agentleFS
charliee1wcharliee1w/consolidation-memory/CLAUDE.md

consolidation-memory

CLAUDE.md8 starsChanged 9 months agoMITView on GitHub

Compact maintainer guide aligned with the codebase. Prioritized blind spots — check this before large refactors; update when fixed. P0 (trust / scope) — addressed 2026-06-13 - ~~Scope on audit APIs~~: contradictions, decay_report, consolidation_log, status use resolved default scope; explicit scope narrows further; global_scope=True for corpus-wide ops view. - ~~content_type validation~~: shared validate_episode_content_type() in types.py. - ~~trust_profile in scoped status()~~: get_claim_trust_stats, count_active_challenged_claims, get_recently_contradicted_topic_ids accept scope. P1 (enforcement / ops) — addressed 2026-06-15 - ~~coding_agent_eval CI gate~~: quick mode in novelty_gates…

  • Installs packages

The file

We split this CLAUDE.md into the rules it gives an agent

4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep semantics aligned across Python, MCP, REST, and OpenAI surfaces.

    line 38
  2. Distinctive:

    Update user-facing docs when behavior changes.

    line 40
  3. Distinctive:

    Avoid hard-coded test counts or stale timeline statements in docs.

    line 41
  4. Very specific:

    Run memory_hygiene_scan on noisy corpora.

    line 73

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

consolidation-memory contributor context

Compact maintainer guide aligned with the codebase.

Repository shape

src/consolidation_memory/
  client.py          orchestration + tool-facing operations
  database.py        backward-compatible facade (re-exports db/)
  db/                SQLite schema/migrations + domain CRUD
  query_service.py   canonical query envelopes
  context_assembler.py  hybrid recall
  claim_graph.py     deterministic claim canonicalization
  drift.py           git-based drift challenge flow
  consolidation/       engine, fast_path, prompting
  schemas.py         OpenAI tools + MCP dispatch

Important facts

  • Package version: pyproject.toml
  • Schema version: database.py (CURRENT_SCHEMA_VERSION)
  • Tool schemas: schemas.py (openai_tools, dispatch_tool_call)

Local verification

pip install -e ".[all,dev]"
python scripts/smoke_builder_base.py
pytest tests/ -q
ruff check src tests/
mypy src/consolidation_memory/

Guardrails

  1. Keep semantics aligned across Python, MCP, REST, and OpenAI surfaces.
  2. Preserve trust invariants (see CONTRIBUTING.md).
  3. Update user-facing docs when behavior changes.
  4. Avoid hard-coded test counts or stale timeline statements in docs.

Known architectural debt (audit 2026-06-15)

Prioritized blind spots — check this before large refactors; update when fixed.

P0 (trust / scope) — addressed 2026-06-13

  • Scope on audit APIs: contradictions, decay_report, consolidation_log, status use resolved default scope; explicit scope narrows further; global_scope=True for corpus-wide ops view.
  • content_type validation: shared validate_episode_content_type() in types.py.
  • trust_profile in scoped status(): get_claim_trust_stats, count_active_challenged_claims, get_recently_contradicted_topic_ids accept scope.

P1 (enforcement / ops) — addressed 2026-06-15

  • coding_agent_eval CI gate: quick mode in novelty_gates job. real_world_eval remains manual (live corpus).
  • embedding_disk_cache cross-process lock: .embedding_cache_write.lock via process_write_lock.py.
  • SECURITY.md + MCP trust boundary: stdio trust model documented; supported line is 0.20.x.
  • Hygiene surface parity: memory_hygiene_scan / memory_hygiene_apply on MCP, REST, OpenAI dispatch, CLI, web UI, desktop.
  • rest.py E402: imports ordered above type aliases.
  • tool_adapter recall parity: shared deferred-knowledge + deadline semantics across MCP/REST/OpenAI.

P2 (structure / tests / adoption) — addressed 2026-06-15

  • ContentType vs RecordType: procedure ingest type added; strategy remains JSON-only at store time (see CONTRIBUTING + FAST_PATH_EPISODES).
  • Global-by-design tools: documented in CONTRIBUTING (scope-aware vs global contract); hygiene + policy admin listed.
  • Migration regression v17–v20: additive tests in tests/test_core.py.
  • Multi-process lock test: tests/test_process_write_lock.py for ProcessWriteLease.
  • database.py god-module: split into db/ domain modules (2026-06-13); database.py remains a thin re-export facade.
  • Positioning vs RAG: examples/trust-vs-rag/ with demo_flow.py.
  • Plugin author guide: docs/PLUGIN_DEVELOPMENT.md.
  • LoCoMo narrative: docs/LOCOMO_BENCHMARK.md (full run needs API key).

Maintainer reminders (not debt)

  • Full MCP profile ships 28 tools; simple profile exposes 3 (memory_recall, memory_remember, memory_ask).
  • forget() expires claims that lose all provenance; consolidated knowledge can lag code — use memory_correct or new episodes + consolidate.
  • Run memory_hygiene_scan on noisy corpora; verify with ruff check src tests/, mypy src/consolidation_memory/, pytest tests/ -q.

Runtime residual (P0-1, mitigated 2026-07-10)

  • Windows SciPy import hang on MCP workers: mitigated by lazy consolidation package export, lightweight status import isolation, main-thread SciPy preload, and bounded MCP tool timeouts. Residual: first consolidate still requires SciPy — preload on main thread / _ensure_scipy_for_consolidate() before worker. Regression: tests/test_import_isolation.py, scripts/smoke_mcp_stdio.py.

Keep (do not rewrite)

  • Episodes → records → claims → topics stack; tool_dispatch seam; FAISS write lease; fast-path before LLM; query_service envelopes.

Core docs

  • README.md
  • docs/ARCHITECTURE.md
  • docs/FAST_PATH_EPISODES.md
  • CONTRIBUTING.md

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.