convez.ai
MCP ServerAutomaçãoAvançado
charliee1w

Consolidation Memory

charliee1w/consolidation-memory

Memória de trabalho drift-aware com consolidação de episódios e claims para agentes de IA

Ver no GitHub
BomPluginScore · de 0 a 100

Memória persistente local-first para agentes de IA que armazena, recupera e consolida conhecimento entre sessões usando FAISS, SQLite e qualquer LLM. MCP server especializado em agentes de codificação com suporte a drift-awareness, provenance explícita e sinais de confiança calibrados.

Instalação

$npx convez-ai charliee1w/consolidation-memory

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
8
Forks
3
Acompanhando
1
Saúde
100%
Último commit
há 4 meses
Versão
v0.20.3
Issues abertas
2
Contribuidores
3

Casos de uso

  • Agentes de codificação com memória persistente entre sessões
  • Rastreamento de fixes, soluções e decisões arquiteturais com provenance
  • Recall inteligente com sinais de confiança e degradação graceful após refatorações

Veredito

Solução técnica madura e bem-archittetada para o problema real de memória em agentes de longa duração. Foco em drift-awareness e provenance ao invés de similarity search opaco é diferencial legítimo; implementação robuusta com SQLite+FAISS+markdown, mas requer domínio conceitual de episódios/claims para máximo valor.

README

A tradução para o português deste README ainda está na fila.

consolidation-memory

PyPI GitHub Release CI Python License

Trust-calibrated working memory for coding agents.

Store what happened. Consolidate what you learned. Recall with provenance — and lower trust when the repo moves on.

consolidation-memory is local-first agent memory built for long-horizon coding work: SQLite + FAISS + markdown topics on disk, one semantic contract across Python, MCP, REST, and OpenAI-style tools, and explicit trust signals instead of opaque similarity search.


At a glance

Typical agent memoryconsolidation-memory
Unit of reuseEmbedded chat snippetsClaims — hash-stable beliefs with provenance
Raw inputSame blob as retrievalEpisodes — evidence kept separate from beliefs
StalenessHidden until wrongDrift challenge when anchored files change
TimePresent-tense onlyas_of queries for prior belief states
SharingHope the filter worksScope envelopes + persisted policy/ACL primitives
ConsolidationAlways calls an LLMFast path for structured episodes; LLM only for residue

Focus: drift-aware debugging memory — preserve fixes, recall with trust signals, degrade gracefully after refactors.


Mental model

claims are the reusable unit; episodes are the raw evidence behind them.

  Episode                 Evidence from a session (chat, tool output, structured JSON)
      │
      ▼ consolidation
  Knowledge record        Typed fact · solution · preference · procedure · strategy
      │
      ▼ deterministic materialization
  Claim                   Reusable belief + sources + lifecycle events
      │
      ▼ human-readable view
  Topic                   Markdown file + DB rows you can open and audit

Contradictions, challenges, and expiry stay visible. The system does not silently overwrite uncertain beliefs.

flowchart TB
  subgraph ingest["Ingest"]
    E["Episodes"]
    A["File / path anchors"]
  end

  subgraph consolidate["Consolidate"]
    C["Cluster by embedding + scope"]
    FP["Fast path — no LLM"]
    LLM["LLM extraction — unstructured residue"]
    R["Knowledge records"]
    CL["Claims + edges + events"]
  end

  subgraph recall["Recall"]
    H["Hybrid search — FAISS + FTS + trust ranking"]
    T["Temporal filter — as_of"]
    S["Scope + policy filter"]
  end

  subgraph trust["Trust maintenance"]
    D["Git drift → challenge claims"]
    X["Contradiction log"]
    P["Precision + outcome signals"]
  end

  E --> C
  A --> E
  C --> FP
  C --> LLM
  FP --> R
  LLM --> R
  R --> CL
  CL --> H
  E --> H
  H --> T
  T --> S
  D --> CL
  X --> CL
  P --> CL

Deep dive: Architecture


Capabilities

Hybrid recall

Semantic vectors (FAISS), keyword fallback (FTS5 when available), and metadata-aware ranking across episodes, topics, records, and claims. Responses can include uncertainty, contradiction context, strategy evidence, and scope attribution.

Consolidation with a deterministic fast path

Related episodes cluster by embedding similarity with scope isolation. Structured episodes consolidate without LLM calls when they match fast-path shapes; everything else falls back to your configured LLM backend (or fails clearly when llm.backend = "disabled").

Drift-aware trust

detect_drift maps git changes → file anchors → impacted claims → auditable code_drift_detected events. Stale debugging conclusions lose precision instead of masquerading as fresh facts.

Temporal correctness

Query what was believed at a point in time with as_of on recall and claim search — useful after refactors, rollbacks, or postmortems.

Scoped sharing

