harness-memory

name	harness-memory
description	Mechanics of Retainer's current memory layer — what's narrative vs facts vs cases, when each is written vs read, retention semantics, who can see what. Read with `memory-management` (which covers the decision procedure).
agents	cognitive, researcher, observer

Memory mechanics

This skill covers the mechanics: where data lives, who writes it, how long it persists. For the decision procedure (when to use which store), read memory-management.

Three stores

Store	What's in it	Disk	Index window
Narrative	One entry per cycle: cycle_id, summary, status. Append-only JSONL.	data/narrative/<date>.jsonl	60d rolling (librarian)
Facts	Key/value with confidence, scope. Most-recent-per-key wins.	data/facts/<date>.jsonl	None — current state
Cases (CBR)	Problem/solution/outcome triples. 6-signal retrieval.	data/cases/cases.jsonl	None — full archive

Disk is immutable

Per project_archive_immutable: memory JSONL files are NEVER deleted or edited. Updates land as new entries. The librarian (SQLite hot index) prunes old entries from the index, but the disk JSONL is the source of truth for the deep archive.

This means: a memory_clear_key writes a tombstone, it doesn't delete history. The next memory_read on that key returns "no fact" because the index respects the tombstone, but the remembrancer's deep_search could still find the original.

Who writes what

• Cog writes narrative (one entry per cycle, on cycle_complete) and facts (via memory_write).
• Archivist writes cases (derived from cycle outcomes via the judge — happens automatically; you don't trigger it).
• Agents don't write to long-term memory directly. Their reply is the deliverable; the cog decides what to remember.

Who reads what

Tool	Reads	Available to
memory_read	Facts (librarian hot index)	Cog
memory_query_facts	Facts (keyword search, hot index)	Cog
recall_recent	Narrative (recent N, hot index)	Observer
inspect_cycle	Narrative + DAG (hot index)	Observer
get_fact	Facts (hot index)	Observer
recall_cases	Cases	Observer (via agent_observer)
case_curate	Cases (action-discriminated mutation)	Observer (via agent_observer)
deep_search	All JSONL (full archive, incl. reports + patterns log)	Observer (via agent_observer)
find_connections	All JSONL (full archive)	Observer (via agent_observer)

The librarian's hot index gives the cog + observer fast reads over recent material. The deep-archive read surface (full JSONL, months/years) is owned by the Observer agent — the cog reaches it via agent_observer, not by calling the tools directly. See agents-using-observer for routing.

Pattern mining and weekly consolidation no longer have tools. They run on the metalearning pool (internal/metalearning/) on a tick — daily mining writes mined-cluster JSONL to data/patterns/patterns.jsonl; weekly consolidation writes a markdown digest to data/knowledge/consolidation/. The Observer reads those durable artifacts via deep_search rather than regenerating on demand.

Confidence + decay

Facts carry a confidence (0.0–1.0) at write time. Reads decay it based on age (half-life — see internal/decay/). A fact written months ago with confidence 0.9 might come back as 0.5.

Practical: write what you actually believe. 1.0 confidence is fine for hard facts ("user's name is X"); use 0.5–0.7 for inferences and observations.

Scopes

• Persistent — survives sessions; the default for "remember this for me"
• Session — current run; cleared by cog restart
• Ephemeral — short-lived; today behaves like session (end-of-cycle clear isn't wired)

What's NOT in memory

• Your conversation context window — that's not "memory" in the store sense, it's just the in-flight turn data.
• Skills — those are static workspace files, not store entries.
• The cycle log — diagnostic telemetry, not retrievable via the memory tools (use inspect_cycle or read JSONL directly).

Practical advice

• Don't write self-narrating facts like "I helped the user with X today." That belongs in narrative (which writes itself per cycle).
• Don't write huge content as a fact. The artifacts subsystem for big content isn't shipped; right now long fact values waste retrieval bandwidth.
• Read once, act: if you've already done memory_read('k') this turn, don't do it again next turn. The value's in your context.