Memory Scopes

AGH memory has three scopes:

• global — user-wide context available across workspaces.
• workspace — project context bound to a specific workspace ID.
• agent — per-agent context, with two tiers:
  • agent-workspace — workspace-private agent state.
  • agent-global — cross-workspace agent baseline.

The runtime composes a frozen snapshot from these scopes at session start. Read precedence is:

agent-workspace ▸ agent-global ▸ workspace ▸ global

A deeper scope shadows a shallower scope when both contain the same identity (type, slug). Shadowed entries are never silently merged. The packaged recall block lists scope blocks least-specific first so agents see global context, then workspace, then agent baseline, then agent-workspace overrides.

File Locations

Typical layout:

~/.agh/memory/
  MEMORY.md
  user_review-style.md
  feedback_test-integrity.md
  _system/
  _inbox/

~/.agh/agents/reviewer/memory/
  MEMORY.md
  user_pedro-style.md
  _system/

/repo/agh/.agh/memory/
  MEMORY.md
  project_runtime-docs.md
  reference_session-events.md
  _system/

/repo/agh/.agh/agents/reviewer/memory/
  MEMORY.md
  project_repo-rules.md
  _system/

workspace_id is derived from <workspace>/.agh/workspace.toml; the same ULID survives mv of the workspace directory. Memory keying never uses workspace_root paths. See Workspace Resolver.

Choosing A Scope

Examples:

Default Write Posture

The default write posture is conservative.

• CLI / HTTP / UDS operator writes. When --scope is omitted, the controller falls back to a type-driven default for global/workspace scopes: user and feedback → global, project and reference → workspace. Agent scope is never the default — --scope agent must be explicit and requires --agent <name> plus a validated --agent-tier {workspace, global}. The agent tier defaults to workspace when omitted.
• Cross-workspace promotion. Agent-global writes are explicit. Operators run agh memory promote --to agent-global <filename> (or use the controller-backed equivalent over HTTP/UDS) when a workspace-tier entry should travel with the agent.

agh memory write \
  --scope global \
  --type user \
  --name "Review Style" \
  --description "User wants concise review findings" \
  --content "Put blocking findings first."

agh memory write \
  --scope workspace \
  --type project \
  --name "Docs Package" \
  --description "Docs package is @agh/site" \
  --content 'Use `bunx turbo run build --filter=@agh/site` for the site build.'

agh memory write \
  --scope agent \
  --agent reviewer \
  --agent-tier workspace \
  --type feedback \
  --name "Repo Reviewer Rules" \
  --description "This repo wants release-risk notes in reviews" \
  --content "For this repo, include release risk when reviewing bridge or automation changes."

Sessions without an active workspace cannot write --scope workspace or --scope agent --agent-tier workspace. The controller rejects those calls with memory.scope.workspace_required instead of silently routing them to global.

Show, Edit, And Delete Resolution

show, edit, and delete commands accept an explicit selector or resolve a filename within the current snapshot when it is unambiguous.

Use explicit selectors for repeatable automation:

agh memory show user_review-style.md --scope global
agh memory delete project_docs-package.md --scope workspace
agh memory show user_pedro-style.md --scope agent --agent reviewer --agent-tier global

API Selectors

HTTP and UDS routes use the same selector shape (scope, workspace_id, agent_name, agent_tier) and the same controller path:

Example workspace write:

curl -X POST http://localhost:2123/api/memory \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "workspace",
    "workspace_id": "01HXJ9YR4QABCDEFGHJK0123456",
    "type": "project",
    "name": "Docs Package",
    "description": "Docs package is @agh/site",
    "content": "Use `bunx turbo run build --filter=@agh/site` for the site build."
  }'

Public selectors use workspace_id and agent_name. There is no path-style workspace field on the wire and no PUT /api/memory/{filename} route.

Shadow-By-Id

Shadowing is structural, not heuristic:

1. The controller computes an entry's identity as (type, slug).
2. When a deeper scope writes the same identity, the shallower entry stays on disk but is not surfaced to the next snapshot or recall packaging until the shadowing entry is removed.
3. memory.write.shadowed events record the winner and loser scopes for forensic browsing.

Shadow events are observable through agh memory decisions list and the events feed.

Related Pages

• Memory System explains the controller WAL, frozen snapshot, and operator surfaces.
• Dream explains gated dreaming runs and signal-based promotion.
• Workspace Resolver explains how workspace_id is derived.
• Agent Definitions documents agent memory binding.