Why
AI coding assistants forget everything between sessions. MemoryPilot gives them persistent, searchable memory with project awareness, semantic understanding, and automatic knowledge organization. Built-in AAAK compression and memory capsules reduce token consumption by 5-10x when loading context. Every memory is auto-classified with the right importance, kind, and TTL on insert. The database compacts itself automatically — zero maintenance.
Benchmarks
LongMemEval-S (ICLR 2025) — Academic Standard
Evaluated on the 470 answerable questions of LongMemEval-S (ICLR 2025; the 30 abstention questions are left out, as the official retrieval protocol does). Turn-level index, ~50 sessions per haystack.
What the score measures. R@5 here is session-level recall_any@5: a question counts as a hit when at least one of the top 5 retrieved turns belongs to one of its gold sessions. It is a retrieval metric, not answer accuracy, and a question that needs several sessions counts as a hit as soon as one of them is found (300 of the 470 questions have more than one gold session). For scale: a plain BM25 over turns, with no embeddings, scores about 93% on the same metric and 74% on recall_all@5. These figures were measured with v4.2 (multilingual-e5-small); the current default model has only been measured on a 100-question slice (see v4.6 below).
Retrieval scores (same metric family, setups differ)
Answer accuracy (a different metric: an LLM reads the retrieved context and a judge grades the answer)
All figures are published by their own authors, none was reproduced independently, and the two tables cannot be compared with each other. On session-level recall MemoryPilot posts the highest published local score, by a margin smaller than the gap between this metric and a plain BM25 baseline. The protocol to settle a comparison: same 470 questions, same hardware, every system run by the same script, reporting
recall_any@5,recall_all@5, turn-level evidence recall and end-to-end QA accuracy with a fixed reader and judge.
Detailed view — MemoryPilot vs MemPalace (closest local competitor)
¹ Validated with the full 470-question evaluation set (after dropping the 30 abstention questions) in two modes: hybrid retrieval with the rerank off (BM25 + cosine RRF,
MEMORYPILOT_CROSS_RERANK=off, ~28 ms/query) and the default adaptive cross-encoder rerank (MEMORYPILOT_CROSS_RERANK=adaptive, jina-v2-multilingual, fusion weight 0.45, ~900 ms/query, suitable for benchmarks and high-stakes recall). Latencies cover the search call only, with models loaded; MemPalace's figures come from a different question split.
By Category (470 questions, adaptive rerank)
French / Multilingual Benchmark — --benchmark-fr
To complement the English-only LongMemEval, MemoryPilot ships its own deterministic French benchmark covering 109 memories and 109 paraphrased queries across infra, mobile, web, security, and ML domains. The queries are intentionally distant from the indexed wording so they actually exercise the semantic lane.
v4.5 fixed a ranking bug that had capped this benchmark at R@5 ≈ 70% since v4.0: knowledge-graph neighbours were injected at a hard-coded score (0.1) above every genuine RRF hit (max 2/41 ≈ 0.049), so they occupied the cross-encoder window and pushed real matches past limit. Neighbours now enter below the weakest genuine candidate and only the cross-encoder can promote them.
v4.5.0 also closes two write-path stability bugs surfaced by that work: the episodic rollup embedded every hourly bucket on each pass (before checking whether the episode already existed) and did so synchronously inside add_memory, then panicked on multi-byte French text; it now runs on its own thread with a cheap existence check first. And auto-compaction held a Mutex across run_gc/compact_to_capsules, whose merged rows re-enter add_memory — a deadlock hidden until the rollup stopped panicking ahead of it.
Run-to-run variance is bounded to ±1 pp on R@5 / R@10 thanks to deterministic memory ids, deterministic id-based RRF tie-break, synchronous ANN warm-up, and explicit cross-encoder pre-warm before the first query. This is the metric to watch for any French / multilingual regression.
v4.6 — beyond single-fact retrieval
v4.6.0 targets the LongMemEval categories a top-k retriever alone cannot win: multi-session aggregation, temporal reasoning, knowledge updates and abstention. Everything stays local and rule-based or int8 ONNX. Measured on LongMemEval-S@100 (64 single-session + 36 multi-session, plus the 7 abstention questions of that slice) against v4.5.0, same machine, cross-encoder adaptive:
--benchmark-fr is unchanged within noise (R@1 96.3%, R@5 99.1%, MRR 97.6%).
- MMR diversity (
src/diversity.rs) — the finalists plus the RRF ranks just below them are re-ordered by maximal marginal relevance over their stored vectors (λ = 0.4, redundancy floor 0.55). The top hit never moves, so MRR is untouched; a second, distinct source can displace a restatement of the first.MEMORYPILOT_MMR=0disables it. - Temporal grounding (
src/temporal.rs) — explicit dates in a memory (2026-09-01,12 septembre 2026,September 12,hier…) becomedateentities at ingest; a temporal phrase in the query (last week,il y a deux semaines,en mars,last Tuesday) becomes a day window that boosts dated candidates inside it (×1.25) and mildly demotes dated candidates far outside (×0.85). Undated memories are neutral, so a mis-parsed window costs at most the boost.MEMORYPILOT_TEMPORAL=0disables it. - Contextual embeddings — transcript chunks and other context-poor kinds are embedded with a
[date · project]prefix while the stored content and its hash are left untouched. - Superseding — the daily consolidation pass links a memory to a newer, near-identical restatement with a changed value (cosine ≥ 0.86, lexical overlap 0.55–0.95, ≥ 1 h apart) and the old one is demoted (−0.35) at search time. Both stay retrievable;
consolidate_memories(apply=true)reports the links made. - Calibrated confidence — every search returns
confidence: { top_cosine, peak, cross_score, margin, level, abstain }. On LongMemEval the abstention haystacks are built from the same user's other sessions and no cheap signal separates them from answerable questions (top-1 cosine p50 0.46 vs 0.54, cross-encoder logits overlap fully), so the hardabstainis deliberately conservative (cosine < 0.35, 4% false abstention) andlevelcarries the graded signal.MEMORYPILOT_ABSTAIN_COSINEmoves the floor. - Extractive reader (
src/reader.rs, opt-in) —search_memorywithanswer: truerunsdeepset/roberta-base-squad2(int8 ONNX, 125 MB, English, loaded on demand through the idle pool) over the top-5 passages and returns the literal span or nothing. ~480 ms per question on CPU. It is a benchmarking instrument and a shortcut for literal lookups, not a language model: it abstained on 5/7 LongMemEval abstention questions where the retriever could not.--benchmark-longmemeval --readerreports SQuAD-style EM / F1 / contains.
Search Quality — Real-World (500 memories, 30 scenarios)
vs the best memory servers on the market:
The 9 Pillars
1. Hybrid Search (BM25 + jina RRF)
Every memory gets a 768-dimension transformer embedding on insert via ONNX Runtime (jina-embeddings-v5-text-nano-retrieval, int8, local inference — 100+ languages including French, English, Spanish, German, Japanese, Chinese — no API calls, no external services; the model is fetched from its Hugging Face repository on first run, licence CC-BY-NC-4.0). Queries and documents use the model's asymmetric Query: / Document: prefixes. The int8 weights are memory-mapped, so the embedder costs ~250 MB resident, most of it reclaimable file-backed pages. Search runs both BM25 full-text and cosine similarity in parallel, then merges results with Reciprocal Rank Fusion.
Results are boosted by importance weighting, knowledge graph link density, file watcher context, and penalized for expired knowledge triples.
Ephemeral working memory is available in the same MCP through remember_working, recall_working, and clear_working. It keeps fast session scratchpad context in RAM, capped to 256 items, without polluting SQLite or durable recall.
Performance optimizations:
- Lazy embedding:
add_memoryreturns instantly, embeddings computed in background thread - Two-tier query embedding cache (LRU 256 + write-through SQLite): repeated queries skip ONNX inference
- Read connection pool (16 connections): concurrent vector searches don't block writes, sized for HTTP server workloads
- EmbedPool (4 sessions, env-tunable): parallel embeddings without serialization on a single ONNX mutex
- RerankPool (1 session, env-tunable to 2): parallel cross-encoder rerank under multi-client load
- Content hashing (FNV-1a): backfill skips unchanged memories
- Synchronous warm-up entrypoint
open_at_warm: hydrates the ANN index in RAM before returning, eliminating cold-start tail (p95 search latency 3939 ms → 229 ms in the 4-client concurrency bench)
2. Temporal Knowledge Graph
A full knowledge graph with temporal validity. Facts have valid_from / valid_to dates and confidence scores. When facts become outdated, they are invalidated rather than deleted — giving the AI a timeline of how knowledge evolved.
Entities (technologies, files, components, people) are automatically extracted from memory content and linked bidirectionally. Search results from memories with all-expired triples are penalized.
5 dedicated KG tools: kg_add, kg_invalidate, kg_query, kg_timeline, kg_stats
3. GraphRAG
Every memory is automatically analyzed for entities: technologies, file paths, components, projects, and people. Entities are stored in a dedicated table. Memories sharing entities are auto-linked with inferred relationship types (resolves, implements, depends_on, deprecates...).
When searching, MemoryPilot traverses the knowledge graph from the top matches to pull in related context — e.g., finding the architecture decision that led to a specific bug fix. A combinatorial reranker then selects the best cluster of connected memories rather than independent top-K results, producing cohesive context (94% cluster coherence). Tuned RRF fusion (k=40), exact term coverage boost, smart FTS tokenization, query-time KG expansion, temporal recency, and importance tiebreakers push NDCG@10 to 94% with perfect R@5/R@10.
4. Chunked RAG (Transcripts)
Save full conversation transcripts without polluting the LLM context window. The add_transcript tool automatically chunks large texts into ~2000 character blocks and links them together. Chunks are excluded from recall but fully searchable.
For source code, MemoryPilot uses local tree-sitter parsing by default for Rust, Python, TypeScript, TSX, and JavaScript, with Svelte support via <script> extraction plus markup chunking. Code is split on semantic boundaries such as functions, classes, impl blocks, interfaces, and exports instead of arbitrary paragraphs.
Auto-distillation extracts structured memories from transcripts: decision, preference, todo, bug, milestone, problem, and note. Smart disambiguation: a segment mentioning both a bug and its resolution is classified as milestone, not bug.
Supports session_id, thread_id, window_id for multi-window memory scoping.
5. AAAK Compression
Inspired by MemPalace's symbolic memory language. When compact: true is passed to recall or get_project_brain, output is compressed ~3x using a terse, pipe-separated format:
[DEC:5] Use Clerk over Auth0 | tags:auth,stack | proj:MyApp
[PREF:4] Always use TypeScript strict mode | tags:typescript
6. Self-Healing (Auto-Linter)
MemoryPilot watches your files. When you save a Rust, Svelte, or TypeScript file, it lints in the background. Compilation errors are automatically stored as bug memories with the exact stack trace. When the error is fixed, the memory is auto-deleted.
The linter thread reuses a single DB connection for its entire lifetime.
7. Garbage Collection & Auto-Compaction
Old, low-importance memories are scored for cleanup candidacy. Groups of related stale memories are merged into condensed summaries using heuristic keyword extraction. Orphaned links and entities are cleaned. DB is vacuumed after significant deletions.
Auto-compaction triggers automatically when the memory count exceeds 500: the GC runs in the background after add_memory, debounced to once per 5 minutes. Zero manual intervention.
Memory Capsules (compact_memories tool): compress old low-importance memories into dense ~100-200 token capsules. Credentials and architecture decisions are never compressed. Capsules preserve Knowledge Graph links, giving you 5-10x token savings on aged memories without recall loss.
8. Zero-Shot Auto-Classification
Every memory is automatically classified on insert when the caller doesn't specify kind or importance. Pattern-based heuristics detect:
- Credentials (API keys, secrets) → importance 5, no TTL
- Architecture decisions → importance 5
- Preferences/patterns → importance 4
- Bugs → importance 3, TTL 90 days
- TODOs → importance 2, TTL 30 days
- Code snippets → importance 2
- Milestones → importance 4
No LLM needed — pure regex + keyword heuristics. The AI can still override by passing explicit kind and importance.
9. Project Brain
One tool call returns a dense JSON snapshot of a project under 1500 tokens: tech stack, architecture decisions, active bugs, recent changes, key components, and team members (auto-detected person entities). Supports compact: true for AAAK compression.
What's new in v4.11
-
Jina models only, non-commercial use: jina-embeddings-v5-text-nano-retrieval and jina-reranker-v2-base-multilingual are the only models (the e5, bge, gte and mmarco options are gone). Both are CC-BY-NC-4.0: see Models: non-commercial use only.
-
Fixes from the October 2026 audit (each one has a regression test in
crates/memorypilot-core/src/db/audit_tests.rs):- A search with
limitof 25 or more (31 on temporal queries) panicked and stopped the process; the limit is now capped at 100 for every interface. - Credentials: the password of a connection URI (
postgres://user:password@host) is masked, and such a URI in a note makes it a credential. SQLite now seals a credential before writing it (no clear text in the table, the FTS index or the WAL) and refuses the write when the vault key is unavailable, unlessMEMORYPILOT_VAULT=off. Entities come from the masked label, soget_project_brainnever returns a secret. A one-shot startup migration repairs databases written by older versions. - Deduplication: a near-duplicate that corrects a figure or a date ("30 jours" then "60 jours") now replaces the old text instead of being dropped; the replaced text is kept in
metadata.previous_versions. - Compaction never touches pinned memories, and every original that
run_gc,compact_memoriesor consolidation removes is kept whole in an archive:list_archivedandrestore_memorybring it back. - An embedding computed for a text edited in the meantime is no longer stored.
- Episodes are built per project (they used to mix every project of an hour), are rebuilt when a source memory changes, disappear with a deleted one, and never include credentials.
- Filtered searches no longer depend on the global ANN top 200, which could miss a small project's best matches past 5,000 vectors.
- The Cursor hook ingests a long transcript backlog in chunks instead of keeping only its last 400 KB.
- Exports include every memory (they stopped at 10,000).
- A search with
-
Memories checked against Git: a memory that cites files of its project's repository is compared with the commits made after it. Search, recall and get add a
verificationobject when there is something to say:likely_resolved(a later fix commit touches the files a bug cites),possibly_resolved(a later fix commit reads like the bug's resolution),changed_since(the cited files changed), or the recordedresolved/ . Mass commits (over 40 files) and docs, tests or chores are ignored. Git is read on demand and cached per HEAD: nothing is copied into the database. gives the detail, records open / resolved / verified with the fixing commit; resolved bugs leave the project brain. turns it off.
What's new in v4.10
- Outdated memories hidden automatically: when a newer memory says "X instead of Y" about an older one, or is a newer status of the same thing, the older one is tagged
superseded(kept, readable by id,unsupersedeto undo) and no longer surfaces in recall or search. - Better recall: the memories matching the current task come first and are always reranked by the cross-encoder. Recall golden set: top-1 73% → 82%, top-5 91% → 100%, cross-project leak 9% → 0%.
- Index repair at startup (
repair_index), andMemoryPilot --seal-backup FILE...to encrypt credentials inside old backups.
What's new in v4.9
- Project isolation in recall: memories from another project only surface when they name the current one (cross-project leak 55% → 18%, hit rates unchanged).
- Lean tool list: 17 core tools (~13 KB of schema per conversation instead of ~24 KB); everything else through
memory_admin.MEMORYPILOT_TOOLS=fullrestores the full list. - Credentials encrypted at rest: XChaCha20-Poly1305, key in the macOS Keychain (key file elsewhere), masked over HTTP (masked everywhere since v4.11, see secrets as pointers).
archive_transcripts: old raw transcripts move to~/.MemoryPilot/archive/*.jsonland out of the live index.find_conflicts: report of same-project memories that contradict each other.rate_skill: usage feedback on learned skills; reliable ones rank first, failing ones are demoted.- Remote access:
--httpnow requires a token (~/.MemoryPilot/http.token), asAuthorization: Beareror/mcp/<token>.scripts/remote-access.shsets up a LaunchAgent and a Cloudflare tunnel so claude.ai, the iPhone app or another PC can use the same memory.
Install
Homebrew (macOS / Linux)
brew install Soflutionltd/memorypilot/memorypilot
That's it. On Apple Silicon, Homebrew installs the signed and notarized release binary (from the first signed release on); Intel Macs and Linux build from source via cargo (Homebrew pulls Rust automatically). After install, run ./install.sh from the cloned repo or follow the manual MCP config below.
Why signed matters on macOS. Credentials stored in MemoryPilot are encrypted with a key kept in your Keychain. macOS lets a binary read it without asking only when that binary is signed by the team that created the key. The signed release keeps that identity across updates, so you are never prompted; a binary built from source (
cargo install, Homebrew on Intel) has a new identity at each build, and macOS asks for your Keychain password after each update. Without stored credentials, the Keychain is never read.
One-liner — auto-configures every IDE on your machine
curl -fsSL https://raw.githubusercontent.com/Soflutionltd/MemoryPilot/main/install.sh | bash
What this does:
- Detects your platform (macOS arm64 / x64, Linux x64 / arm64).
- Fetches the pre-built binary from the latest GitHub Release and checks its
.sha256. - On macOS, checks the signature: refuses a binary signed by another team, warns when it is unsigned.
- Installs to
~/.local/bin/MemoryPilotand clears Gatekeeper attributes on macOS. - Auto-configures every supported IDE / agent it finds — Cursor, Claude Desktop, Claude Code, Codex CLI, Gemini CLI, Windsurf, VS Code, OpenCode, Cline, Roo Code — in a single pass.
If no pre-built binary is available for your platform, it falls back to cargo build --release --features http automatically (requires Rust).
Alternative paths
# Via Cargo, pinned to a release tag — works anywhere Rust runs
# (unsigned on macOS: Keychain prompt after each update if you store credentials):
cargo install --git https://github.com/Soflutionltd/MemoryPilot --tag v4.11.0 --bin MemoryPilot
# Local clone + auto-config (same installer, run from inside the repo):
git clone https://github.com/Soflutionltd/MemoryPilot.git && cd MemoryPilot && ./install.sh
The installer is idempotent: re-run it any time to refresh configs without breaking the others.
Pre-built binaries
Every release ships pre-built binaries for the three mainstream targets. Linux builds come from the release CI workflow on every v*.*.* tag; the macOS build is signed with Soflution's Developer ID and notarized by Apple (scripts/release-macos.sh):
Each archive is paired with a .sha256 for verification. Grab them from the releases page.
Intel Mac (
x86_64-apple-darwin): no pre-built binary — theort/ ONNX Runtime crate used byfastembeddoes not publish prebuilts for this target. Usebrew install Soflutionltd/memorypilot/memorypilot(builds from source) orcargo install --git .... Apple Silicon Macs (M1+) are fully covered with a pre-built binary.
Supported IDEs / agents (auto-configured by ./install.sh):
Additional MCP-compatible clients (use the same stdio binary, manual config):
The script is idempotent — run it again to update without breaking existing MCP configs.
ChatGPT Desktop
ChatGPT requires a remote MCP endpoint. Start the HTTP server, then add it as a custom connector:
MemoryPilot --http 7437
In ChatGPT: Settings → Apps → Create → URL: http://localhost:7437/mcp
Manual install
git clone https://github.com/Soflutionltd/MemoryPilot.git
cd MemoryPilot
cargo build --release --features http
cp target/release/MemoryPilot ~/.local/bin/
chmod +x ~/.local/bin/MemoryPilot
xattr -cr ~/.local/bin/MemoryPilot # macOS only
Then add MemoryPilot to your IDE's MCP config manually (see table above for file paths).
How it works
That's it. MemoryPilot automatically injects a dynamic System Prompt into your IDE on startup. The AI will proactively call add_memory in the background to store your architecture decisions, API keys, and bug fixes without manual intervention. All configured IDEs share the same memory database.
For ChatGPT or any MCP client that needs HTTP: run MemoryPilot --http to expose the Streamable HTTP endpoint at /mcp.
Or use via McpHub for SSE transport with all your other MCP servers.
First run
# If upgrading from v1 (JSON files):
MemoryPilot --migrate
# Compute embeddings for existing memories:
MemoryPilot --backfill
# Force re-embed all (skips unchanged via content hash):
MemoryPilot --backfill-force
MCP Tools (30)
Core
Memory CRUD
Agent hooks (automatic memory, zero agent effort)
MemoryPilot --install-hooks
Installs two hooks in every agent found (existing settings and hooks are kept, a .bak is written):
- Session start runs
MemoryPilot --hook session-start --agent <agent>and injects the compact recall of the opened project. - Stop runs
MemoryPilot --hook stop --agent <agent>, answers{}immediately and distills, in a detached process, only the transcript lines added since the previous turn. From user messages only what the user typed is kept (Cursor<user_query>, Claude Code meta lines skipped), agent narration ("Checking…", "Let me…", "Je vais…") is filtered out, and obvious secrets (API keys, JWTs, IBANs) are redacted before storage.
State: ~/.MemoryPilot/cursor-hooks-state.json. Log: ~/.MemoryPilot/cursor-hooks.log. Set MEMORYPILOT_DB=/path/copy.db to test against a copy.
Knowledge Graph
Project & Config
Maintenance
Memory Types
fact · preference · decision · pattern · snippet · bug · credential · todo · note · milestone · architecture · problem · transcript_chunk
Each memory has importance (1-5), optional TTL, tags, project scope, content hash, and auto-generated embedding + entity links.
CLI
MemoryPilot # Start MCP stdio server
MemoryPilot --backfill # Compute missing embeddings
MemoryPilot --backfill-force # Re-embed all (skips unchanged via hash)
MemoryPilot --benchmark-recall # Run recall quality benchmark
MemoryPilot --benchmark-search # Search quality: R@5, R@10, NDCG@10, cluster coherence
MemoryPilot --benchmark-fr # French/multilingual deterministic benchmark (109 queries, ±1pp variance)
MemoryPilot --benchmark-longmemeval # LongMemEval-S benchmark, supports --limit N and --min-r5 PCT
MemoryPilot --benchmark-concurrency # Multi-client concurrency bench (--clients N --queries-per-client N)
MemoryPilot --benchmark-latency # open_at startup + search latency
MemoryPilot --http 7437 # Start HTTP REST server (requires --features http)
MemoryPilot --migrate # Import v1 JSON data
MemoryPilot --version # Show version
MemoryPilot --help # Show help
Tuning environment variables
HTTP API
When built with --features http, MemoryPilot exposes a multi-threaded REST API (4 worker threads, each with its own DB connection):
# Health check
curl http://localhost:7437/health
# Call any MCP tool
curl -X POST http://localhost:7437/tools/call \
-H 'Content-Type: application/json' \
-d '{"name": "search_memory", "arguments": {"query": "auth setup", "limit": 5}}'
Architecture
src/main.rs — CLI + MCP stdio server + file watcher init + HTTP server init + benchmark runners
src/code_chunker.rs — Tree-sitter code-aware chunking for Rust/Python/TS/TSX/JS/Go/Java/Kotlin/Swift + Svelte scripts
src/db.rs — SQLite facade: hybrid search, CRUD, KG, GC, brain, recall, lazy embed, connection pool, ANN warm-up
src/db/benchmark.rs — Internal recall/search quality benchmark helpers
src/db/benchmark_fr.rs — French/multilingual deterministic benchmark (109 queries, ±1pp variance)
src/db/benchmark_longmemeval.rs — LongMemEval-S benchmark runner + regression guard support
src/db/transcript.rs — Transcript/session ingestion and local-only distillation
src/tools.rs — 41 MCP tool definitions + handlers
src/protocol.rs — JSON-RPC types
src/embedding.rs — jina-embeddings-v5 via ONNX Runtime (fastembed for legacy models), EmbedPool, two-tier query cache
src/tokenizer.rs — lean byte-level BPE (tiktoken ranks) and Unigram tokenizers, ~65 MB instead of ~535 MB with the `tokenizers` crate
src/onnx_external.rs — one-shot rewrite of embedded ONNX weights into a memory-mapped sidecar (ORT 1.28 keeps 3 copies otherwise)
src/pool.rs — lazily-built, idle-evicting pool shared by the embedder and reranker sessions
src/db/consolidate.rs — embedding-based near-duplicate consolidation (daily + `consolidate_memories`)
src/reranking.rs — Cross-encoder rerank (jina-v2-multilingual), RerankPool, adaptive trigger, confidence gate
src/ann.rs — Persistent on-disk HNSW (usearch) with synchronous warm-up via `wait_for_ann_warm`
src/fts.rs — FTS5 query variants (prefix, phrase, NEAR) + Snowball stemming
src/graph.rs — Entity extraction (tech, files, components, people) + relation inference + graph traversal
src/gc.rs — GC scoring, heuristic memory merging, stopwords
src/working_memory.rs — In-process scoped scratchpad memory for current MCP sessions
src/watcher.rs — File system watcher + auto-linter with persistent DB connection
src/http.rs — Optional multi-threaded HTTP REST server (feature-gated)
Database Schema
memories — id, content, kind, project, tags, importance, embedding (BLOB),
content_hash, expires_at, last_accessed_at, access_count, metadata
memories_fts — FTS5 virtual table (content, tags, kind, project)
memory_entities — memory_id, entity_kind, entity_value, valid_from, valid_to
memory_links — source_id, target_id, relation_type, valid_from, valid_to, confidence
knowledge_triples — id, subject, predicate, object, valid_from, valid_to, confidence, source_memory_id
projects — name, path, description
config — key/value store
Performance
Optimizations
- Lazy embedding:
add_memoryinserts withNULLembedding, background thread computes and updates asynchronously - Content hashing (FNV-1a):
--backfill-forceskips memories whose content hasn't changed - Two-tier embedding cache: 256-entry in-process LRU on top of a write-through SQLite query cache (
*.query_cache.sqlite, soft-capped at 8 192 entries with LRU eviction) so repeated queries are instant within a session and across restarts - Read connection pool (4 connections): concurrent vector searches don't block writes
- WAL mode: SQLite Write-Ahead Logging for concurrent read/write
- Batched scoring: knowledge triple counts and link boosts fetched in single queries, not N+1
- Debounced cleanup: expired memory cleanup runs max once per 60 seconds
- Prepared statements: graph traversal prepares SQL once, not per node
- Tuned RRF fusion: k=40 for sharper top-K discrimination vs standard k=60
- FTS5 precision fallbacks: prefix, exact phrase, and NEAR proximity queries run together for code symbols, errors, and named concepts
- Weighted FTS fields: content, tags, kind, and project use separate BM25 weights to make structured metadata count
- ACT-R-style activation: frequently reused and recently accessed memories get a small cognitive activation boost before final reranking
- int8 quantized embeddings: stored vectors are 4× smaller (388 bytes vs 1536 bytes) with negligible recall loss; fast SIMD-friendly dot product directly on the blob avoids per-search allocations
- Local HNSW ANN index (
usearch): persistent on-disk approximate nearest neighbor index that warms asynchronously from SQLite in a detached thread (non-blocking startup), updates incrementally on backfill, on the async embed worker, and on delete. Surfacesvector_anncandidates so large memory bases stay fast as they grow past tens of thousands of entries. - ANN scan bypass: when the index reaches 5,000+ entries, the SQL vector scan is restricted to the union of ANN top-K and BM25 hits — turning an O(N) blob load into an O(K) lookup without changing the ranking logic.
- Code-aware chunking: tree-sitter splits Rust/Python/TypeScript/TSX/JavaScript on semantic units, with Svelte
<script>extraction - Exact term coverage boost: +10% when 80%+ of query terms appear in memory content
Fast Local Development
Use cargo check for day-to-day validation; it catches type and borrow errors without paying the full linking cost.
make check # cargo check
make check-http # cargo check --features http
make test # cargo test
make timings # cargo build --timings
make check-cached # RUSTC_WRAPPER=sccache cargo check
sccache is optional but recommended for frequent rebuilds:
make sccache-install
make build-cached
Cargo aliases are also available: cargo dev, cargo check-http, cargo test-fast, cargo timings, and cargo build-http.
Keep cargo build --release --features http for release validation and benchmark runs. Linker swaps such as mold or lld are intentionally not enabled by default on macOS; measure with cargo build --timings first before changing .cargo/config.toml.
Run Benchmarks Yourself
MemoryPilot --benchmark-search --scenario-limit 30 # R@5, R@10, NDCG@10, cluster coherence, latency
MemoryPilot --benchmark-recall --scenario-limit 12 # top1/top5 hit rate, cross-project leak, credential safety
MemoryPilot --benchmark-longmemeval [PATH] [--limit N] [--min-r5 PCT] # LongMemEval-S with regression guard
The LongMemEval benchmark downloads the LongMemEval-S dataset and evaluates retrieval quality across 470 questions with turn-level granularity. Results are output as JSON with per-category breakdowns.
The cross-encoder runs in adaptive mode by default (triggers on hard / non-English queries). Force or disable it explicitly:
MEMORYPILOT_CROSS_RERANK=off MemoryPilot --benchmark-longmemeval benchmarks/longmemeval_s_cleaned.json # baseline, ~28ms/query, 98.7% R@5
MemoryPilot --benchmark-longmemeval benchmarks/longmemeval_s_cleaned.json # adaptive (default), ~900ms/query, 99.1% R@5
MEMORYPILOT_CROSS_RERANK=1 MemoryPilot --benchmark-longmemeval benchmarks/longmemeval_s_cleaned.json # force on every query, max latency
MEMORYPILOT_CROSS_RERANK_WEIGHT=0.70 MemoryPilot --benchmark-longmemeval benchmarks/longmemeval_s_cleaned.json # bias more toward the cross-encoder score
The cross-encoder is jina-reranker-v2-base-multilingual. Validated full-run results on the 470 evaluable LongMemEval-S questions (v4.2, session-level recall_any): with the rerank off, 98.7% R@5, 95.1% NDCG@10, 93.6% MRR, ~28 ms average search latency; adaptive mode reaches 99.1% R@5, 96.0% NDCG@10, 94.9% MRR, ~900 ms average search latency. The deterministic French benchmark (--benchmark-fr) is the canonical regression test for any multilingual change — variance is bounded to ±1 pp R@5 across runs.
Storage
- Database:
~/.MemoryPilot/memory.db - Global prompt:
~/.MemoryPilot/GLOBAL_PROMPT.md - Model cache:
~/.cache/fastembed/(Hugging Face layout, downloaded on first run;FASTEMBED_CACHE_PATHoverrides). Externalized ONNX weights live inmemorypilot-external/inside it.
License
Soflution Source Available License: free to use, not to fork or modify. See LICENSE for details.
Models: non-commercial use only
MemoryPilot runs two models by Jina AI, downloaded from their Hugging Face repositories on first use and never redistributed by MemoryPilot:
- jina-embeddings-v5-text-nano-retrieval (embeddings)
- jina-reranker-v2-base-multilingual (reranking)
Both are licensed by Jina AI under CC-BY-NC-4.0: non-commercial use only. Personal use is fine. Commercial use, including inside a company or a paid product, needs a commercial licence from Jina AI. The opt-in answer reader (answer: true) uses deepset/roberta-base-squad2, CC-BY-4.0.
Built by SOFLUTION LTD
