Memory System

AGH memory is curated Markdown that survives across sessions. It is designed for durable facts that future agents should be able to discover without replaying every old transcript.

The current implementation is intentionally hybrid:

• curated semantic memory (user, feedback, project, reference) is Markdown-authoritative on disk
• memory_decisions is a per-database write-ahead log: every controller decision lands there before any file mutation
• memory_events is the canonical observability log for memory operations
• memory_catalog_entries, memory_chunks, and FTS5 indexes are derived projections
• memory_recall_signals and memory_consolidations carry live runtime state for dreaming
• there are three scopes: global, workspace, and agent — agent has two tiers
• only the frozen startup snapshot is injected into prompts; new writes become visible to the next session

Runtime Flow

Memory is not streamed into an already-running process. When a session starts, AGH captures a frozen snapshot of the resolved scopes, packages a recall block, prepends the assembled memory section to the agent prompt, and hands that prompt to the ACP subprocess. Writes during the session are durable immediately but only become visible to the next session via a fresh snapshot.

Scopes And Authorities

Read precedence is agent-workspace ▸ agent-global ▸ workspace ▸ global. Identity is keyed by (type, slug) per scope, and a deeper scope shadows a shallower scope with the same identity. The runtime never silently merges shadowed entries — see Scopes.

Scope is selected explicitly. --scope agent requires --agent <name> and a validated --agent-tier {workspace, global}; the agent tier defaults to workspace when omitted. CLI/HTTP/UDS operator writes that omit --scope fall back to a conservative type-driven default for the non-agent scopes only: user and feedback → global, project and reference → workspace. Agent scope must be explicit.

Workspace Identity

Workspace memory is keyed by a stable ULID stored in <workspace>/.agh/workspace.toml:

workspace_id = "01HXJ9YR4Q..."
created_at   = "2026-05-04T14:30:00Z"
realpath_at_creation = "/Users/you/dev/checkout-api"

The runtime resolves the workspace by walking ancestors for .agh/workspace.toml, reads the ULID, and uses that as the durable identity for catalog rows, events, decisions, dreaming runs, and session ledgers. Path-keyed memory is gone — moving the workspace directory does not orphan its memory because the ULID travels with the directory. See Workspace Resolver for the lookup cascade.

Four Memory Types

Every curated memory file declares one of four types:

The taxonomy is closed. Unsupported types are rejected at the controller boundary.

Memory File Format

Memory files are Markdown with strict YAML frontmatter. The canonical YAML key for the agent name is agent; JSON and HTTP payloads use agent_name.

Example feedback memory written through the controller:

---
name: Test Integrity
description: Production bugs must be fixed instead of weakening tests
type: feedback
scope: global
provenance:
  source_actor: extractor
  source_sessions:
    - 01J7VR2Q8MZ4FXWZ8WB7M2A4S0
  confidence: high
  created_at: 2026-04-12T14:32:11Z
  updated_at: 2026-04-12T14:32:11Z
---

If a test reveals incorrect behavior, fix the production code. Do not relax assertions just to make
the suite green.

Storage Layout

Each scope has a MEMORY.md index next to its memory documents and a structurally-excluded _system/ namespace for machine-managed artifacts:

$AGH_HOME/memory/
  MEMORY.md
  user_review-style.md
  feedback_test-integrity.md
  _inbox/                        # extractor staging (operator-quiet)
  _system/
    dreaming/
    extractor/
    extractor/failures/
    ad_hoc/

<workspace>/.agh/memory/
  MEMORY.md
  project_runtime-docs.md
  reference_session-events.md
  _system/
    dreaming/
    ...

<workspace>/.agh/agents/<agent>/memory/
  MEMORY.md
  user_pedro-style.md
  _system/
    ...

_system/ is reserved. Curated indexing skips it, recall filters it out by default, and the controller rejects any write that would land directly in a top-level _system_*.md file. Operators can browse _system/ artifacts explicitly with --include-system on list/show/search/etc.

The Write Controller

Every write — CLI, HTTP, UDS, native tool, extractor, dreaming, file-watcher, provider — passes through the controller:

1. Caller submits a Candidate { workspace_id, scope, agent, agent_tier, origin, frontmatter, content, ... }.
2. The controller computes a deterministic decision with rule-first lexical+entity-slot logic; an LLM tiebreaker runs only when the rule trace falls in the configured ambiguity band.
3. The decision is persisted to memory_decisions (per-database WAL) before any file mutation, carrying full replay material: target_filename, frontmatter, post_content, post_content_hash, prior_content (for update/delete), idempotency_key, and the rule/LLM trace.
4. The file mutation lands atomically; the catalog reindexes the affected file; a canonical memory_events row is appended.
5. On crash, daemon boot replays unapplied decisions in decided_at order. Replay is idempotent by idempotency_key and post_content_hash.

