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
In this repository4 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- .cursor/rules/consolidation-memory.mdcCursor rule
- releaseSkill
- reviewSkill
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
- Distinctive: line 38
Keep semantics aligned across Python, MCP, REST, and OpenAI surfaces.
- Distinctive: line 40
Update user-facing docs when behavior changes.
- Distinctive: line 41
Avoid hard-coded test counts or stale timeline statements in docs.
- Very specific: line 73
Run memory_hygiene_scan on noisy corpora.
≈ “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.
Files
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 dispatchImportant 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
- Keep semantics aligned across Python, MCP, REST, and OpenAI surfaces.
- Preserve trust invariants (see CONTRIBUTING.md).
- Update user-facing docs when behavior changes.
- 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,statususe resolved default scope; explicitscopenarrows further;global_scope=Truefor corpus-wide ops view.: sharedcontent_typevalidationvalidate_episode_content_type()intypes.py.:trust_profilein scopedstatus()get_claim_trust_stats,count_active_challenged_claims,get_recently_contradicted_topic_idsacceptscope.
P1 (enforcement / ops) — addressed 2026-06-15
:coding_agent_evalCI gatequickmode innovelty_gatesjob.real_world_evalremains manual (live corpus).:embedding_disk_cachecross-process lock.embedding_cache_write.lockviaprocess_write_lock.py.: stdio trust model documented; supported line isSECURITY.md+ MCP trust boundary0.20.x.Hygiene surface parity:memory_hygiene_scan/memory_hygiene_applyon MCP, REST, OpenAI dispatch, CLI, web UI, desktop.: imports ordered above type aliases.rest.pyE402: shared deferred-knowledge + deadline semantics across MCP/REST/OpenAI.tool_adapterrecall parity
P2 (structure / tests / adoption) — addressed 2026-06-15
:ContentTypevsRecordTypeprocedureingest type added;strategyremains 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 intests/test_core.py.Multi-process lock test:tests/test_process_write_lock.pyforProcessWriteLease.: split intodatabase.pygod-moduledb/domain modules (2026-06-13);database.pyremains a thin re-export facade.Positioning vs RAG:examples/trust-vs-rag/withdemo_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 — usememory_corrector new episodes + consolidate.- Run
memory_hygiene_scanon noisy corpora; verify withruff 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
consolidationpackage export, lightweightstatusimport 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_dispatchseam; FAISS write lease; fast-path before LLM;query_serviceenvelopes.
Core docs
- README.md
- docs/ARCHITECTURE.md
- docs/FAST_PATH_EPISODES.md
- CONTRIBUTING.md
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
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.

