| name | memory-management |
| description | When and how to use the memory stores in Retainer. Adapted to current shape (narrative + facts via the librarian; CBR + remembrancer V1 shipped; threading + artifacts deferred). |
| agents | cognitive, observer |
Memory Management
Two stores today
| Store | What goes there | How to access |
|---|
| Narrative | One entry per cycle: cycle_id, timestamp, status, summary (user input + reply or error). Append-only on disk. The librarian indexes the last 60 days into SQLite for fast recall. | recall_recent (observer agent), agent_observer for inspect_cycle |
| Facts | Key/value entries with scope (persistent / session / ephemeral) and confidence. Most-recent-per-key wins on lookup. JSONL on disk; index has no time window — facts are current state. | memory_write, memory_read, memory_clear_key, memory_query_facts (cog), get_fact (observer agent) |
Which tool for which question
| Question | Use this | Why |
|---|
| "What did I just do?" / "What was that about?" | Cog: nothing — already in your conversation context | Don't call tools for stuff in the live window |
| "What did I do today / earlier / last session?" | Delegate to agent_observer with recall_recent | Pulls narrative entries from the librarian |
| "What's the status of cycle X?" / "Why did that fail?" | Delegate to agent_observer with inspect_cycle | DAG status + narrative summary + error for one cycle |
| "Did I store a value under key K?" | Cog: memory_read | Direct lookup, no delegation |
| "Search facts containing the word 'mustang'" | Cog: memory_query_facts | Direct keyword search, no delegation |
| Save a value to remember later | Cog: memory_write | Direct write |
| Forget a stored value | Cog: memory_clear_key | Direct tombstone (history preserved on disk; index returns nil afterwards) |
Rule of thumb: cog tools are synchronous and cheap. The observer adds value when the user wants formatted cycle inspection or a curated recall, not when they want a single key/value lookup.
Facts: when to write
Write a fact when:
- The user tells you something that should survive cycles ("my name is Seamus", "the Cavan price is X")
- You discover a reusable configuration ("Mistral Small 4 handles X better than Y")
- A computation produced a value the next cycle will want
Use scopes correctly:
- Persistent — survives across sessions; the default for "remember this for me"
- Session — current run only; cleared by clearing the key
- Ephemeral — short-lived; would be cleared at end-of-cycle once that hook lands (today behaves like session)
Don't write facts for:
- Things already in your conversation history (the window has them)
- Long content (no artifacts subsystem yet — wait for that to land)
- Self-narration about your own performance
Confidence matters. If you're not sure, write 0.5–0.7 rather than 1.0. Confidence decays at read time via half-life so older uncertain facts naturally weaken.
Reading facts honestly
memory_read returns the most-recent non-cleared entry with confidence decayed to now. If a fact comes back with low confidence:
- Treat it as a hint, not gospel
- Verify it before acting on it (re-read narrative, ask the user, or just say the value out loud and check the operator's reaction)
If memory_read returns "No fact found" — say so. Don't fabricate a remembered value.
Remembrancer — deep archive (V1 agent shipped)
For history older than the librarian's hot index, delegate to
the Observer specialist via agent_observer. It owns the
deep-archive read tools and reads JSONL files directly (the
immutable archive), not the librarian's index.
| Tool the Observer has | Use for |
|---|
deep_search | Free-text search across the full narrative + facts archive. Use when recall_recent / memory_query_facts come up empty and the answer might be older than the index window. Also reads weekly consolidation digests under data/knowledge/consolidation/ and the mined-cluster log at data/patterns/patterns.jsonl. |
find_connections | Surface relationships between cycles / facts that share themes or terms. Use to triangulate "what else have I done in this area?". |
Pattern mining and weekly consolidation no longer happen on
demand. The metalearning pool (internal/metalearning/) runs
those as background workers on a tick: daily mining clusters CBR
cases into data/patterns/patterns.jsonl; weekly consolidation
writes a markdown digest to data/knowledge/consolidation/. The
Observer reads those durable artifacts via deep_search — it
does not regenerate them. When the user asks "what patterns are
emerging?" or "what was learned this week?", brief the Observer
to read the corresponding artifact.
The Observer is a delegated agent (matching SD's shape). Don't
try to call its tools directly from the cog — they're not on your
registry. Brief it via agent_observer with a specific question.
See agents-using-observer for briefing patterns.
When the user asks for something archival ("what did I work on
three months ago?", "find every time we discussed auth", "show me
last week's review"), this is the right delegate.
Still deferred
These belong in this skill but the subsystems aren't shipped yet — DON'T pretend you have them:
- Threads (overlap-scoring narrative grouping). No
recall_threads.
- Artifacts (50KB-truncated content store). No
store_result / retrieve_result.
- Memory trace (full key history). No
memory_trace_fact.
If the user asks for any of these, say what's not available. Do NOT pretend by approximating with the tools you have.