Namespace, project, app, agent, and session columns persist on memory rows. Policy and ACL tables support intentional sharing without accidental cross-project leakage. Details: Architecture — scope.

Adaptive scheduling

A utility scheduler weighs backlog pressure, recall misses, contradiction spikes, challenged claims, and failed action outcomes. memory_status exposes utility_scheduler.run_decision.explanation, fast_path_hits, llm_fallbacks, and trust_profile so automation is inspectable, not magical.

Surface parity

Every transport routes through MemoryClient and shared query semantics — no “MCP-only” behavior drift.

SurfaceEntry
Pythonfrom consolidation_memory import MemoryClient
MCPconsolidation-memory serve / python -m consolidation_memory serve
RESTconsolidation-memory serve-rest (optional [rest] extra)
OpenAI toolsschemas.openai_tools + dispatch_tool_call

Quick start

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

During init, choose disabled for the LLM backend unless you already run LM Studio, Ollama, or OpenAI. You still get durable storage, hybrid recall, drift detection, and MCP serving.

Optional extras

ExtraEnables
[fastembed]Local embeddings (recommended default)
[openai]Hosted OpenAI embeddings / LLM
[rest]FastAPI HTTP server
[dashboard]Textual TUI inspector
[desktop]Native desktop UI with system tray icon (consolidation-memory app)
[all,dev]Full stack + test/lint tooling

Backend matrix: Model support · Runnable wiring: examples/


Connect your agent (MCP)

Use an absolute Python path — more reliable than a console script, especially on Windows:

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

consolidation-memory init prints the full recommended env (timeouts, warmup, lightweight status). Drop-in configs: Cursor · Continue

Simple profile (3 of 28 full-profile tools): add "CONSOLIDATION_MEMORY_MCP_TOOL_PROFILE": "simple" to env — exposes memory_recall, memory_remember, and memory_ask only.

MCP tools (representative)

ToolPurpose
memory_store / memory_store_batchPersist episodes with type, tags, scope
memory_recallHybrid recall over episodes, topics, records, claims
memory_searchPlain-text search (non-semantic)
memory_claim_search / memory_claim_browseClaim-centric retrieval
memory_detect_driftGit-based claim challenge
memory_consolidateRun consolidation on demand
memory_statusHealth, scheduler, trust_profile, fast-path metrics
memory_timeline / memory_contradictionsAudit lifecycle and conflicts
memory_export / memory_correctBackup and human corrections
memory_hygiene_scan / memory_hygiene_applyNoisy-episode scan and orphan-claim cleanup
memory_outcome_record / memory_outcome_browseLink actions to outcomes

Full schemas: src/consolidation_memory/schemas.py


Python API

from consolidation_memory import MemoryClient

with MemoryClient(auto_consolidate=False) as mem:
    mem.store(
        "Prefer PR summaries with concrete file paths, not high-level narration.",
        content_type="preference",
        tags=["workflow", "reviews"],
    )
    result = mem.recall("how should I format PR summaries?", n_results=5)
    print(result.episodes, result.claims)

Challenge stale beliefs after code changes:

report = mem.detect_drift()
print(report.challenged_claim_ids)

Inspect trust and scheduler state:

status = mem.status()
print(status["trust_profile"])
print(status["utility_scheduler"]["run_decision"]["explanation"])

LLM-optional consolidation

Set llm.backend = "disabled" and store episodes in fast-path shapes — preferences, path-anchored solutions, JSON facts/procedures/strategies. Consolidation stays deterministic; unstructured residue simply does not consolidate until you enable an LLM.

memory_status reports extraction mix (fast_path_hits, llm_fallbacks), consolidation quality aggregates, and why the scheduler would run next.


Who this is for

Good fit

  • Developers using Cursor, Claude Code, Continue, or custom agents on real repositories
  • Teams that need durable agent memory with explicit scope boundaries
  • Workflows where file changes should reduce trust in prior conclusions
  • Builders who want inspectable on-disk artifacts, not a hosted black box

Not a fit

  • Generic “remember everything” consumer assistants
  • Replacing git, issue trackers, or canonical product docs
  • Opaque vector RAG with no provenance story

Privacy and data

  • No built-in telemetry.
  • Default data dir: platformdirs.user_data_dir("consolidation_memory")/projects/<project>/
  • Network I/O only to embedding/LLM backends you configure.
  • REST binds require auth before non-loopback exposure.

Documentation

DocWhy read it
ArchitectureModules, persistence, data flow
Fast-path episodesLLM-free consolidation shapes
Model supportEmbedding and LLM backends
ExamplesCursor, REST, LangGraph, plugins
Trust vs RAGSame bug twice — recall + drift challenge demo
Plugin developmentHook surface and author guide
LoCoMo benchmarkExternal memory comparison harness

Contributors: see CONTRIBUTING.md.


Community

MIT · Code of Conduct

Ver o original no GitHub

Bom para

Relacionados