Mnemo MCP
seslak/mnemo-mcp
Memória de projeto local para agentes de código com SQLite e busca inteligente
Ver no GitHubServidor MCP local-first que fornece memória persistente e estruturada para agentes de IA, armazenando decisões, logs, contexto e conhecimento do projeto em SQLite. Implementa busca inteligente com deduplificação, consolidação e exportação em múltiplos formatos (JSON, JSONL, Markdown) sem dependência de serviços externos.
Instalação
npx convez-ai seslak/mnemo-mcp1 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
Casos de uso
- Manter contexto persistente de projetos entre sessões de agentes
- Armazenar decisões, abordagens falhadas e feedback de especialistas
- Indexar e recuperar conhecimento do projeto sem crescimento automático de tokens
- Exportar histórico de memória em formatos legíveis (Markdown, JSON)
Veredito

Solução robusta e bem pensada para memória persistente em agentes de IA, com foco em eficiência local e controle de crescimento de contexto. Recomendado para projetos que precisam de memória estruturada sem overhead de serviços externos, embora exija integração técnica e Python 3.10+.
README
A tradução para o português deste README ainda está na fila.
Mnemo MCP
Local-first project memory for MCP-capable coding agents.
Mnemo is a small stdio MCP server that gives coding agents a durable, project-scoped memory substrate. It stores decisions, interaction logs, context blocks, durable project knowledge, specialist feedback, useful commands, paths, failed approaches, and test results across sessions.
Mnemo is a local project hippocampus: store broadly, index locally, recall narrowly, export readably, compact aggressively.
Status
Current version: 0.22.0
Runtime requirements:
- Python 3.10+
- Standard library only
- SQLite-first local storage
- Optional: local
agent-salienceviaAGENT_SALIENCE_HOMEor normal Python import - CI compatibility matrix enforces parse/test coverage on Python
3.10,3.11,3.12,3.13
Mnemo is local-first. It does not require a cloud service, vector database, external database server, or package install.
What Mnemo provides
- Local SQLite project memory by default
- JSON import/export compatibility for older
memory.jsonfiles - JSONL and Markdown exports for human inspection
- Bounded search and recall so memory growth does not automatically become token growth
- Structured memory layers for agentic systems
- Signature-at-write-time duplicate detection and consolidation support
- Candidate-based consolidation by default, with full O(n²) scan gated behind explicit confirmation
- Maintenance actions for log compaction, consolidation, JSON import, signature backfill, and alias proposal analysis
- Git-aware memory metadata on new writes (
git_sha,git_branch,git_dirty) with touched-file tracking - Freshness-aware retrieval multiplier in SQLite mode for file-linked memories
- Memory Packs for scripted
.memexport, inspect, import, review, and promotion workflows - Group-first runtime selection support (
memory_group_discover,memory_group_preview), including active alias concept groups - Landing-folder pack listing for import UX (
pack_landing_list) - Local-HMAC pack signing and trusted import controls (
signer_add,signer_list,signer_disable,signer_enable) - Direct group selectors for pack preview, redaction preview, and export (
group_id+scope) - Alias proposal admission based on continuous IDF strength, with duplicate-heavy IDF profiles handled by unique-value cutoffs
- Scripted Copilot prompt workflows for Memory Pack export, import, promotion, and list/select compatibility under
.github/prompts/ - A single Copilot-friendly gateway MCP tool:
mnemo - Optional deterministic salience diagnostics
- Automatic local IDF activation when project/domain corpus maturity thresholds are met
- Lightweight symbol lookup under a configured workspace root
Non-goals
Mnemo is not:
- an agent framework
- a hosted memory service
- a vector database
- a secrets manager
- a replacement for tests or source control
Git-aware memory (0.13.5)
New memory writes in SQLite mode attempt to capture repository context:
git_sha(HEAD commit)git_branch(current branch)git_dirty(1when working tree has local changes, else0)
When record receives touched_files, Mnemo records per-file digests in memory_files:
- preferred: git blob SHA at
HEAD:path - fallback: current file digest from
git hash-object(or BLAKE2b-128 bytes digest when git hashing is unavailable)
Retrieval applies a post-score freshness multiplier:
git_shaisNULL(legacy or non-git write):1.0- all touched files unchanged:
1.0 - any touched file changed but still present:
0.7 - any touched file missing/deleted/renamed away:
0.3 - mixed file states: minimum multiplier wins
Safety and compatibility:
- Non-git folders and git command failures are non-fatal.
- No backfill is performed for legacy rows.
- Legacy rows remain neutral (
1.0) to preserve prior retrieval behavior.
Memory Packs
Memory Packs are portable .mem artifacts for moving selected Mnemo memories between local environments.
A normal pack lifecycle is:
export -> .mem file
import -> staged rows in imported_pack_rows
promote -> regular local rows in memories
Key runtime actions:
memory_group_discoverandmemory_group_previewdiscover exportable memory groups.pack_previewpreviews a selector before export.pack_redaction_previewchecks the export selection for baseline sensitive patterns.pack_exportcreates a.memfile. The public suffix is.mem; the internal container is ZIP.pack_landing_listlists.memfiles from the configured landing folder.pack_inspectvalidates and summarizes a pack before import.pack_importstages pack rows for review inimported_pack_rows.pack_review_importsummarizes staged imported rows.pack_promote_previewpreviews materialization of staged rows into local memory.pack_promotecreates regular local memories after explicit approval.signer_add,signer_list,signer_disable, andsigner_enablemanage local-HMAC signing metadata.
Pack import is intentionally staged. Imported rows are not regular local memories until promotion. Promotion is explicit and approval-gated.
The repository also includes scripted Copilot prompt workflows:
.github/prompts/mnemo.memory-pack-export.prompt.md.github/prompts/mnemo.memory-pack-import.prompt.md.github/prompts/mnemo.memory-pack-promote.prompt.md.github/prompts/mnemo.memory-list-select.prompt.md(compatibility stub that points to export)
Security and provenance notes:
.memfiles can contain project-sensitive memory text and metadata.content/file_fingerprints.jsonrecords touched-file paths and hashes; it does not embed file contents.- Local-HMAC signing is a local integrity/trust workflow, not public-key identity or non-repudiation.
Repository layout
mnemo-mcp/
├── server.py
├── salience_loader.py
├── git_context.py
├── memory.example.json
├── smoke_test.py
├── test_server.py
├── benchmark_consolidation.py
├── .github/
│ ├── prompts/
│ └── workflows/
├── examples/
├── docs/
├── CHANGELOG.md
└── README.md
Quick start
Point your MCP client at server.py.
Example VS Code MCP config when Mnemo is checked out as mnemo-mcp/ inside your workspace:
{
"servers": {
"mnemo": {
"type": "stdio",
"command": "python",
"args": ["${workspaceFolder}/mnemo-mcp/server.py"],
"env": {
"MNEMO_STORE": "sqlite",
"MNEMO_WORKSPACE_ROOT": "${workspaceFolder}",
"MNEMO_FILE": "${workspaceFolder}/state/mnemo/memory.json",
"MNEMO_SQLITE_FILE": "${workspaceFolder}/state/mnemo/mnemo.sqlite"
}
}
}
}
More example configs are in examples/.
MCP gateway model
Mnemo exposes exactly one public MCP tool:
mnemo
Call it with an action and optional params object:
{"action":"record","params":{"kind":"decision","text":"Run validation commands before handoff."}}
This gateway model keeps the MCP surface small for clients with tool-inventory limits while preserving the full Mnemo feature set.
Gateway actions
Supported top-level actions:
doctorsearchsalience_checkpack_previewpack_redaction_previewpack_exportpack_inspectpack_importpack_list_importspack_review_importpack_promote_previewpack_promotesigner_addsigner_listsigner_disablesigner_enablerecordalias_hintlinkrecallgetexportupdatedeleterecentrecent_eventssearch_eventsget_eventmemory_eventscompact_contextinspectmaintenancebackfill_signaturesconsolidate_fulllookup_symbol
backfill_signatures and consolidate_full are also available as top-level aliases. Alias lifecycle actions are available as maintenance sub-actions.
Event history actions
{"action":"recent_events","params":{"limit":20}}
{"action":"search_events","params":{"query":"IBAN validation","limit":20}}
{"action":"get_event","params":{"event_id":"evt_..."}}
{"action":"memory_events","params":{"memory_id":"mem_...","limit":50}}
doctor
Returns storage, schema, health, export, FTS, salience, and IDF diagnostics.
{"action":"doctor"}
In SQLite mode, use doctor to verify backend, sqlite_file_exists, sqlite_size_bytes, memory_count, newest_memory, fts, signature warnings, and idf activation status.
record
Records a project memory of any supported kind.
{"action":"record","params":{"kind":"decision","text":"Run validation commands before handoff.","source":"team note","tags":["validation"],"pinned":true}}
Structured aliases are accepted by the generic record action:
{"action":"record","params":{"kind":"interaction_log","summary":"Session handoff and active constraints.","role":"coordinator","agent_id":"coord_1"}}
{"action":"record","params":{"kind":"context_block","body":"Expanded implementation context.","title":"Handoff block","linked_ids":["mem_log_id"]}}
{"action":"record","params":{"kind":"hippocampus_entry","text":"Always run validation before release handoff.","evidence_ids":["mem_log_id"],"domain":"release"}}
{"action":"record","params":{"kind":"agent_feedback","text":"Prefer middleware-first auth checks.","feedback_type":"good_pattern","agent_id":"spec_auth","domain":"auth"}}
search
Searches project memory with bounded output.
{"action":"search","params":{"query":"validation commands before handoff","limit":5,"phase":"implementation","max_tokens":2000}}
Search-like actions (search, recall, and salience_check) emit miss-aware query events:
- miss when
result_count == 0ortop_score < MNEMO_MISS_TOP_SCORE_THRESHOLD - typed event fields include
result_count,success, andtop_score - miss events are marked
include_in_salience=1for downstream alias analysis
recall
Returns startup or specialist recall bundles.
{"action":"recall","params":{"mode":"startup","role":"coordinator","agent_id":"coord_1","query":"release handoff","recent_logs":20}}
{"action":"recall","params":{"mode":"agent","agent_id":"spec_auth","role":"specialist","domain":"auth","task":"review auth middleware"}}
alias_hint
Records explicit alias evidence linking failed wording to successful canonical wording.
{"action":"alias_hint","params":{"domain":"agentic","canonical":"memory recall pipeline","candidate_alias":"hippocampus bridge","original_query":"hippocampus bridge","successful_query":"memory recall pipeline","confidence":"high","include_in_salience":true}}
get
Retrieves one memory by id. Use this when a search/recall preview is not enough.
{"action":"get","params":{"id":"mem_123","full":true}}
link
Links two memory records.
{"action":"link","params":{"source_id":"mem_log","target_id":"mem_block","relation":"expands","bidirectional":true}}
export
Writes readable exports.
{"action":"export","params":{"format":"jsonl"}}
{"action":"export","params":{"format":"hippocampus_markdown"}}
Default outputs go under state/mnemo/exports/.
compact_context
Builds a prompt-ready memory context block.
{"action":"compact_context","params":{"query":"change the auth flow","limit":8,"phase":"implementation","max_tokens":2000}}
maintenance
Maintenance sub-actions:
compact_logsconsolidateconsolidate_fullimport_jsonbackfill_signaturespropose_aliaseslist_alias_proposalsapprove_aliasreject_alias_proposallist_aliasesdisable_aliasdisable_alias_concept
Examples:
{"action":"maintenance","params":{"action":"backfill_signatures","dry_run":true}}
{"action":"maintenance","params":{"action":"consolidate","dry_run":true,"max_candidates_per_memory":100}}
{"action":"maintenance","params":{"action":"consolidate_full","confirm_full_scan":true,"dry_run":true}}
{"action":"maintenance","params":{"action":"propose_aliases","window_days":30,"min_recurrence":3,"include_hints":true,"dry_run":true}}
The default consolidate action is candidate-based. The O(n²) full scan is only available through consolidate_full with confirm_full_scan:true.
propose_aliases supports dry run and persistence:
dry_run=true: returns proposals but does not persistdry_run=false: persists pending proposals in SQLite (alias_proposals,alias_proposal_events)
{"action":"maintenance","params":{"action":"list_alias_proposals","status":"pending","domain":"agentic","limit":50}}
{"action":"maintenance","params":{"action":"approve_alias","proposal_id":"alias-prop-...","approved_by":"coordinator"}}
{"action":"maintenance","params":{"action":"reject_alias_proposal","proposal_id":"alias-prop-...","reason":"generic wording"}}
Top-level maintenance aliases
For discoverability, these can also be called directly:
{"action":"backfill_signatures","params":{"dry_run":false}}
{"action":"consolidate_full","params":{"confirm_full_scan":true,"dry_run":true}}
inspect
Inspects history and related memories.
{"action":"inspect","params":{"id":"mem_123","mode":"both","limit":50,"depth":2,"include_archive":true}}
lookup_symbol
Finds likely source definition locations under MNEMO_WORKSPACE_ROOT.
{"action":"lookup_symbol","params":{"name":"authenticate","limit":10}}
salience_check
Optional deterministic salience diagnostics when Agent Salience is available. When local IDF profiles are active, salience_check automatically uses IDF-dominant scoring.
{"action":"salience_check","params":{"text":"auth middleware decisions","limit":5,"candidate_limit":500,"max_scored":100}}
salience_check is candidate-limited. In SQLite mode it uses FTS when available, then signature overlap, and scores only bounded survivors. Candidate generation is unchanged in this patch.
When IDF is active, Mnemo uses IDF-dominant weights:
idf_cosine: 0.55idf_jaccard: 0.35cosine: 0.05jaccard: 0.05
The added idf_jaccard (weighted Jaccard/Tanimoto using corpus IDF weights) suppresses common-word overlap false positives. When IDF is cold/off/unavailable, lexical scoring remains active.
Local storage
Mnemo uses SQLite by default.
state/mnemo/
├── mnemo.sqlite # primary store in SQLite mode
├── memory.json # legacy/import/export compatibility path
└── exports/
├── memory.jsonl
├── hippocampus.md
├── agent_feedback.md
└── startup_context_latest.md
memory.json is not the primary store when MNEMO_STORE=sqlite; it is retained as an import/export compatibility format.
Signature-at-write-time
Mnemo stores deterministic signatures when memories are recorded, imported, or backfilled:
content_hash: blake2b digest of full raw text after stable line-ending normalizationnormalized_hash: blake2b digest of normalized tokens joined with spacestoken_countunique_token_counttop_terms_json: top 32 terms by frequency, ties alphabeticallyshingle_hashes_json: sorted min-K word-shingle hashes, capped at 256signature_versionnormalizer_versionsignature_updated_at
content_hash covers the full text. Token-based signatures are capped at MAX_SIGNATURE_TEXT_CHARS = 50,000 characters to avoid runaway tokenization on pasted logs or huge dumps. Raw stored text is unaffected.
Similarity policy:
jaccard([], []) = 0.0
Empty-empty means no signal, not semantic identity. Tiny texts may match exact hashes but are skipped by shingle-based near-duplicate detection.
Memory growth and token cost
The store can grow locally without automatically increasing token usage. Search and recall return bounded previews. Full bodies are loaded by id through action="get".
Structured memory layers
Mnemo uses neutral, reusable memory kinds:
interaction_log: short continuity notes from recent workcontext_block: larger linked memory artifactshippocampus_entry: durable project/system knowledgeagent_feedback: feedback scoped to anagent_id,role, ordomain
Mnemo does not hardcode personal agent names. Use metadata fields such as agent_id, role, scope, domain, authority, retention, confidence, linked_ids, parent_id, and source_run_id.
Environment variables
| Variable | Description |
|---|---|
MNEMO_STORE | Storage backend: sqlite or json. Default: sqlite. |
MNEMO_FILE | Compatibility/import/export path for memory.json. Default: <workspace>/state/mnemo/memory.json. |
MNEMO_SQLITE_FILE | SQLite path when MNEMO_STORE=sqlite. Default: <workspace>/state/mnemo/mnemo.sqlite. |
MNEMO_WORKSPACE_ROOT | Workspace root for lookup_symbol. Default: current working directory. |
MNEMO_MAX_MEMORIES | Total memory cap including retired entries. Default: 5000. |
MNEMO_MAX_SEARCH_RESULTS | Server-side cap for search results. Default: 20. |
MNEMO_MAX_RECENT_RESULTS | Server-side cap for recent results. Default: 50. |
MNEMO_MAX_CHARS_PER_ITEM | Per-item preview cap for search/recall/get preview mode. Default: 1200. |
MNEMO_MAX_TOTAL_CHARS | Total preview cap for bundled search/recall output. Default: 12000. |
MNEMO_DECAY | Set to 0 to disable time-decay scoring. Default: 1. |
MNEMO_LOG_EVENTS | In JSON mode, set to 0 to disable events.jsonl. In SQLite mode, lifecycle events are stored in SQLite. Default: 1. |
MNEMO_LOG_QUERIES | In JSON mode, set to 0 to disable queries.jsonl. In SQLite mode, query events are stored in SQLite. Default: 1. |
MNEMO_LOG_ARCHIVE | Set to 0 to disable permanent archiving of rotated query/event logs. Default: 1. |
MNEMO_CONSOLIDATE_THRESHOLD | Near-duplicate consolidation threshold. Default: 0.7. |
MNEMO_MISS_TOP_SCORE_THRESHOLD | Miss threshold used by search-like event tagging. Default: 0.15. |
MNEMO_SYMBOL_TTL_SECONDS | Symbol-index walk TTL. Default: 5. |
MNEMO_MAX_FILES_SCANNED | Max files scanned by lookup_symbol. Default: 5000. |
MNEMO_MAX_TOTAL_BYTES | Max total bytes scanned by lookup_symbol. Default: 52428800. |
MNEMO_MAX_FILE_BYTES | Max single file bytes read by lookup_symbol. Default: 1048576. |
MNEMO_IDF_MODE | auto, off, or force. Default: auto. |
MNEMO_IDF_MIN_DOCUMENTS | Project IDF minimum documents. Default: 200. |
MNEMO_IDF_MIN_UNIQUE_TERMS | Project IDF minimum unique terms. Default: 1000. |
MNEMO_IDF_MIN_TOTAL_TOKENS | Project IDF minimum total tokens. Default: 10000. |
MNEMO_IDF_DOMAIN_MIN_DOCUMENTS | Domain IDF minimum documents. Default: 50. |
MNEMO_IDF_DOMAIN_MIN_UNIQUE_TERMS | Domain IDF minimum unique terms. Default: 300. |
MNEMO_IDF_DOMAIN_MIN_TOTAL_TOKENS | Domain IDF minimum total tokens. Default: 3000. |
MNEMO_IDF_MIN_TEXT_TOKENS | Minimum tokens per memory included in IDF corpus. Default: 5. |
MNEMO_ALIAS_MIN_IDF_STRENGTH | Minimum continuous IDF strength required for alias proposals. Default: 0.30. |
AGENT_SALIENCE_HOME | Optional path to local agent-salience checkout. |
MNEMO_MCP_PROFILE is ignored. Mnemo always exposes one public gateway tool.
Salience / IDF / LSH
Mnemo stores deterministic signature fields (signature_version, normalizer_version, shingle_hashes_json, hashes, token counts, and top terms) and automatically builds local project/domain IDF profiles when corpus maturity thresholds are met.
Defaults:
MNEMO_IDF_MODE=autoMNEMO_IDF_MIN_DOCUMENTS=200MNEMO_IDF_MIN_UNIQUE_TERMS=1000MNEMO_IDF_MIN_TOTAL_TOKENS=10000MNEMO_IDF_DOMAIN_MIN_DOCUMENTS=50MNEMO_IDF_DOMAIN_MIN_UNIQUE_TERMS=300MNEMO_IDF_DOMAIN_MIN_TOTAL_TOKENS=3000MNEMO_IDF_MIN_TEXT_TOKENS=5
Modes:
auto: activate only when thresholds are metoff: do not build/use IDFforce: activate below thresholds (dev/test only)
doctor returns an idf object with project/domain status (cold|ready|disabled|unavailable), activation flags, corpus counts, and remaining maturity gaps.
All activation thresholds are AND-gated:
- documents threshold must pass
- unique-terms threshold must pass
- total-token threshold must pass
IDF is a scoring aid and does not replace signatures, lexical ranking, FTS, or baseline cosine/Jaccard primitives. It now contributes through both idf_cosine and idf_jaccard.
Alias proposal admission uses continuous IDF strength instead of requiring a token to land in the top IDF bucket. IDF summary cutoffs are computed over unique values so duplicate-heavy corpora do not collapse the high cutoff onto a single maximum value.
Full LSH/MinHash buckets are still not implemented in this release. See docs/salience_lsh_idf_notes.md.
Alias runtime boundary
Aliases are dynamic project/domain retrieval knowledge stored in Mnemo SQLite.
- Mnemo passively logs miss events and alias hints.
maintenance(action="propose_aliases")proposes candidates and can persist pending proposals.- Curation uses
list_alias_proposals,approve_alias, andreject_alias_proposal. - Runtime query paths (
search,recall,salience_check,compact_context) consume active aliases automatically. - SQLite views for inspection:
v_alias_vocabularyv_alias_pending_proposalsv_alias_concept_counts
See docs/alias_proposals.md for scoring and curation workflow details.
Copilot compatibility
Mnemo exposes a single public MCP gateway tool to avoid tool-inventory pressure and confusion with native assistant memory tools.
The exported schema avoids unsupported JSON Schema features. Defaults, bounds, and validation are enforced in Python handlers.
Development
python -m compileall .
python smoke_test.py
python -m unittest discover -s . -p "test*.py"
python benchmark_consolidation.py
Expected result for this release: smoke test and unit suite pass locally.
The benchmark inserts 50,000 synthetic memories, backfills signatures, runs candidate-based consolidation, and verifies the consolidate_full confirmation gate.
Privacy
Mnemo stores local project memory. Do not commit local state unless you intentionally want to share seed memory. See docs/storage.md and docs/tool_reference.md.
License
MIT. See LICENSE when present in the packaged repository.