Files
waggle-os/docs/oss/adr/0002-memory-contract-local-mem0.md
shumeiko.it ea21721d2a docs(oss): record owner decisions as ADRs and the starting baseline
ADR-0001..0006 capture the scope decisions: no monetization, memory
through a contract backed by local mem0 (knowledge graph deferred), team
mode postponed, cost tracking open and self-learning out, whatsapp-web.js
for WhatsApp, opt-in analytics. baseline.md records build, typecheck,
lint and unit test results on macOS before scope work starts.
2026-10-15 18:35:58 +02:00

39 lines
2.0 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. 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).