consolidation-memory 0.15.0

Trust-calibrated working memory for coding agents with provenance, drift awareness, and scoped sharing

consolidation-memory

Trust-calibrated working memory for coding agents.

consolidation-memory is built around a simple stance: claims are the reusable unit, episodes are the raw evidence, and code drift is a first-class reason to distrust stale memory. The system stores episodic events, consolidates them into structured knowledge and claims, and serves the same trust-aware retrieval semantics across Python, MCP, REST, and OpenAI-style tool calls.

Design Philosophy

• Treat the system as a trust layer for coding-agent memory, not a generic blob store.
• Prefer reusable claims with provenance over raw episodic recall.
• Keep uncertainty visible through temporal validity, contradiction history, and drift challenge signals.
• Preserve local-first inspectability: SQLite, FAISS, markdown, and logs should all stay understandable on disk.
• Support shared memory only when scopes and policy make reuse safe.

What It Is And Is Not

consolidation-memory is for:

• coding agents that need durable, inspectable working memory
• teams that want reusable claims without mixing unrelated contexts
• workflows where code changes should automatically reduce trust in older conclusions

consolidation-memory is not trying to be:

• a generic “memory for every AI app” platform
• a replacement for source control, issue trackers, or primary documentation
• a black-box vector store that hides why something was retrieved

Try It In 5 Minutes

pip install "consolidation-memory[fastembed]"
consolidation-memory init
consolidation-memory test
consolidation-memory serve

Pick disabled for the LLM step unless you already have LM Studio, Ollama, or OpenAI configured. That gives you a clean first-run path with local storage, recall, and MCP serving.

What that gives you immediately:

• Durable local storage with SQLite + FAISS
• A health check that validates the runtime end to end
• An MCP server that coding agents can connect to over stdio
• A clean path to REST, OpenAI-style tools, and scoped shared-memory use later

If you want runnable integration snippets instead of docs, start in examples/.

Why It Is Different

Capability	What consolidation-memory does
Local-first persistence	Stores memory on disk in inspectable SQLite, FAISS, markdown, and log artifacts
Claim-first trust layer	Treats claims as the reusable memory unit and episodes as supporting evidence
Trust-aware retrieval	Tracks temporal validity, contradictions, provenance, and claim lifecycle events
Drift-aware knowledge	Maps changed files to anchored claims and challenges impacted knowledge automatically
Shared memory without chaos	Supports namespace/project/app/agent/session scope dimensions with policy controls
Transport parity	Keeps MCP, REST, Python, and OpenAI-style tool semantics aligned
Builder ergonomics	Ships package metadata, release gates, examples, smoke tests, CI, and contributor docs

Architecture At A Glance

flowchart LR
    A["Agent / App"] --> B["MCP / REST / Python / OpenAI tools"]
    B --> C["MemoryClient"]
    C --> D["Canonical query semantics"]
    C --> E["SQLite + knowledge markdown"]
    C --> F["FAISS vector store"]
    C --> G["Claim graph + anchors + drift signals"]
    G --> H["Changed files -> challenged claims"]
    D --> I["Episodes + topics + records + claims"]

More detail lives in docs/ARCHITECTURE.md.

memory_status / MemoryClient.status() also expose a trust_profile so callers can inspect current claim coverage, provenance coverage, anchor coverage, contradiction pressure, and drift-watch posture.

Examples

The repo now keeps runnable or close-to-runnable examples in the root examples/ directory:

• Python quickstart
• REST API client
• Cursor MCP config
• Continue config
• LangGraph memory node
• Plugin hook example

Legacy raw config snippets still exist under docs/examples/.

Backend Support

consolidation-memory supports both fully local and hosted setups.

Layer	Supported backends	Recommended default	Local-only option
Embeddings	fastembed, lmstudio, openai, ollama	fastembed	fastembed, lmstudio, ollama
LLM consolidation	lmstudio, openai, ollama, disabled	lmstudio	lmstudio, ollama, disabled

See docs/MODEL_SUPPORT.md for the full matrix, defaults, and install notes.

Privacy And Trust

• No built-in telemetry.
• Data is stored locally under platformdirs.user_data_dir("consolidation_memory").
• Network calls only go to the embedding and LLM backends you configure.
• REST auth is required before non-loopback binds.
• The repo ships with tests, smoke checks, release gates, lint, type checks, and security scanning.

Install

pip install "consolidation-memory[fastembed]"

Common extras:

• consolidation-memory[rest] for FastAPI endpoints
• consolidation-memory[fastembed,rest] for the default local REST setup
• consolidation-memory[dashboard] for the Textual dashboard
• consolidation-memory[openai] for the OpenAI SDK backend
• consolidation-memory[all,dev] for full local development

Quick Start

consolidation-memory init
consolidation-memory test
consolidation-memory serve

consolidation-memory with no subcommand defaults to serve.

CLI Commands

serve            Start MCP server (default command)
serve --rest     Start REST API
init             Interactive setup
test             End-to-end health check
status           Runtime/system stats
consolidate      Trigger consolidation run
detect-drift     Challenge claims impacted by changed files
export           Export full snapshot JSON
import PATH      Import snapshot JSON
reindex          Rebuild vectors with current embedding backend
browse           Browse knowledge topics
setup-memory     Add reusable memory instructions to an agent file
dashboard        Launch Textual dashboard

