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:
shumeiko.it
2026-10-18 14:28:13 +02:00
parent cd6553061b
commit 10ad678547
7 changed files with 299 additions and 6 deletions

View File

@@ -46,7 +46,7 @@ The community edition:
| Sidecar | Fastify on Node.js, run with tsx in development (`packages/server`) |
| Desktop shell | Tauri 2 (`app/src-tauri`), an optional wrapper around the sidecar and web UI |
| Database | SQLite via better-sqlite3 and sqlite-vec |
| Memory | Today the hive-mind substrate (`packages/hive-mind-core`); target is the memory contract plus local mem0 (P0.3, P1.5) |
| Memory | `MemoryStore` from `@waggle/memory-contract`, implemented on local mem0 by `@waggle/memory-mem0` (ADR-0007). Existing callers still use the hive-mind substrate until P1.5 |
| Local models | Waggle-managed Ollama runtime, or the user's own provider keys |
| Tests | Vitest (unit), Playwright (e2e and visual) |
@@ -61,6 +61,7 @@ npm workspaces with the root `package-lock.json`. Node `^20.19.0 || >=22.12.0`.
| `apps/web` | Keep. The main UI; all React code lives here. |
| `app/` | Keep. Tauri shell only (there is no `app/src/`). |
| `packages/agent`, `core`, `server`, `shared`, `sdk`, `weaver`, `marketplace`, `cli`, `launcher` | Keep. |
| `packages/memory-contract`, `packages/memory-mem0` | Keep. The memory contract and its mem0 implementation (ADR-0007). |
| `packages/waggle-dance`, `packages/worker` | Postponed: team mode stays in the repo, is not built or shipped (ADR-0003). |
| `packages/optimizer` | Excluded: part of self-learning (ADR-0004). Removed in P1.4. |
| `packages/hive-mind-*`, `memory-mcp`, `wiki-compiler` | Excluded once P1.5 moves all memory access to the contract. |
@@ -107,9 +108,11 @@ modules (P1.4), `packages/server/src/stripe/` and `packages/server/src/kvark/` (
checks, or KVARK and Team upsell. When a work package touches such code, remove it.
The word "tier" also means UserTier (UI complexity), ModelTier, persona tiers, CLI levels
and memory health levels. Leave those alone and never mass-replace the word.
2. **Memory goes through the contract.** New code must not import `@waggle/hive-mind-*`,
`memory-mcp` or `wiki-compiler`, and must not run SQL against the memory database. Until
the contract lands (P0.3), keep memory changes minimal. The knowledge graph is not in v1.
2. **Memory goes through the contract.** New code reaches memory through `MemoryStore`
(`@waggle/memory-contract`), must not import `@waggle/hive-mind-*`, `memory-mcp` or
`wiki-compiler`, and must not run SQL against a memory database (ADR-0007). Until P1.5 moves
the existing callers, keep changes to the old memory code minimal. The knowledge graph is
not in v1.
3. **Team mode is frozen.** Do not add features to team routes, WaggleDance or the worker.
4. **Self-learning is out.** Do not extend evolution, improvement signals, correction
learning, judge or eval loops, or `optimizer`. Cost tracking stays.
@@ -302,7 +305,7 @@ interface AgentPersona {
| Term | Meaning |
|---|---|
| Sidecar | The local Fastify server (`packages/server/src/local`) that the UI talks to |
| Memory contract | The interface Waggle uses to remember, search, get, update and delete memories (P0.3) |
| Memory contract | `MemoryStore` in `@waggle/memory-contract`: how Waggle remembers, searches, lists, updates and forgets memories (ADR-0007) |
| mem0 | Open-source memory library (`mem0ai`, Apache-2.0) behind the contract, run locally |
| Hive DS | Waggle design system tokens (`waggle-theme.css`) |
| BEHAVIORAL_SPEC | Core agent rules (`packages/agent/src/behavioral-spec.ts`) |