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).
This commit is contained in:
@@ -20,7 +20,8 @@ The agreed scope takes the memory packages out of the community edition.
|
||||
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,
|
||||
- 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
|
||||
|
||||
73
docs/oss/adr/0007-memory-contract.md
Normal file
73
docs/oss/adr/0007-memory-contract.md
Normal file
@@ -0,0 +1,73 @@
|
||||
# ADR-0007: The memory contract and how it maps onto mem0
|
||||
|
||||
- Status: Accepted
|
||||
- Date: 2026-10-18
|
||||
|
||||
## Context
|
||||
|
||||
ADR-0002 decided that Waggle reaches memory through a contract backed by local mem0. The
|
||||
inventory of today's callers ([research/memory-inventory.md](../research/memory-inventory.md))
|
||||
shows what the contract must cover: 68 files use the frame store; content prefixes such as
|
||||
`[mind-fact]` or `Decision:` act as types and are queried with `LIKE`; named "sessions" group
|
||||
writes by producer; personal and workspace minds are separate databases whose ids collide; the
|
||||
same databases also hold the user's profile card, a task list and a dozen non-memory tables.
|
||||
What mem0 3.3.1 offers is recorded in [research/mem0-3.3.1.md](../research/mem0-3.3.1.md).
|
||||
|
||||
The owner decided on 2026-10-16 that the profile card keeps exact fields while facts learned
|
||||
about the user live in mem0, and that facts are extracted in the background, in batches.
|
||||
|
||||
## Decision
|
||||
|
||||
1. **Two packages.** `@waggle/memory-contract` holds the `MemoryStore` interface, the record
|
||||
model, the capability map, an in-memory store for development and tests, and a
|
||||
compatibility suite every implementation must pass. `@waggle/memory-mem0` implements the
|
||||
contract on mem0. Callers depend only on the contract.
|
||||
2. **Record model.** A memory has text, a scope (personal or one workspace), a kind (fact,
|
||||
event, preference, profile, decision, summary, note) that replaces the content prefixes, an
|
||||
importance (critical, important, normal, temporary), a source, an origin (the producer:
|
||||
'chat', 'agent-run', 'loop'…) that replaces the named sessions, an optional chat session id,
|
||||
timestamps and free metadata. Ids are unique across scopes.
|
||||
3. **Operations.** `remember` stores text (identical text in the same scope is not written
|
||||
twice) or extracts facts from a conversation; `search` ranks; `list` returns newest first;
|
||||
`count`, `get`, `update`, `forget`, `forgetMatching` and `history` complete the set. Filters
|
||||
cover scopes, kinds, minimum importance, origin, session and a creation-time window.
|
||||
4. **No direct access.** Code outside a `MemoryStore` implementation does not query a memory
|
||||
database with SQL and does not import `@waggle/hive-mind-*`, `memory-mcp` or
|
||||
`wiki-compiler`. New code follows this rule now; P1.5 removes the existing violations.
|
||||
5. **Not memory.** The user's profile card (name, role, department, style and the other
|
||||
identity fields), the task list (awareness) and the other Waggle tables move to `waggle.db`
|
||||
in P1.5. What the model learns about the user is memory: kind 'profile', personal scope.
|
||||
6. **Extraction policy.** Facts are extracted in the background, in batches (after several
|
||||
turns or a pause), with the model the user chose, through the sidecar's built-in
|
||||
OpenAI-compatible proxy. A setting turns it off. Wiring this is part of P1.5.
|
||||
7. **mem0 configuration.**
|
||||
- One store per data directory, in `<dataDir>/memory/`: `vectors.db`, `vectors_entities.db`,
|
||||
`history.db` and mem0's `config.json`. Every memory belongs to user 'local'; the scope is
|
||||
mem0's `agent_id` ('personal' or 'workspace:<id>'), so mem0 never compares facts across
|
||||
scopes. Contract fields live in mem0 metadata.
|
||||
- Embeddings come from Waggle's in-process embedder, passed through mem0's `langchain`
|
||||
provider, so memory works offline. Verified on 2026-10-18 with network access blocked:
|
||||
no request was made and paraphrased queries found the right memory.
|
||||
- Fact extraction uses mem0's `openai` provider pointed at an OpenAI-compatible endpoint.
|
||||
Without one, `capabilities.extraction` is false.
|
||||
- `MEM0_TELEMETRY=false` and `MEM0_DIR` are set before mem0 is imported. With telemetry on,
|
||||
mem0 sends every call to its PostHog project and downloads a notice configuration from
|
||||
GitHub; a test asserts that no request is made.
|
||||
- `mem0ai` is pinned to exactly 3.3.1. An upgrade re-runs the compatibility suite and
|
||||
re-checks the telemetry behaviour.
|
||||
8. **Knowledge graph.** `capabilities.knowledgeGraph` is false; graph features stay hidden
|
||||
(ADR-0002).
|
||||
|
||||
## Consequences
|
||||
|
||||
- P1.5 maps the callers onto the contract: prefix lanes become `kinds`, the importance lane
|
||||
becomes `minImportance`, named sessions become `origin`, `getLatestIFrame`/`createPFrame`
|
||||
chains become plain `remember` calls.
|
||||
- Compared with the current engine: a write cannot set its own creation time (mem0's OSS build
|
||||
rejects timestamps; history import is hidden in v1 anyway); importance filters but does not
|
||||
boost ranking; P/B-frame chains, access counts and full-text search are gone, replaced by
|
||||
mem0's hybrid vector and BM25 search. P1.5 compares search quality on a reference set.
|
||||
- `list`, `count` and `forgetMatching` read every memory of the scopes involved. That is fine
|
||||
at personal scale and should be revisited if a store grows past tens of thousands.
|
||||
- mem0 keeps its SQLite handles open for the life of the process; `close` only marks the store
|
||||
closed.
|
||||
@@ -12,6 +12,7 @@ decision, add a new record that supersedes the old one.
|
||||
| [0004](0004-cost-tracking-in-self-learning-out.md) | Cost tracking is open; self-learning and `optimizer` are excluded | Accepted |
|
||||
| [0005](0005-whatsapp-web-js.md) | The WhatsApp channel uses `whatsapp-web.js` | Accepted, one open item |
|
||||
| [0006](0006-opt-in-analytics.md) | Analytics are opt-in | Accepted, one open item |
|
||||
| [0007](0007-memory-contract.md) | The memory contract and how it maps onto mem0 | Accepted |
|
||||
|
||||
## Pending decisions
|
||||
|
||||
|
||||
Reference in New Issue
Block a user