Memory Bank

Per-profile long-lived memory: structured saves, multi-signal relevance ranking, and automatic prompt injection.

What is the Memory Bank?

The Memory Bank is a profile-scoped store of long-lived knowledge that survives across every session of an agent. It captures preferences, facts, behaviors, and short-lived context the agent has decided to remember, and surfaces the most relevant entries back into the prompt on every run.

Two delivery channels:

• Automatic injection — every run for a profile that opts in to @memory gets a prefixed --- CONTEXT FROM MEMORY --- block built from the core tier plus query-relevant entries.
• On-demand — agents can call memory_save, memory_recall, memory_list, or memory_delete at any point during a run.

The bank is a port of the Brain Dump relevance model. No embeddings — keyword overlap plus a small set of domain-specific clusters bridges the lexical gap between query and memory.

---

Storage Layout

Memories are persisted to the same S3-compatible bucket as artifacts, under a dedicated prefix:

memory/<profileName>/<memoryId>.json

<memoryId> is mem-<8hex>, matching Orca’s other ID conventions (run-, sess-, agent-, pool-).

The in-memory index is the runtime source of truth; S3 is the persistence tier hydrated at startup via LoadAll. A successful save does not return until the object lands in S3, so a crash never loses an explicitly saved memory. When S3 is not configured the bank still operates — degraded to in-memory only.

---

Memory Schema

type AgentMemory struct {
  ID               string    // "mem-<8hex>"
  ProfileName      string
  RawInput         string    // verbatim, audit trail
  ProcessedContent string    // LLM-normalized, retrieval-friendly
  Summary          string    // <50 chars, used in lists
  Category         string    // preference | fact | behavior | context | general
  Source           string    // explicit | inferred (v2)
  Confidence       float64   // [0, 1]
  CreatedAt        time.Time
  LastAccessedAt   time.Time
  AccessCount      int
  StalenessScore   float64
  IsActive         bool
  Version          int       // schema version
}

RawInput is capped at 4 KiB. Larger inputs are rejected with a clear error.

Categories

Category	Decay	Retrieval role
preference	Slowest	Eligible for the always-injected core tier
fact	Slow	Eligible for the core tier
behavior	Normal	Query-only
context	Fastest	Query-only — meant to age out quickly
general	Normal	Query-only

The core tier is preference + fact entries with confidence >= 0.8, ordered by confidence then access count. Cached per profile for 5 minutes to keep the run hot path off S3.

---

Relevance Scoring

QueryWithRelevance ranks active memories by a composite score:

score = (wR * recency  +  wU * usage  +  wT * topic) * confidenceMul

Signal	Default weight	Behavior
Recency	0.35	Exponential decay, 30-day half-life, anchored at the more recent of CreatedAt and LastAccessedAt
Usage	0.30	Logarithmic ramp from a 0.6 baseline (never accessed) toward 1.0 (heavily accessed)
Topic	0.35	Tokenized word overlap (stopwords removed) plus semantic-cluster matching
Confidence	multiplier	0.5 + 0.5 * confidence — low-confidence saves never dominate the ranking

Maturity

Until the bank has accumulated query history, recency and topic dominate. The maturity factor is min(1, totalAccesses / 50) — once a profile has crossed ~50 cumulative recalls, the usage weight reaches its full 0.30, and the slack from the early-bank period is redistributed back to recency and topic.

Semantic clusters

Eight built-in vocabulary groups bridge cases where a query and a memory share a topic but no literal words. A “diet” query still matches a “peanut allergy” memory through the food cluster. Clusters: food, health, work, tech, travel, entertainment, communication, shopping. A non-zero contribution requires the cluster to appear on both sides.

Staleness

Each memory carries a stalenessScore in [0, 1] recomputed on every save and access:

staleness = (daysSinceAccess * 0.05  -  log10(accessCount+1) * 0.2  +  (1 - confidence) * 0.3) * categoryWeight

Category weights tilt the decay: preference=0.5, fact=0.7, behavior=1.0, context=1.5, general=1.0. The score is surfaced for inspection but does not currently gate retrieval (Brain Dump parity).

---

Prompt Injection

Profiles that opt in to the @memory capability receive an automatic context block prepended to every run’s prompt:

