Experiment: named core memories and bounded recall

[vangheem]

Purpose: an experimental memory playground

This draft explores whether a small library of named, editable memories is a better foundation than append-only notes. It is a prototype for discussion and iteration, not a production rollout or a claim that memory now makes agents faster.

Based on #155 so the diff stays focused on memory rather than including the existing Code Mode changes again. It can be rebased onto main when that work lands.

Companion application playground: nuclia/data-platform#1334. Consumer-specific storage, prompts, and observations stay there rather than in the framework documentation.

Architectural overview and critical paths

• Keep the existing remember, recall, and forget tools; do not add a separate update tool. remember requires a short stable name and upserts the corresponding scoped record. forget also addresses records by name. Prototype records are disposable: there is no legacy compatibility or migration layer.
• harness_sdk/memory.py derives stable IDs from name, scope, and application identity. Conversation/agent IDs are deliberately excluded so a fresh session can reuse the same entry. The common user/project scopes select the applicable identity fields, and applications can additionally provide a stable memory namespace.
• remember point-reads through the storage protocol, checks scope/namespace, preserves creation time, and replaces the full text after a correction. Identical text is a no-op. Write events distinguish created from updated so consumers do not confuse replacement with memory growth.
• recall supports exact-name point reads and bounded topic search: default five results, maximum fifty. The process-local store filters namespaces before applying limits and ranks lexical overlap in names/text. This is intentionally not semantic/vector retrieval.
• Storage adapters gain get_memory and a namespace argument for recall. Deterministic IDs prevent same-key appends, but are not authorization: production adapters must enforce their own tenant/user boundaries. Concurrent writes are last-writer-wins, not compare-and-swap or semantic merging.
• A recall-disable execution-context setting supports controlled cold-memory experiments without deleting data or changing upsert behavior, including exact-name reads. The setting follows the existing child-context inheritance path.
• Framework-neutral documentation describes the API, storage obligations, safety limits, and tradeoffs. The examples contain no consumer-specific schemas, tools, or project names.

Why these choices

• Anthropic's memory tool treats memory as addressable, editable notes with bounded reads and application-owned storage. Short named records are a database-backed analogue of that interface, not an attempt to copy its file-command API.
• Anthropic's context-engineering guidance favors the smallest useful context, just-in-time retrieval, and avoiding overlapping/bloated tool sets. That motivates bounded recall and extending remember rather than adding an update_memory capability.
• LangGraph's memory overview uses namespace/key stores and discusses continuously maintained collections, over-insertion versus over-updating, and hot-path/background-write tradeoffs. Explicit identity and replacement semantics make those decisions visible rather than silently appending on every save.

These sources motivate the experiment; they do not establish that this particular implementation is optimal. Domain-specific policies about what to remember belong to the application, not the generic framework.

Deliberate limitations / open questions

• Same names overwrite; different names remain different entries. Naming does not solve semantic duplicates, poor recipe quality, or conflicting concurrent corrections.
• No embedding service, automatic consolidation, expiration policy, or background memory-writing agent is introduced. Those add cost and complexity and should follow measured need.
• Current consumer experiments showed that the lifecycle works but did not establish a reliable latency improvement. A useful next evaluation is whether the model stores an executable successful route rather than vague advice, and whether that reduces subsequent discovery.
• The storage contract is changing while the feature is unused/prototypical. Publication and consumer adoption are intentionally separate follow-up decisions.