MCP Setup

{
  "mcpServers": {
    "consolidation_memory": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "consolidation_memory", "--project", "default", "serve"],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "CONSOLIDATION_MEMORY_IDLE_TIMEOUT_SECONDS": "900"
      }
    }
  }
}

Prefer an exact Python interpreter over the consolidation-memory console script. It avoids PATH and env drift and is more reliable on Windows when MCP hosts restart the server.

The stdio MCP server now enforces one live server per parent process and project, and the recommended idle timeout is 900 seconds so leaked hosts self-clean instead of accumulating indefinitely. Set CONSOLIDATION_MEMORY_IDLE_TIMEOUT_SECONDS=0 only if you explicitly need a never-exit server.

MCP tools exposed by server.py:

• memory_store
• memory_recall
• memory_store_batch
• memory_search
• memory_claim_browse
• memory_claim_search
• memory_detect_drift
• memory_status
• memory_forget
• memory_export
• memory_correct
• memory_compact
• memory_consolidate
• memory_consolidation_log
• memory_decay_report
• memory_protect
• memory_timeline
• memory_contradictions
• memory_browse
• memory_read_topic

Python Example

from consolidation_memory import MemoryClient

with MemoryClient(auto_consolidate=False) as mem:
    mem.store(
        "User prefers short PR summaries with concrete file paths.",
        content_type="preference",
        tags=["workflow", "reviews"],
    )

    result = mem.recall(
        "how should I format PR summaries?",
        n_results=5,
        include_knowledge=True,
    )

    print(len(result.episodes), len(result.knowledge), len(result.records), len(result.claims))

REST API

Run:

pip install "consolidation-memory[fastembed,rest]"
consolidation-memory serve --rest --host 127.0.0.1 --port 8080

For non-loopback binds (for example --host 0.0.0.0), set auth first:

export CONSOLIDATION_MEMORY_REST_AUTH_TOKEN="change-me"
consolidation-memory serve --rest --host 0.0.0.0 --port 8080

$env:CONSOLIDATION_MEMORY_REST_AUTH_TOKEN = "change-me"
consolidation-memory serve --rest --host 0.0.0.0 --port 8080

When auth is enabled, send Authorization: Bearer <token> on all endpoints except /health.

Endpoints:

• GET /health
• POST /memory/store
• POST /memory/store/batch
• POST /memory/recall
• POST /memory/search
• POST /memory/claims/browse
• POST /memory/claims/search
• POST /memory/detect-drift
• GET /memory/status
• DELETE /memory/episodes/{episode_id}
• POST /memory/consolidate
• POST /memory/correct
• POST /memory/export
• POST /memory/compact
• GET /memory/browse
• GET /memory/topics/{filename}
• POST /memory/timeline
• POST /memory/contradictions
• POST /memory/protect
• POST /memory/consolidation-log
• GET /memory/decay-report

OpenAI-Compatible Tools

Use:

• consolidation_memory.schemas.openai_tools
• consolidation_memory.schemas.dispatch_tool_call

This keeps tool definitions and dispatch behavior aligned with the same semantics used by MCP and REST.

Scope Model (Compatibility + Shared Use)

By default, existing single-project usage still works.

When a scope envelope is provided, records are persisted with explicit scope dimensions:

• namespace_*
• project_*
• app_client_*
• agent_*
• session_*

This allows selective sharing without mixing unrelated contexts.

Optional scope.policy controls:

• read_visibility: private (default), project, namespace
• write_mode: allow (default), deny

Persisted ACL entities are also supported (access_policies, policy_principals, policy_acl_entries). When persisted ACL rows match the resolved scope and principal, they are authoritative over scope.policy. Conflict rules: write deny overrides allow; read visibility resolves to the most restrictive level.

Storage Layout

Data is under platformdirs.user_data_dir("consolidation_memory")/projects/<project>/.

memory.db
faiss_index.bin
faiss_id_map.json
faiss_tombstones.json
.faiss_reload
knowledge/
knowledge/versions/
consolidation_logs/
backups/

Configuration

Config file discovery:

1. CONSOLIDATION_MEMORY_CONFIG
2. Platform default config path
3. Built-in defaults

Every scalar field can be overridden with CONSOLIDATION_MEMORY_<FIELD_NAME>.

Examples:

CONSOLIDATION_MEMORY_PROJECT=work
CONSOLIDATION_MEMORY_EMBEDDING_BACKEND=fastembed
CONSOLIDATION_MEMORY_LLM_BACKEND=ollama
CONSOLIDATION_MEMORY_CONSOLIDATION_INTERVAL_HOURS=6

Documentation Map

• Architecture
• Builder Baseline
• Model Support
• Release Gates
• Release Automation
• Novelty Metrics
• Novelty Eval Guide
• External Review Playbook
• Recommended Agent Instructions
• Universal-memory strategy docs

Development

git clone https://github.com/charliee1w/consolidation-memory
cd consolidation-memory
pip install -r requirements-dev.txt
python scripts/smoke_builder_base.py
pytest tests/ -q
pytest tests/ -q -W error::ResourceWarning
ruff check src/ tests/
mypy src/consolidation_memory/
bandit -q -r src scripts

Community

• Contributors: CONTRIBUTORS.md
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Releases: GitHub Releases

License, Etc.

Project policies:

• Security
• Contributing
• Code of Conduct

MIT