From 8b5624520c85b80b229b4ba632ac5f29be003359 Mon Sep 17 00:00:00 2001 From: "shumeiko.it" Date: Sat, 24 Oct 2026 12:04:39 +0200 Subject: [PATCH] docs(oss): record how the server runs on mem0 (ADR-0007) --- docs/oss/adr/0007-memory-contract.md | 44 ++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/oss/adr/0007-memory-contract.md b/docs/oss/adr/0007-memory-contract.md index 46dff52..e1c1586 100644 --- a/docs/oss/adr/0007-memory-contract.md +++ b/docs/oss/adr/0007-memory-contract.md @@ -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 `/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.