Memory System

AGH memory is persistent 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 small:

• memory is file-based, not stored in SQLite
• there are two scopes: global and workspace
• each scope has a MEMORY.md index
• only indexes are injected into startup prompts
• full memory files are read on demand with agh memory read

Runtime Flow

Memory is not streamed into an already-running process. When a session starts, AGH loads the global and workspace indexes, prepends them to the agent prompt, and hands that assembled prompt to the ACP subprocess. New memory written during the session becomes visible to the next session.

Four Memory Types

Every memory file has one of four types. The type also determines the default write scope when you do not pass --scope.

The taxonomy is closed. Unsupported types are rejected.

Memory File Format

Memory files are Markdown files with strict YAML frontmatter.

Required fields:

Example user memory:

---
name: Review Style
description: User wants concise review findings with file references first
type: user
---

When reviewing code, put blocking findings first and cite the file path and symbol. Keep summaries
short unless the user asks for deeper explanation.

Example feedback memory:

---
name: Test Integrity
description: Production bugs must be fixed instead of weakening tests
type: feedback
---

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

Example project memory:

---
name: Runtime Docs Location
description: Runtime documentation pages live in the Fumadocs runtime collection
type: project
agent_name: codex
---

AGH runtime docs are authored under `packages/site/content/runtime/` and build to `/runtime/*`.
Protocol pages live in a separate `/protocol/*` collection.

Example reference memory:

---
name: Session Events API
description: Stored session events are available through the stream endpoint
type: reference
---

Use `GET /api/sessions/:id/stream` for persisted SSE replay. Use `agh session events <id>` when
working from the CLI.

MEMORY.md Indexes

Each scope can include a MEMORY.md file next to the memory documents:

~/.agh/memory/
  MEMORY.md
  review-style.md
  test-integrity.md

<workspace>/.agh/memory/
  MEMORY.md
  runtime-docs-location.md
  session-events-api.md

The index is the prompt-safe table of contents. AGH reads it at session start and injects it into the prompt. A useful index entry is short and points to one file:

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

Index behavior:

Dream consolidation is the normal way to tighten memory files over time. Manual writes and deletes still keep the index synchronized so the next session can discover changed memories.

Operator Visibility

Memory has two operator-facing visibility surfaces:

The same typed data is available through GET /api/memory/health and GET /api/memory/history. History output is intentionally bounded and redacted before it is returned to CLI or API clients.

These visibility surfaces do not change prompt assembly. Runtime prompts still receive only the startup memory index snapshot described above; future context-reference and provider-hook support will be integrated by a separate runtime task.

Prompt Injection

When memory is enabled, AGH prepends a # Persistent Memory section to the startup prompt. That section can include:

1. Global MEMORY.md index
2. Workspace MEMORY.md index
3. The four-type taxonomy
4. A short command guide for agh memory list, agh memory read, and agh memory write
5. A staleness warning policy

This memory block is assembled before the agent's AGENT.md body. The skills catalog is appended after the base prompt when skills are enabled, so memory gives the agent durable context before it starts applying reusable skills.

Basic Workflow

Write a global preference:

agh memory write review-style.md \
  --type user \
  --description "User wants concise review findings with file references first" \
  --content "Put blocking findings first. Cite file paths and symbols."

Write a workspace decision:

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

List memories:

agh memory list

Read the full file when an index entry looks relevant:

agh memory read runtime-docs-location.md --scope workspace

Related Pages

• Scopes explains global and workspace storage rules.
• Dream Consolidation explains automatic cleanup and index tightening.
• Memory Best Practices gives concrete writing and hygiene guidance.
• Memory CLI Reference lists every generated memory command.