Memory Manager
Use explicit, user-owned artifacts for durable memory. Model memory can help when available, but files and connected knowledge bases are easier to inspect, version, share, and correct.
Storage Priority
- Repo-specific rules ->
AGENTS.md
- Project facts and recurring context ->
MEMORY.md or docs/MEMORY.md
- Decisions and rationale ->
DECISIONS.md or docs/decisions/*.md
- Long implementation plans ->
PLANS.md or issue/task tracker
- Private team knowledge -> Notion, GitHub wiki, or another connected MCP source
- Personal cross-repo defaults ->
~/.codex/AGENTS.md
Read references/storage-targets.md when choosing between these locations.
What To Capture
Capture durable facts that will help future sessions:
- repo layout and important directories
- build, test, lint, deploy, and run commands
- architecture decisions and tradeoffs
- project-specific style and naming conventions
- recurring pitfalls, flaky commands, or setup gotchas
- external systems, dashboards, docs, and issue trackers
- user preferences that are stable and relevant to coding
Do not capture secrets, tokens, passwords, private keys, credentials, or one-off chatter.
Capture Workflow
- Identify the memory type: rule, fact, decision, plan, or lesson.
- Check whether an existing artifact should be updated.
- Write concise entries with date, source, and confidence when useful.
- Prefer bullets and command snippets over prose essays.
- Link to files, PRs, issues, or docs instead of duplicating large content.
- Ask before writing personal or sensitive preferences.
Retrieval Workflow
Before using memory:
- Read the closest repo
AGENTS.md first.
- Search for
MEMORY.md, DECISIONS.md, PLANS.md, and relevant docs.
- Prefer current repo files over older remembered context.
- Treat memory as guidance, not proof of current external facts.
If memory conflicts with the user prompt, follow the prompt and mention the conflict if it matters.
Entry Templates
Project fact:
- YYYY-MM-DD: Fact. Source: file/path or user note. Confidence: high|medium|low.
Decision:
## YYYY-MM-DD - Decision title
Decision: ...
Rationale: ...
Alternatives considered: ...
Applies to: ...
Revisit when: ...
Lesson:
- Symptom: ...
Cause: ...
Fix or workaround: ...
Verification: ...
1---2name: memory-manager3description: Capture, update, and retrieve durable project memory for coding work. Use when the user asks to remember project facts, preserve decisions, create reusable context, manage memory across accounts or machines, maintain MEMORY.md/DECISIONS.md/AGENTS.md, or summarize lessons from a completed task for future Codex sessions.4---56# Memory Manager78Use explicit, user-owned artifacts for durable memory. Model memory can help when available, but files and connected knowledge bases are easier to inspect, version, share, and correct.910## Storage Priority11121. Repo-specific rules -> `AGENTS.md`132. Project facts and recurring context -> `MEMORY.md` or `docs/MEMORY.md`143. Decisions and rationale -> `DECISIONS.md` or `docs/decisions/*.md`154. Long implementation plans -> `PLANS.md` or issue/task tracker165. Private team knowledge -> Notion, GitHub wiki, or another connected MCP source176. Personal cross-repo defaults -> `~/.codex/AGENTS.md`1819Read `references/storage-targets.md` when choosing between these locations.2021## What To Capture2223Capture durable facts that will help future sessions:2425- repo layout and important directories26- build, test, lint, deploy, and run commands27- architecture decisions and tradeoffs28- project-specific style and naming conventions29- recurring pitfalls, flaky commands, or setup gotchas30- external systems, dashboards, docs, and issue trackers31- user preferences that are stable and relevant to coding3233Do not capture secrets, tokens, passwords, private keys, credentials, or one-off chatter.3435## Capture Workflow36371. Identify the memory type: rule, fact, decision, plan, or lesson.382. Check whether an existing artifact should be updated.393. Write concise entries with date, source, and confidence when useful.404. Prefer bullets and command snippets over prose essays.415. Link to files, PRs, issues, or docs instead of duplicating large content.426. Ask before writing personal or sensitive preferences.4344## Retrieval Workflow4546Before using memory:4748- Read the closest repo `AGENTS.md` first.49- Search for `MEMORY.md`, `DECISIONS.md`, `PLANS.md`, and relevant docs.50- Prefer current repo files over older remembered context.51- Treat memory as guidance, not proof of current external facts.5253If memory conflicts with the user prompt, follow the prompt and mention the conflict if it matters.5455## Entry Templates5657Project fact:5859```markdown60- YYYY-MM-DD: Fact. Source: file/path or user note. Confidence: high|medium|low.61```6263Decision:6465```markdown66## YYYY-MM-DD - Decision title6768Decision: ...69Rationale: ...70Alternatives considered: ...71Applies to: ...72Revisit when: ...73```7475Lesson:7677```markdown78- Symptom: ...79 Cause: ...80 Fix or workaround: ...81 Verification: ...82```
panxy1019