There is exactly one write path. Controller-bypassing tools are forbidden; provider-supplied tools that collide with reserved names are rejected at registration with a memory.provider.collision event.

Frozen Snapshot And Recall

At session start, AGH captures a frozen snapshot of the resolved memory context (global, workspace, and the agent's two tiers when applicable). The snapshot includes:

• the per-scope MEMORY.md index after staleness banners
• a packaged recall block produced by the deterministic recall pipeline (FTS5 unicode + trigram, scope shadow, top-K) when a contextual query is available
• a freshness banner for entries whose age exceeds memory.recall.freshness.banner_after_days

The snapshot is captured once per session and does not mutate mid-session. Sub-agent sessions inherit the parent snapshot read-only. Manual writes during the session land in the WAL and on disk, but the running session keeps its captured prompt; the next session sees a fresh snapshot.

_system/ artifacts are never injected into the prompt by default. Recall skips ledger files, extractor inbox/DLQ artifacts, and dreaming output unless the caller explicitly opts in.

Operator And Agent Surfaces

Memory is reachable from CLI, HTTP, UDS, and native tools with parity. The Slice 1 verbs are:

Entry writes from agents still route through agh__memory_propose and agh__memory_note; both go through the controller. The operational tools live in the separate agh__memory_admin toolset and mirror the daemon CLI/API surfaces. There is no agh__memory_read, no agh__memory_history, no raw agh__memory_write, no raw agh__memory_edit, no raw agh__memory_delete, no agh memory read, and no agh memory consolidate in this slice — the renamed verbs above own the same intent.

CLI verbs accept -o json and -o jsonl for structured output. Errors are deterministic {code, message, details} payloads with stable codes such as memory.scope.invalid, memory.controller.timeout, and memory.provider.collision.

MEMORY.md Indexes

The per-scope MEMORY.md is the prompt-safe table of contents. AGH reads it inside the snapshot, caps it at [memory.file] max_lines = 200 and max_bytes = 25600, and includes the entries that fit. Useful index entries are short and point to one file:

- [Review Style](user_review-style.md) — User wants concise review findings with file references first.
- [Runtime Docs Location](project_runtime-docs.md) — Runtime docs live under `packages/site/content/runtime/`.

Observability

Every controller decision and recall outcome is observable.

memory_events rows have stable canonical op names (memory.write.committed, memory.write.rejected, memory.recall.executed, memory.dream.run.promoted, memory.extractor.completed, memory.provider.collision, etc.). They are queryable through the event store and feed agh memory health and the web Memory inspector.

Skipped empty extractor turns are recorded as memory.extractor.dropped with metadata.reason = "empty_snapshot" and redaction-safe counters only. Extractor completion events carry candidate_count, and controller write decisions remain under memory.write.*.

agh memory history returns the same audit material in the legacy summary shape as a thin compatibility view over memory_events. Use agh memory decisions list when you need controller-level detail.

Basic Usage

Write a global preference (operator-only):

agh memory write \
  --scope global \
  --type user \
  --name "Review Style" \
  --description "User wants concise review findings with file references first" \
  --content "Put blocking findings first. Cite file paths and symbols."

Write a workspace decision in the current workspace:

agh memory write \
  --scope workspace \
  --type project \
  --name "Runtime Docs Location" \
  --description "Runtime docs live in the Fumadocs runtime collection" \
  --content 'Runtime docs are authored under `packages/site/content/runtime/` and build to `/runtime/*`.'

Write to a specific agent tier:

agh memory write \
  --scope agent \
  --agent reviewer \
  --agent-tier global \
  --type feedback \
  --name "Reviewer Tone" \
  --description "Reviewer keeps findings short and actionable" \
  --content "Lead with the blocker. Cite file:line. Keep lists tight."

List and show:

agh memory list
agh memory show project_runtime-docs.md --scope workspace

Search recall:

agh memory search "review tone" --scope agent --agent reviewer --agent-tier global

Trigger a gated dreaming pass:

agh memory dream trigger

Related Pages

• Scopes explains scope selection, agent-tier rules, and shadowing.
• Dream explains gates, signals, and what dream trigger actually changes.
• Memory Best Practices gives concrete writing and hygiene guidance.
• Memory CLI Reference lists every generated memory command.