--- CONTEXT FROM MEMORY ---
Core knowledge (always apply):
* [preference] The agent prefers returning structured JSON whenever the caller supplies a schema.
* [fact] Plans are persisted as JSONL objects at plans/<planId>.jsonl in the artefact bucket.

Relevant to this task:
* [behavior] Before reading a file, the agent should call list_dir on the parent directory first.
---
<user prompt here>

Two soft caps shape the block:

Cap	Default	Notes
Character budget	2000 chars (~500 tokens)	Query-relevant tier is trimmed first, core tier last
Query results	8 memories	Pulled with minScore = 0.05, excluding any IDs already in the core tier

After the block is rendered, the IDs that made it in are passed to MarkAccessed fire-and-forget — accessCount and lastAccessedAt update without blocking the run.

Profiles without @memory (or any of the four memory_* tools by name) never receive injection. Same opt-in shape as @artifacts.

---

LLM Processor

When an agent saves a memory with only rawInput (no pre-structured processedContent), the bank consults a fast LLM to extract processedContent, summary, category, and confidence. The processor is a thin wrapper around Anthropic’s Messages API with a 5-second deadline.

Configuration:

Variable	Default	Notes
ANTHROPIC_API_KEY	—	Required to enable LLM extraction
ANTHROPIC_MEMORY_MODEL	claude-haiku-4-5	Override the extraction model

When the key is unset, or the call fails, or the response is malformed, the bank falls back to a deterministic preview: processedContent = rawInput, summary = first 50 chars, category = general, confidence = 0.5.

---

Memory Tools

@memory is opt-in (not in @default). Every tool requires session context and operates against the session’s profile.

Tool	Description
memory_save	Save a memory. Provide rawInput for free-text (LLM extracts structure) or content/category/confidence for pre-structured saves.
memory_recall	Search by topic. Returns ranked results with the relevance breakdown attached. Bumps accessCount for every returned memory.
memory_list	List newest-first with limit / offset paging. Read-only — does not affect access counts.
memory_delete	Remove a memory by id.

{
  "name": "researcher",
  "tools": ["@default", "@memory"]
}

Selecting @memory (or naming any memory_* tool individually) both registers the tools and enables prompt injection.

---

REST API

All endpoints return 503 Service Unavailable when the bank is not wired. Reads call a 2-second TTL RefreshIfStale so the dashboard sees runner-side saves promptly without paying for an S3 round-trip on every request.

Per-profile

Method	Path	Description
GET	/api/profiles/{name}/memories	List with limit / offset
POST	/api/profiles/{name}/memories	Create — body is MemoryCreateRequest
GET	/api/profiles/{name}/memories/search	Query with q, limit, minScore
GET	/api/profiles/{name}/memories/{id}	Get one
DELETE	/api/profiles/{name}/memories/{id}	Delete one

Global

Method	Path	Description
GET	/api/memory-bank	All memories grouped by profile, or a flattened page with limit / offset, q, and category
GET	/api/memory-bank/stats	Roll-up: total memories, profiles with memory, per-profile counts

See the Conductor API reference for request and response shapes.

---

Configuration

The bank shares the artifact store’s environment contract — see Storage and Files. When S3_BUCKET is set it boots in fully persistent mode; otherwise it runs in-memory only and logs a warning at startup.

Variable	Description
S3_BUCKET and friends	Persistence layer (shared with artifacts)
ANTHROPIC_API_KEY	Enables LLM extraction in memory_save
ANTHROPIC_MEMORY_MODEL	Optional override for the extraction model

Both the runner and the conductor build their own bank from these variables. The runner’s bank is the source of truth on writes; the conductor’s bank is read-through synced every 2 seconds for dashboard reads.

---

Limits and Caveats

• Per-profile scope only. Memories are not shared across profiles or pools — by design. Use pools and the shared filesystem for cross-agent state.
• Listing cap. LoadAll walks at most 1000 entries per profile (the underlying ListObjectsV2 page cap). Banks larger than that need pagination plumbed through ListInput.
• No retention enforcement. Staleness is computed but not acted on. Operators delete cold memories by hand or via the dashboard.
• MarkAccessed is best-effort. Access count and timestamp updates persist asynchronously; a runner crash within a few seconds of a recall may lose them.
• Source inferred is reserved for v2. All v1 saves carry source: "explicit"; future post-run extraction will populate inferred.