Memory Setup

---
name: memory-setup
description: Persistent project memory setup and the context-routing stack for this project — what lives in .claude/memory/ vs Beads vs graphify vs cocoindex-code vs context7, when to write a memory file, learning intensity, Ollama/router wiring, and shared team preferences. Invoke when deciding whether/what to save to memory, when context-routing is unclear (which source to hit first), when Ollama/claude-code-router or team-prefs come up, or on explicit request — "memory setup", "what should I remember", "context stack", "team preferences".
---

# Memory & context stack (optional feature)

Persistent project memory is **toggled by `AIFLOW_MEMORY` at the top of `AGENTS.md`** (set by
`aiflow init` / `aiflow change-settings`, config key `memory.enabled`).
- `off`: no memory dir is used; rely on Beads + `AGENTS.md`.
- `on`: store durable facts in `.claude/memory/` with an index in `.claude/MEMORY.md`
  **(Claude Code only path** — Copilot/Codex have no equivalent persistent-memory feature today;
  read these files as plain markdown for the same context if your tool can browse the repo**)**.
  `aiflow` seeds two files: `project-aim.md` (goal + target architecture) and
  `dev-environment.md` (OS, IDE, VCS host — so the agent picks correct commands).

When **on**: save only non-obvious, durable facts (decisions, gotchas, env quirks) —
never things already in code, git history, or Beads.

**Learning intensity** is set in `.aiflow/config.json → memory.intensity` and written to
`.claude/memory/memory-policy.md` (read it — it is the live, generated, authoritative version of
this section's routing table): `aggressive` (default — learn after every non-trivial task +
refresh the graph), `normal`, `light`, or `off`.

## Context stack — route the question, don't scan files

`.claude/memory/memory-policy.md` holds the full, live routing table (regenerated by
`aiflow apply`/`aiflow change-settings`); the summary below is the static fallback.

| Need | Use | Why |
|------|-----|-----|
| Current task, deps, decisions, session state | **Beads** (`bd`) | structured work memory, survives compaction |
| Durable project facts / gotchas / env quirks | **memory files** (`.claude/memory/`) | prose facts not in code/git |
| Where a symbol is defined, who calls it, dependency direction | **graphify** MCP | exact structural graph, no re-scan |
| "Find code about concept X" / semantic / fuzzy | **cocoindex-code** (`ccc search` / MCP) | AST-aware RAG, ~70% fewer tokens than reading files |
| External library / framework API docs | **context7** MCP | live upstream docs, avoids hallucination |
| Anything still unresolved | read the file(s) | only after graph + RAG have narrowed the target |

MCP servers are wired per agent (`.mcp.json` for Claude Code, `.codex/config.toml` for Codex CLI,
`.vscode/mcp.json` for Copilot in VS Code) from the same `.aiflow/config.json` — any agent that
supports MCP gets the same graphify/cocoindex-code/context7 access.

**Rule:** never scan whole files first. Route the question through graphify (structure) and
cocoindex-code (semantics) to locate the few relevant chunks, then open only those files. Refresh
**both** indexes after significant changes with a single command: `aiflow index` (runs
`graphify build` + `ccc index`, incremental).

## Shared team preferences

If `.aiflow/team-prefs.json` exists it holds versioned, team/user-wide preferences (code style,
language, conventions) that override the per-language defaults in `AGENTS.md` §3. It is committed
so the whole team inherits it; personal tweaks stay local.

## Local models (Ollama)

When `.aiflow/config.json → ollama` is enabled, its models are wired into
`.aiflow/router-config.json`; run easy/background steps on them via `aiflow shell --router`
**(Claude Code only** — launches Claude Code via claude-code-router; Copilot/Codex route models
through their own settings**)**. Manage models with `aiflow ollama`.