Files
waggle-os/docs/oss/adr/0002-memory-contract-local-mem0.md
shumeiko.it 10ad678547 docs(oss): record the memory contract decision (ADR-0007)
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).
2026-10-18 14:28:13 +02:00

40 lines
2.1 KiB
Markdown

# 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-mcp` and `wiki-compiler` are removed once nothing imports them (P2.2).