Global vs Workspace Memory

AGH memory has two implemented scopes:

global: user-wide context available across workspaces
workspace: project context available when a session starts in that workspace

The scopes are loaded together at session start. Global memory appears first, then workspace memory. Use global memory for stable user-level patterns. Use workspace memory for facts that would be wrong or noisy in another repository.

File Locations

Scope	Default location	Override
global	`~/.agh/memory/`	Set `$AGH_HOME`, or set `[memory].global_dir` in config.
workspace	`<workspace>/.agh/memory/`	Derived from the resolved workspace root.

If $AGH_HOME is set, the global memory directory is $AGH_HOME/memory/.

Typical layout:

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

/repo/agh/
  .agh/
    memory/
      MEMORY.md
      runtime-docs-location.md
      session-events-api.md

Choosing A Scope

Question	Store globally	Store in the workspace
Would this still help in a different repository?	yes	no
Is this about the user's working style?	yes	no
Is this a repeated correction across tasks?	yes	sometimes
Is this about architecture, file paths, commands, or conventions in one repo?	no	yes
Would another project be misled by this fact?	no	yes

Examples:

Memory	Type	Scope
"User prefers terse status updates while commands run."	`user`	global
"Never weaken a failing test to preserve a broken implementation."	`feedback`	global
"The docs site package is named `@agh/site`."	`project`	workspace
"The AGH API stream endpoint is `GET /api/sessions/:id/stream`."	`reference`	workspace

Default Scope Rules

When a write request omits scope, AGH infers scope from the memory type:

Type	Default scope
`user`	global
`feedback`	global
`project`	workspace
`reference`	workspace

That inference happens in both CLI and API writes. Workspace writes need a workspace root. The CLI uses the current working directory for workspace memory. The API uses the request workspace field.

agh memory write review-style.md \
  --type user \
  --description "User wants concise review findings" \
  --content "Put blocking findings first."

The command above writes to global memory because user defaults to global.

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

The command above writes to workspace memory because project defaults to workspace.

Pass --scope when you need to override the type default:

agh memory write team-review-style.md \
  --type feedback \
  --scope workspace \
  --description "This repository wants release-risk notes in reviews" \
  --content "For this repo, include release risk when reviewing bridge or automation changes."

Read And Delete Resolution

Read and delete commands can resolve a memory file without --scope, but only when the filename is unambiguous.

Case	Behavior
File exists only globally	AGH uses global scope.
File exists only in the current workspace	AGH uses workspace scope.
File exists in both scopes	AGH returns an ambiguity error and asks for `--scope`.
File exists nowhere	AGH returns not found.

Use explicit scope for repeatable automation:

agh memory read review-style.md --scope global

agh memory delete docs-package.md --scope workspace

API Scope Rules

The HTTP and UDS routes use the same store and validation rules:

Operation	Route	Scope behavior
List	`GET /api/memory`	Lists global memory by default. Include `workspace` to include workspace memory, or pass `scope`.
Read	`GET /api/memory/:filename`	Searches global, and also workspace when the `workspace` query is provided.
Write	`PUT /api/memory/:filename`	Infers scope from frontmatter type unless `scope` is supplied. Workspace scope requires `workspace`.
Delete	`DELETE /api/memory/:filename`	Uses explicit scope or resolves by filename like read.
Consolidate	`POST /api/memory/consolidate`	Optionally accepts `workspace` to target one workspace.

Example API write to workspace memory:

curl -X PUT http://localhost:2123/api/memory/docs-package.md \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "workspace",
    "workspace": "/absolute/path/to/repo",
    "content": "---\nname: Docs Package\ndescription: Docs package is @agh/site\ntype: project\n---\n\nUse `bunx turbo run build --filter=@agh/site` for the site build."
  }'

Configuration

Memory is enabled by default. The global directory defaults to the resolved AGH home memory directory.

[memory]
enabled = true
global_dir = "/Users/you/.agh/memory"

[memory.dream]
enabled = true
agent = "general"
min_hours = 24
min_sessions = 3
check_interval = "30m"

Set memory.enabled = false to disable memory prompt injection, memory store initialization, and dream runtime wiring.

Set memory.dream.enabled = false to keep manual memory files and prompt injection while disabling automatic dream consolidation.

Memory System explains the file format and prompt injection.
Dream Consolidation explains automatic and manual consolidation.
Agent Definitions documents current AGENT.md parser limits.