docs(oss): record how the server runs on mem0 (ADR-0007)

This commit is contained in:
shumeiko.it
2026-10-24 12:04:39 +02:00
parent 55f42a1077
commit 8b5624520c

View File

@@ -101,3 +101,47 @@ its own copies. The substrate keeps its copies until it is removed. Those files
Apache-2.0 package into the MIT `core` package; both are Egzakta's code, and the licence of the
copies is part of the licensing review.
## The server on mem0 (P1.5, days 7 and 8)
- **One store.** The sidecar opens one mem0 store in `<dataDir>/memory/` at startup and
decorates it as `server.memory`. Agent sessions select a workspace with
`Orchestrator.setWorkspace(id)`; nothing opens a database per workspace any more.
Embeddings come from the in-process model (`all-MiniLM-L6-v2`), loaded on first use and
stored at its native 384 dimensions (`createMemoryEmbedder` in core). The CLI REPL opens
the same store. Tests use a deterministic word embedder (`WAGGLE_MEMORY_EMBEDDER=words`).
- **Background extraction** (decision 6). Finished chat turns are queued per session and
handed to `remember({ conversation })` after six messages or a two-minute pause. The
facts land in personal memory as kind `profile`, origin `extraction`. mem0 calls the
model through the built-in OpenAI-compatible proxy (or LiteLLM when the user runs it)
and reads the user's current model on every call. `memoryExtraction` in `config.json`
turns it off (default on). Failures are logged and never block a turn.
- **Legacy memories** are copied once into the store in the background
(`legacy-memory-import.ts`). The `.mind` files are opened read-only. Content prefixes
become kinds, `[mind-rawturn …]` frames and deprecated frames are skipped, the original
creation time is kept in `metadata.legacy_created_at` because mem0 sets its own. Progress
is kept per scope in `waggle_meta`, so an interrupted copy resumes.
- **Writers.** Chat write-back, compaction summaries, sub-agent and agent-run results
(`run-memory.ts`), loops, connector fetch, indexed workspace files and the failed-turn
capture all call `remember`. Contract field names are reserved in metadata; agent-run
metadata renames them with a `run_` prefix.
- **Recall** keeps the importance lane, the date window and the catch-up branch, renders
`profile` and `event` memories as their own sections, and drops the raw-dialogue and
extracted-fact lanes of the old engine. The cross-encoder reranker is opt-in
(`WAGGLE_RERANKER=1`).
- **Search quality** was compared on a reference set of 100 memories and 67 queries
([research/memory-search-quality.md](../research/memory-search-quality.md)). mem0 matches
the old engine with its reranker (recall@1 0.72, recall@5 0.89 against 0.72 and 0.90) at
a seventh of the latency. The reranker did not improve mem0's ranking and costs about
130 ms per search, so it stays off. The benchmark keeps running against mem0 alone after
the old engine is removed.
- **Waggle data moved to waggle.db** as well: the install audit trail (`install_audit`,
copied from `personal.mind` with the other personal tables) and the file index
(`file_index`, keyed by scope and path, pointing at memory ids; files are re-indexed on
their next write rather than migrated).
- **Removed with the old engine:** the weaver package (consolidation, decay, transcript
distillation), harvest and its auto-sync, wiki, chat-export import, memory lanes, vector
backfill and index reconciliation, knowledge-graph tools and extraction, and the
per-workspace mind cache in sessions. Scheduled jobs left over from legacy data
(`index_reconcile`, `harvest_sync`, `memory_compact`, `memory_lane_extract`,
`workspace_health`) run as no-ops.