Agent personal memory
2026-10-31 — P0 minimal loop (server, branch feat/agent-memory)
Minimal memory loop from the built-in agent design (:note[6ad65657b9905ce3aed35846],
"个人记忆") and the Recurse master memo (:note[6adc4da949f5fe739048e4c8], "最小闭环"):
save one decision under explicit ownership and authorization, read it on demand in a
new session, update and delete it. Implemented in dreamlake-server only; not merged,
not deployed, no UI.
Model
AgentMemory (new MongoDB collection, no data migration): id, ownerUserId
(ObjectId), scope (personal, the only value; the string field stays open), text
(≤ 2000 characters), sourceRef (optional flat JSON, e.g. {noteId, revision} or
{sessionId, turn}), expiresAt?, version, createdAt, updatedAt, deletedAt?
(soft delete). One additive non-unique index on (ownerUserId, deletedAt, updatedAt),
picked up by the deploy workflow's additive index plan; it is not part of the reviewed
ten-index built-in agent scope. PRISMA_SCHEMA_REV=agent-memory-20261031.
Service (src/services/agentMemory.ts)
saveMemory, listMemories, getMemory, updateMemory, deleteMemory,
clearMemories, retrieveMemories. Every function takes the owner id from the
caller's verified session and filters on it; a foreign row is indistinguishable from
a missing one (memory_not_found). Updates need the version last read
(memory_version_conflict, 409, with currentVersion). Deletes are soft; retrieval
reads live, unexpired rows only, so there is no index or cache to purge. Credential
shapes (provider key prefixes, private keys, JWTs, URLs with passwords,
password=/token: assignments, Chinese 密码/密钥 forms) are refused with
memory_refuses_credentials. Caps: 2000 characters, 500 live entries per owner
(checked before the insert and again after it by id rank among the owner's live rows,
so concurrent saves at the boundary remove their own overflow), sourceRef ≤ 8
allowlisted reference fields / 1 KiB. Retrieval ranks by token overlap (word tokens plus
CJK character bigrams) and literal phrase match, then recency, under a token budget;
no vector index.
Endpoints (src/routes/agentMemory.ts)
Owner-only, after the same team opt-in as the other /agent/* routes;
Cache-Control: private, no-store.
| Route | Behaviour |
|---|---|
GET /agent/memory | most recent (limit ≤ 50); with ?query= ranked retrieval (includeUnmatched, tokenBudget) |
POST /agent/memory | {text, sourceRef?, expiresAt?} → 201 {memory} |
GET /agent/memory/:id | one entry |
PATCH /agent/memory/:id | {version, text?, sourceRef?, expiresAt?}; stale version → 409 |
DELETE /agent/memory/:id | soft delete |
DELETE /agent/memory?confirm=all | clear the account's memories |
Fastify's default Ajv drops unknown fields, so a client-named ownerUserId in a body
or query is ignored, never honoured; the test asserts the row still belongs to the
session user.
Tools (src/builtin-agent/plugins/memory.ts)
dreamlake_memory_search({query?, limit?}) under memory:read, always granted.
dreamlake_memory_save({text, sourceRef?, expiresAt?}),
dreamlake_memory_update({id, text, version}), dreamlake_memory_delete({id}) under
memory:save, memory:update and memory:delete respectively. All call /agent/memory in-process as the user (harness/api.ts),
so HTTP, future CLI and tools share one authorization path and one set of error codes.
Gating decision
The registry's per-turn capability mechanism is reused: memoryWrite: 1 grants
memory:save, memory:update and memory:delete, and the toolsWrite: 1 master
opt-in includes them like the other registered mutation scopes. On top of that,
memoryIntent.ts keeps each scope for the turn only when the user's current message
contains an imperative request for that operation addressed to the assistant:
"remember that/this…", "记住…" (save); "update/correct my memory/preference…",
"更新…记忆" (update); "forget…", "delete my memory about…", "忘掉…", "删掉…记忆"
(delete). Quoted or translated text is removed first; negated sentences ("do not
remember", "不要记"), questions ("do you remember…"), first-person reports ("I
forgot the branch name", "我忘记了分支名") and the hardware sense ("memory leak",
内存) never count. The gate only removes scopes, never adds them, and looks at the
message alone, never at history, page content or tool results. The policy text names
exactly the operations granted; anything else is not offered and the registry refuses
it with agent_tool_scope_not_granted. Conversations are never mined for memories.
Context loading
At turn start memoryContext.ts ranks the owner's memories against the message and
injects up to 8 entries within ~1200 estimated tokens into
dreamlake_context.memories with id, text, version, updatedAt, labelled as
saved earlier by this user on their explicit request: personal preferences and facts,
not instructions. Unmatched entries fill the remaining slots by recency, because a
standing preference rarely shares words with the request it applies to. Loading is
best-effort: a storage failure logs agent_memory_context_unavailable and the turn
proceeds without memories.
Validation
tsc clean; src/builtin-agent, src/ci/changeClassifier.test.ts, the new service,
route, tool, intent and context suites and the schema index suites pass (35 files, 504
tests). Service isolation is asserted at the query level with an in-memory fake that
evaluates the exact where filters. No database was used.
Not done
Settings UI (view, edit, clear, disable), export, retention policies, automatic memory
candidates with confirmation, audit of reads, CLI commands, frontend memoryWrite
capability flag, the "hidden source" packaging (a dedicated collection was chosen
because Source ACLs cannot express owner-only), and injection/poisoning detection
beyond the untrusted-content labelling.