Agent Memory

The AI is good at reading code and conversations, but once a session ends it forgets “what it can do in this workbench.” As a result, it often re-misjudges a task it already succeeded at (deploy, build, DB access) in the next session as “can’t do it — no credentials.”

Agent Memory lets the AI store verified facts in an exact-match drawer and automatically pull them back out in the next session. It doesn’t compete with RAG (approximate semantic search); instead they divide the labor — fact judgment goes to the drawer, approximate search goes to the library.

Why it’s needed — starting from a real incident

Deploying Blyck was directly possible on this PC (the aws CLI is configured, with a history of direct deploys) and the procedure was documented. Yet every session the agent repeatedly misjudged that it “can’t deploy — no credentials.” The cause was reasoning, from the code comments alone, that “a separate step = I can’t do it.”

On diagnosis, the weak link was capture, not recall.

Stage	Status	Basis
recall	OK	Had it been stored, it would clearly have been read
capture	Failed	”This PC can deploy” had never once been persisted

In other words, it wasn’t that it couldn’t remember — the item to remember was never created in the first place. An action (one s3 cp) looks volatile, but the capability it proves (“can deploy”) is a persistent, reusable fact. Failing to make that distinction was the blind spot.

Core principles

Memory does not go into the RAG soup. Fact/capability memories are pulled by exact match, not approximate semantic search.
Capture does not depend on self-awareness. Successful actions are automatically promoted to capability candidates (with an approval gate).
Recall is auto-injected. Relevant memories enter the context without a call.
Verify before claiming inability. Before saying “can’t do it,” check the memory and verify with a cheap probe.

Analogy — the library and the desk drawer

📚 Library search (RAG): piles up all the code, conversations, and logs and “finds something similar.” It’s large and approximate, so garbage gets mixed in. → For “where was that similar code from before?”
🗂️ The note drawer on the desk (Memory): just a few verified core facts, kept tidy. Precise and always visible. → For “this PC can deploy,” “don’t touch PROD DB.”

RAG and Memory don’t compete — they divide the labor. Fact judgment goes to the drawer (first priority); approximate search goes to the library (supporting role).

The typed exact-match drawer

Memories are stored as typed records in a dedicated table in workspace.sqlite.

Field	Description
`type`	`capability` · `decision` · `rule` · `procedure` · `fact`
`scope`	`workspace` (default) · `global`
`key`	Exact-match identifier (e.g. `deploy:blyck`)
`body`	The human-readable fact body
`confidence`	0–1 (verified = 1.0)
`proof`	The basis (e.g. “aws sts passed; s3 cp succeeded”)
`status`	`active` · `stale` · `retired`

Capture — triple-covering the weak link

Method	Trigger	Garbage blocking
Explicit	The `memory_write(key, body, type, scope)` MCP tool	Intentional calls only
Auto-promotion	Detects success events (deploy, build, auth, DB access) in the activity log → creates a candidate	Approval gate
Reflection pass	Session summary at chat end / milestone → extracts “persistent facts learned?” candidates	Approval gate

All three paths enter the drawer only after approval, so there’s no RAG-style auto-suction noise.

Examples of success events the auto-promotion classifier raises to capability candidates:

External auth/deploy success (aws … succeeded, gh auth, deploy/publish) → capability
Build/packaging success (npm run dist, tests passing) → capability/procedure
DB/SSH connection success (credential verified) → capability
A rule the user gave as a command (“don’t touch PROD”) → rule
Things too trivial or one-off (a simple file read, etc.) are excluded — to avoid approval fatigue

Recall — auto-injection

When assembling the context each turn, a memory-retrieval step is inserted.

Exact key match + light semantic match against the current query, active panels, and project.
The top-k active memories are auto-injected into the system prompt (no separate call needed).
recency · importance weighting + decay → memories unused for a long time go stale → retired.

AI tools (MCP)

Tool	Permission	Role
`memory_write(key, body, type, scope)`	Confirm	Explicitly stores a fact in the drawer (same key overwrites)
`memory_read(key?/query?)`	Read (automatic)	Retrieves a memory by exact `key` match or light semantic match

Most recall is handled by auto-injection, so you don’t need to call memory_read for every item. Use it to fill in items that auto-injection missed.

Decay and cleanup

To keep the drawer from bloating, memories unused for a long time are cleaned up based on last_seen.

capability · rule · procedure are exempt from auto-expiry — the goal is to prevent the incident above from recurring. A once-verified capability does not disappear even if unused.
Only decision · fact go stale at 90 days, retired at 180 days.
An explicit lookup revives stale → active.

End-to-end flow — today’s case

[Capture] first successful deploy → activity log "s3 cp blyck-releases succeeded"
   → promotion classifier detects → candidate {capability, key:"deploy:blyck",
      body:"This PC can deploy directly: npm run dist → s3 cp → cloudfront invalidate",
      proof:"aws sts passed; s3 cp succeeded"} → [approve] → pinned into the drawer

[Recall] next session "deploy it" → context assembly auto-injects "deploy:blyck"
   → inferring "no credentials" becomes impossible → zero repeat incidents

Relationship to Claude’s file memory

This feature borrows the precise, automatic recall of Claude Code’s file memory (MEMORY.md + *.md, auto-loaded every session) as is, while shoring up its weaknesses.

Item	Claude file memory	Blyck exact-match drawer
Storage location	Markdown files	workspace.sqlite table
Capture trigger	Agent judgment (manual)	Manual + action auto-promotion + reflection pass
Auto-capture	✗	✓ (success-event promotion)
Garbage	Low	Near-zero (UNIQUE key + approval)
Duplicate prevention	Human manages the index	`UNIQUE(scope, key)` automatically
decay/cleanup	Manual	`last_seen`-based stale/retire
Domain awareness	General	Specialized for Blyck activity (deploy · DB · SSH)

The decisive difference is auto-capture. The incident above happened with Claude file memory enabled — recall was fine, and the weak link was that “capture depends on judgment.” Blyck has the activity log as a record of actions, so it can auto-promote success events to capability candidates — something structurally impossible with file memory alone.

Security

Cross-chat memories default to scope=workspace with a sensitive-info filter, so they don’t conflict with the principles of global sessions being non-transferable and read-only.
Secrets are not stored in the memory body (the OS encrypted store + automatic masking is a separate path).

FAQ

Q. If there’s RAG, why is memory needed too? → RAG is approximate-semantic, so garbage gets mixed into fact judgment. A verified fact like “this PC can deploy” must be pulled 1:1 from the exact-match drawer to be safe. The two divide the labor.

Q. Do I have to say “remember this” every time? → No. You can store explicitly with memory_write, but success events surface as auto-promotion candidates that you only need to approve. At chat end, the reflection pass also extracts rules automatically.

Q. Won’t a wrongly stored memory keep following me around? → The same key is overwritten, and decision/fact are cleaned up by decay. You can update a wrong capability memory with memory_write or retire it.

Q. If a verified capability disappears from disuse, won’t the incident happen again? → That’s exactly why capability · rule · procedure are exempt from auto-expiry. A once-verified capability stays in the drawer even when unused.