ADR-0007 maps today's memory usage onto the contract and mem0: profile card and tasks move to waggle.db, learned facts stay in mem0, extraction runs in the background in batches. Research notes cover what mem0 3.3.1 does and how 68 files use memory today. Two defects found on the way are logged for the main project (UF-025, UF-026).
2.1 KiB
2.1 KiB
ADR-0002: Memory goes through a contract backed by local mem0
- Status: Accepted
- Date: 2026-10-14, amended 2026-10-15 (knowledge graph deferred)
Context
Memory today is the hive-mind substrate in packages/hive-mind-core (FrameStore,
HybridSearch, KnowledgeGraph, identity and awareness layers). About 250 imports across agent,
server, weaver and cli depend on it, and around 20 files query the memory database with SQL.
The agreed scope takes the memory packages out of the community edition.
Decision
- Waggle reaches memory only through a memory contract package (P0.3): remember, search, get, update, delete and history, plus a capability map that the UI uses to hide unsupported features.
- The backend is the open-source mem0 library (
mem0ai, Apache-2.0) running inside the sidecar. Data stays in a SQLite file in the Waggle data directory. The hosted Mem0 Platform is not used. - Fact extraction and embeddings use the Waggle-managed Ollama runtime or the user's own provider key.
- Memory features in v1: facts, search and the user profile (an exact profile card plus facts learned about the user, see ADR-0007). Hidden in v1: history import, wiki, Claude Code and Codex hooks, Waggle Room and the memory MCP server.
- The knowledge graph is deferred to a later release, because open-source mem0 has no graph memory since version 3. The capability map marks it unavailable, so it can be added later without changing the contract.
- No code outside the adapter queries the memory store with SQL.
Consequences
- Tables that belong to Waggle rather than to memory (cron, notifications, pending actions,
skill hashes, file index, cost tracking) move to a separate
waggle.db(P1.5). - Non-memory code in
hive-mind-core(WorkspaceManager, logger, injection scanner, ingress guard) moves to@waggle/core(P1.5). - Search quality is compared with the current engine on a reference question set, with a local model and with a provider key, before release.
hive-mind-*,memory-mcpandwiki-compilerare removed once nothing imports them (P2.2).