From 10ad6785473cf967961ccaace0e0e7870df33509 Mon Sep 17 00:00:00 2001 From: "shumeiko.it" Date: Sun, 18 Oct 2026 14:28:13 +0200 Subject: [PATCH] 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). --- AGENTS.md | 13 +- .../adr/0002-memory-contract-local-mem0.md | 3 +- docs/oss/adr/0007-memory-contract.md | 73 ++++++++++ docs/oss/adr/README.md | 1 + docs/oss/research/mem0-3.3.1.md | 61 ++++++++ docs/oss/research/memory-inventory.md | 134 ++++++++++++++++++ docs/oss/upstream-fixes.md | 20 +++ 7 files changed, 299 insertions(+), 6 deletions(-) create mode 100644 docs/oss/adr/0007-memory-contract.md create mode 100644 docs/oss/research/mem0-3.3.1.md create mode 100644 docs/oss/research/memory-inventory.md diff --git a/AGENTS.md b/AGENTS.md index af1fed3..00d0972 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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`) | diff --git a/docs/oss/adr/0002-memory-contract-local-mem0.md b/docs/oss/adr/0002-memory-contract-local-mem0.md index f60d28c..b550a26 100644 --- a/docs/oss/adr/0002-memory-contract-local-mem0.md +++ b/docs/oss/adr/0002-memory-contract-local-mem0.md @@ -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 diff --git a/docs/oss/adr/0007-memory-contract.md b/docs/oss/adr/0007-memory-contract.md new file mode 100644 index 0000000..8e6f5cb --- /dev/null +++ b/docs/oss/adr/0007-memory-contract.md @@ -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 `/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:'), 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. diff --git a/docs/oss/adr/README.md b/docs/oss/adr/README.md index 1e5d944..1b485e9 100644 --- a/docs/oss/adr/README.md +++ b/docs/oss/adr/README.md @@ -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 diff --git a/docs/oss/research/mem0-3.3.1.md b/docs/oss/research/mem0-3.3.1.md new file mode 100644 index 0000000..29f48d7 --- /dev/null +++ b/docs/oss/research/mem0-3.3.1.md @@ -0,0 +1,61 @@ +# mem0ai 3.3.1 (OSS build): what it does and what we must configure + +Source: the published npm package `mem0ai@3.3.1`, entry `mem0ai/oss` (`dist/oss/index.d.ts` +and `dist/oss/index.js`), read on 2026-10-16. Line numbers refer to `dist/oss/index.js`. + +## Package + +- License Apache-2.0. Runtime dependencies: `zod`, `uuid`, `axios`, `openai`. +- 41 peer dependencies, 38 of them optional. The three required peers are `better-sqlite3` + (already in Waggle), `compromise` (MIT, NLP) and `@cloudflare/workers-types` (types only, + MIT OR Apache-2.0). npm installs required peers automatically. + +## API (`class Memory`) + +| Method | Signature | Notes | +|---|---|---| +| `add` | `add(messages: string \| Message[], { userId?, agentId?, runId?, metadata?, infer?, timestamp?, expirationDate? })` | `infer: true` (default) asks the LLM to extract facts and decide add/update/delete against existing memories in the same `userId`/`agentId`/`runId` scope | +| `search` | `search(query, { topK?, filters?, threshold?, rerank?, showExpired? })` | `filters` holds `user_id`/`agent_id`/`run_id` and any metadata key, with operators `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `contains`, `icontains` | +| `get` | `get(memoryId)` | `MemoryItem \| null` | +| `getAll` | `getAll({ topK?, filters?, showExpired? })` | listing per scope | +| `update` | `update(memoryId, { text?, metadata?, expirationDate? })` | | +| `delete` / `deleteAll` | `delete(memoryId)`, `deleteAll({ userId?, agentId?, runId? })` | | +| `history` | `history(memoryId)` | change log from the history store | +| `reset` | `reset()` | drops everything | + +`MemoryItem` is `{ id, memory, hash?, createdAt?, updatedAt?, score?, rerankScore?, metadata? }`. +There is no graph memory in the OSS build. + +## Storage + +- Vector store `memory` (`MemoryVectorStore`, line 896): a SQLite file via `better-sqlite3` at + `vectorStore.config.dbPath`, table `vectors(id, vector BLOB, payload TEXT)`. Search loads the + rows matching the filters and ranks them by cosine similarity in JS. Fine for personal scale. +- History store `sqlite` at `historyDbPath`. +- Default paths fall back to the working directory or `~/.mem0`; always set them explicitly. + +## Model providers + +- Embedders: `openai`, `ollama`, `lmstudio`, `huggingface` (an HTTP TEI endpoint, not + in-process), `fastembed`, `google`, `azure_openai`, `vertexai`, `aws_bedrock`, `together`, + `langchain`. The `langchain` provider accepts any object with `embedQuery(text)` and + `embedDocuments(texts)` (duck-typed, no LangChain import), so Waggle's in-process embedder can + be passed in directly. +- LLMs: `openai` (accepts `baseURL` and `apiKey`, sends `response_format`), `anthropic`, `ollama`, + `litellm`, `groq`, `mistral`, `google`, `deepseek`, `xai`, `vllm`, `lmstudio`, and others. The + `langchain` LLM provider imports `@langchain/core` at runtime, so we do not use it. Pointing the + `openai` provider at the sidecar's built-in proxy (`http://127.0.0.1:/v1`, session token + as key) reuses whatever model the user configured. + +## Must-configure settings + +- **Telemetry is on by default.** Every `add`, `search`, `update`, `delete`, `get_all` and `reset` + sends an event to mem0's PostHog project (`https://us.i.posthog.com`, line 14821). It is read + once at module load from `MEM0_TELEMETRY` (line 14817). Set `MEM0_TELEMETRY=false` before the + module is imported, which means importing `mem0ai/oss` dynamically after setting the variable. + With telemetry on, mem0 also downloads a notice configuration from + `raw.githubusercontent.com` (observed on 2026-10-18 with a stubbed `fetch`); both stop when + telemetry is off. +- **Home directory.** mem0 reads and writes `~/.mem0/config.json` unless `MEM0_DIR` is set + (lines 15056, 16962). Point `MEM0_DIR` into the Waggle data directory. +- Console notices (first run, decay, scale thresholds) are printed by default. diff --git a/docs/oss/research/memory-inventory.md b/docs/oss/research/memory-inventory.md new file mode 100644 index 0000000..52c3ee9 --- /dev/null +++ b/docs/oss/research/memory-inventory.md @@ -0,0 +1,134 @@ +# How the code uses memory today (input for P1.5) + +Read-only inventory of the commercial memory substrate's callers, made on 2026-10-16 at commit +`5e0c369` by reading the code. Scope: non-test sources of `agent`, `server`, `weaver`, `cli`, +`core`, and HTTP calls in `apps/web`. Paths are relative to `packages/` unless marked. + +## Size + +68 files import memory (agent 19, server 38, weaver 1, cli 1, core 10), all through +`@waggle/core`. About 60 sites build `new FrameStore(db)` / `new SessionStore(db)` per request. +`MindDB.getDatabase()` is called 130 times in 26 files. + +## Classes and the methods callers use + +| Class | Used (calls) | Never used outside the substrate | +|---|---|---| +| FrameStore | createIFrame 31, setMetadata 19, getById ~12, getLatestIFrame 10, createPFrame 9, getRecent 8, list 6, delete 6, update 4, deleteByContentPrefix 3, findDuplicate 2, getGopFrames 2, touch 2, compact 2, reconstructState 1, createBFrame 1 (dead path) | hasSession, getPFramesSinceLastI, getImportanceMultiplier, getRecentFiltered, getBFrameReferences, runInTransaction | +| SessionStore | ensure 16, getActive 14 (always `[0].gop_id` to pick where a write goes), create 11, ensureActive 3, getByGopId 1, getByProject 1 (dead) | close, archive | +| HybridSearch | search ~20 (options: limit, profile, reranker, since/until, excludeDeprecated once); indexFrame 2, indexFramesBatch 2 | | +| KnowledgeGraph | createEntity 4, getEntitiesByType 4, getRelationsFrom 4, createRelation 4, searchEntities 3, getEntity 3, getEntityCount 2, linkEntityToFrame 1; wiki-compiler reads more | traverse, bfsDistances, findEntityByName, getEntitiesValidAt, … | +| IdentityLayer | exists 8, get 4, toContext 4, create 3, update 2 | | +| AwarenessLayer | add 4, toContext 3, getAll 1, getByStatus/parseMetadata/updateMetadata 1 each (loop-executor) | get, remove, update, getByCategory, clear, clearCategory | +| MultiMind | `.personal` 92 references in 21 files; search (FTS) 3; getFrameStore 2; setWorkspace 1 | getIdentity, getAwareness | +| MultiMindCache | acquire 16 / release 17 (leases), getOrOpen 5, getIfOpen 2; `agentState.getWorkspaceMindDb()` 44 calls in 14 files | | + +Search result fields read: `frame.content` (16), `frame.importance` (10), `frame.id`, +`frame.created_at`, `frame.frame_type`, `frame.source`, `finalScore`. + +## Data model + +- `memory_frames`: id (autoincrement), frame_type I/P/B, gop_id (FK to sessions), t, + base_frame_id, content, importance (critical/important/normal/temporary/deprecated), source + (user_stated/tool_verified/agent_inferred/import/system), access_count, created_at, + last_accessed, metadata JSON, content_hash; plus FTS5, vec0 and chunk side tables. +- Fields callers read: content, importance, created_at, id, source heavily; frame_type, gop_id, + access_count, last_accessed moderately; t, base_frame_id, content_hash effectively never. +- Metadata keys in use: kind, title, scope, status, confidence, tags, evidence, sourceId, + sourceUrl, archiveUids, relatedMemoryIds, relatedArtifactIds, updatedAt, trace_id. +- **Content prefixes act as types** and are queried with `LIKE`: `[mind-fact]`, `[mind-event]`, + `[mind-profile Name]`, `[mind-rawturn …]`; `User preference:`, `Correction from user:`, + `Style note:`, `Workspace topic:`, `Decision:`, `Research findings:`, `Recommendation:`, + `User asked:`, `Work completed:`; `[Session summary — key]`, `[Loop: name]`, + `[Sub-agent: role]`, `[Team:author]`, `# Monthly Agent Assessment — period`. +- `sessions` are named buckets, not chat sessions: 'harvest', 'agent-runs', 'loop', + 'team-sync', 'memory-lanes', 'agent-signals', 'session:file-index'. Chat transcripts are JSONL + files under `/workspaces//sessions/`. +- `identity`: one row (name, role, department, personality, capabilities, system_prompt). +- `awareness`: category (task/action/pending/flag), content, priority, metadata, expires_at; at + most 10 returned; loop-executor keeps status/result/lastTickAt/score in metadata. +- `knowledge_entities` / `knowledge_relations` with validity columns. + +## Personal and workspace minds + +- Personal: `/personal.mind` as `server.multiMind.personal`. +- Workspace: `/workspaces//workspace.mind`, opened through an LRU `MultiMindCache` + (max 20). Some routes open `new MindDB(path)` directly; `routes/workspaces.ts:211` opens a raw + read-only better-sqlite3 handle. +- Every session orchestrator is built on the personal DB (`server/src/local/index.ts:1298`) and + gets the workspace mind added with `setWorkspaceMind`. `getFrames()`, `getSessions()` and + `getKnowledge()` therefore return personal layers (see UF-025). +- Ids collide across minds (separate autoincrements); Memory Center routes take + `?mind=personal|workspace` to resolve them. +- The personal mind also holds non-memory tables: cron, audit, traces, evolution, signals, + compliance, feedback, wiki_pages, harvest sources/runs, raw_archive, file_index. + +## Direct SQL outside the substrate + +| File | Tables | Purpose | +|---|---|---| +| agent/src/orchestrator.ts | memory_frames, sessions, knowledge_entities | counts, empty-mind check, catch-up and importance lanes, prefix lanes | +| agent/src/context-loader.ts | memory_frames, knowledge_* | recent frames, top entities, personal-preference `LIKE` | +| agent/src/tools.ts | memory_frames | save_memory dedup, contradiction scan, search fallback | +| agent/src/pattern-write-back.ts | memory_frames | style-note duplicate check | +| server/src/local/index.ts | memory_frames, memory_frames_vec, install_audit | health and vector coverage counts | +| local/vector-backfill.ts | frames, vec, chunks, meta | embedding backfill | +| local/memory-lane-cron.ts | memory_frames, meta | nightly lane extraction watermark | +| local/monthly-assessment.ts | sessions, install_audit, optimization_log | assessment | +| local/proactive-handlers.ts, local/workspace-state.ts | awareness, memory_frames | counts, decisions `LIKE` | +| routes/memory.ts, routes/knowledge.ts, routes/workspace-context.ts | frames FTS, knowledge_* | global FTS, graph dump, workspace context | +| routes/workspaces.ts | memory_frames, sessions | counts; raw INSERT of template starter frames | +| routes/feedback.ts, routes/wiki.ts | feedback_entries, improvement_signals, wiki_pages | non-memory data in the mind | +| weaver/src/consolidation.ts | memory_frames, sessions, knowledge_entities | decay/strengthen, delete, archive | +| cli/src/repl.ts | memory_frames, sessions | counts | + +## HTTP surface used by the web app + +`/api/memory/search`, `/api/memory/frames` (GET/POST/PUT/PATCH access/DELETE), `/api/memory/stats`, +`/api/quick-capture`, Memory Center `/api/memory` and `/api/memory/:id` (GET/PATCH/DELETE, POST, +archive, confirm, trace, source), `/api/memory/erase`, `/api/memory/suppression`, +`/api/memory/merge`, `/api/memory/graph`, `/api/mind/identity|awareness|skills`, +`/api/identity`, `/api/wiki/*`, `/api/harvest/*`, `/api/import/*`, `/api/weaver/status`, +`/api/workspaces/:id/context|state|activity|export`, `/api/home/briefing`, +`/api/onboarding/status`, `/api/embedding/*`, `/api/data/erase`. Direct fetches outside the +adapter: `/api/export`, `/api/weaver/trigger`, `/api/dreams`, `/api/backup`, `/api/restore`. + +## Agent tools + +get_identity, get_awareness, search_memory (workspace first, then personal), search_all_workspaces, +save_memory (injection scan, 50 saves per session, routing guard, three-level dedup, contradiction +check, cognify), query_knowledge, add_task, correct_knowledge, read_other_workspace and the +cross-workspace file tools. Three dependencies are never wired (UF-026). + +## Recall per chat turn (`agent/src/orchestrator.ts` recallMemory) + +Empty-mind check; "catch me up" path; otherwise date window, lazy reranker, personal and +workspace hybrid search (limit 10, retried without the window), importance lane (top 5 +critical/important), filter temporary/deprecated, prefix lanes (all profiles, last 60 facts, +last 40 events), raw-detail lane, render as Profiles / Facts / Events / Workspace Memory / +Personal Memory, injection scan, provenance preamble and temporal guidance. +`buildSystemPrompt` adds identity, memory stats, top-5 frames, awareness, top-10 entities and +5 personal preferences. + +## Automatic writes + +After each chat turn (pattern write-back, entity extraction), context compaction summaries, +agent collaboration results, sub-agent completion, waggle-dance signals, loop cron, weaver +(hourly consolidation, daily decay/strengthen, transcript distillation), harvest auto-sync and +cron, connector fetch, nightly memory-lane extraction, compaction and reindex crons, weekly +workspace health flags, monthly assessment, team sync, vector enrichment, file upload indexing, +workspace template starter frames, harvest commit. + +## Call patterns the contract must cover first + +1. Write into a chosen mind with importance and source; duplicates return the existing memory. +2. Ranked search per mind with limit and date window; result needs id, text, importance, + source, created time, kind. +3. Prefix and importance lanes, which become `kinds` and `minImportance` filters. +4. Recent listing for the context loader, Memory Center and home. +5. Metadata, get, update and delete by id, with no id collisions across minds. +6. Personal plus many workspace scopes, and cross-workspace search. +7. Named buckets (harvest, agent-runs, loop, memory-lanes…), which become `origin`. +8. Identity singleton and awareness items: not memory, they move to `waggle.db` (ADR-0007). +9. Knowledge graph: hidden in v1. +10. Maintenance (re-index, decay, compaction, replace-on-update, erasure, counts). diff --git a/docs/oss/upstream-fixes.md b/docs/oss/upstream-fixes.md index f584736..50d1c68 100644 --- a/docs/oss/upstream-fixes.md +++ b/docs/oss/upstream-fixes.md @@ -53,6 +53,8 @@ Baseline: commit `b20b138` of `git.os-dev.tech/oleg.m/waggle-os`. | UF-022 | Unit tests write into the developer's real `~/.waggle` | Fixed | Tests | | UF-023 | Four unit-test files fail on macOS | Open | Tests, macOS | | UF-024 | Workspace packages import packages they do not declare | Fixed | Build, packaging | +| UF-025 | Workspace chat writes entities and error-path messages into personal memory | Open | Memory, privacy | +| UF-026 | Three memory tools of the agent are never wired | Open | Agent, memory | ## Entries @@ -244,3 +246,21 @@ Entries UF-010 to UF-019 come from the UI audit `anti-slop/audit-001-2026-10-14. - Cause: no check compares imports with declared dependencies. - What we did: declared the missing dependencies (`playwright-core` as an optional peer, because `agent` loads it only when available; `@waggle/server` as a dev dependency of `launcher`, because its build bundles `@waggle/*`), removed the unused ones, and added `scripts/check-workspace-deps.mjs` (`npm run check:deps`) to CI. - Recommendation: apply the same declarations in the main project and run the check in CI. + +### UF-025. Workspace chat writes entities and error-path messages into personal memory +- Status: Open +- Found: 2026-10-16 +- Where: `packages/server/src/local/index.ts:1298` (`createSessionOrchestrator` builds every session orchestrator on `multiMind.personal`); `packages/server/src/local/routes/chat.ts:3435` and `:3786` +- Symptom: in a workspace chat, entities extracted from the agent's answer and, on the error path, the user's message are written to the personal mind, not to the workspace mind. The comment at `chat.ts:3428` says they go to "the knowledge graph of the active workspace mind". Workspace content leaks into personal memory, which follows the user into every other workspace. +- Cause: `getKnowledge()`, `getFrames()` and `getSessions()` on the orchestrator return the layers of the database it was built on, which is always the personal one; the workspace mind is only attached with `setWorkspaceMind`. +- What we did: nothing in the old code. Found by reading the code, not reproduced at runtime. In the community edition these writes move to the memory contract in P1.5, where the scope is explicit on every call. +- Recommendation: write through the workspace layers when a workspace mind is attached, and add a test that a workspace chat leaves the personal mind unchanged. + +### UF-026. Three memory tools of the agent are never wired +- Status: Open +- Found: 2026-10-16 +- Where: `packages/agent/src/orchestrator.ts:187` (the only `createMindTools` call); `packages/agent/src/tools.ts:96-109`, `:314`, `:474`, `:657` +- Symptom: `search_all_workspaces` searches only personal memory although its description promises all workspaces; `correct_knowledge` always answers "Feedback handler not available. Cannot correct knowledge."; the embedding-based duplicate check in `save_memory` never runs. +- Cause: `createMindTools` is called without `getAllWorkspaceSearches`, `feedback` and `embedder`, and each tool silently falls back when its dependency is missing. +- What we did: nothing in the old code. In the community edition these tools are rebuilt on the memory contract in P1.5. +- Recommendation: pass the three dependencies, or remove the tools whose dependency cannot be provided so the agent is not offered a tool that cannot work.