Skip to content

Memory Storage

Jump to bottom
Eugene Naumov edited this page May 13, 2026 · 3 revisions

Memory Storage

Agents accumulate knowledge across sessions using one of three storage options, chosen during agent-notes install.

Note: The Obsidian and Wiki storage modes store notes as markdown files in an Obsidian vault. You need to download and install Obsidian to browse notes visually with graph view, backlinks, and search. The files are plain markdown, so the CLI works without Obsidian installed — but you lose the visual browsing experience.

Comparison

Feature Local Obsidian Wiki
Location ~/.claude/agent-memory/ Obsidian vault Obsidian vault
Project scoping No Yes (per CWD) Yes (per CWD)
Organization Per-agent folders Categories (Patterns, Decisions, etc.) Wiki pages (sources, concepts, entities)
Wikilinks No Yes Yes
Session tracking No Yes (auto-linking) Yes
Ingest No Via /ingest skill CLI + /ingest skill
Query/Lint No No Yes
Best for Simple setup Process memory, visual browsing Domain knowledge, team knowledge bases

Local (default)

Plain markdown storage in ~/.claude/agent-memory/. One folder per agent, no project scoping or cross-referencing. Simplest setup, no external tools needed.

Structure

~/.claude/agent-memory/
├── Index.md
├── lead/
│   └── *.md
├── coder/
│   └── *.md
└── reviewer/
    └── *.md

Commands

agent-notes memory list              # list all notes by agent
agent-notes memory show <agent>      # show one agent's notes
agent-notes memory size              # disk usage
agent-notes memory reset [agent]     # clear memory (confirmation required)
agent-notes memory export            # back up to memory-backup/
agent-notes memory import            # restore from memory-backup/

Obsidian (per-project sessions)

Category vault with YAML frontmatter and [[wikilinks]]. Auto-creates a folder per project (derived from current working directory name) and organizes notes into categories.

Structure

<vault-root>/
├── my-project/              # auto-created from CWD name
│   ├── Patterns/            # reusable solutions
│   ├── Decisions/           # architectural choices with rationale
│   ├── Mistakes/            # recurring errors to avoid
│   ├── Context/             # project background, constraints
│   ├── Sessions/            # per-session running logs
│   └── Index.md             # auto-generated chronological catalog
└── another-project/
    └── ...

Note types

Type Category Description
pattern Patterns/ Reusable solution or technique
decision Decisions/ Architectural choice with rationale
mistake Mistakes/ Recurring error to avoid
context Context/ Project background, stakeholder notes
session Sessions/ Current session's running log (appends)

Note format

---
created_at: 2026-05-11T14:30:00Z
type: pattern
agent: coder
project: my-project
session: 2026-05-11_abc123
tags: [rails, models]
---

# Note Title

Content here.

## Related

Key features

  • Auto-linking: When a non-session note is written during an active session, the CLI auto-appends a wikilink to the session note
  • Plan mirroring: Plans created during a session are mirrored as Decision notes
  • Session append: Repeated memory add ... session calls append ## Update blocks to the same session file
  • Index regeneration: memory index rebuilds Index.md sorted chronologically (newest first)
  • Visual browsing: Works with Obsidian's graph view, backlinks, and Dataview queries

Commands

agent-notes memory init                          # create folder structure
agent-notes memory add <title> <body> [type] [agent]  # add a note
agent-notes memory list                          # list all notes
agent-notes memory vault                         # show storage path and status
agent-notes memory index                         # regenerate Index.md
agent-notes memory show <agent>                  # show one agent's notes
agent-notes memory reset [agent]                 # clear memory
agent-notes memory export                        # back up
agent-notes memory import                        # restore

Ingest via /ingest skill

The /ingest skill works in Obsidian mode. It scans a source (file, folder, or URL), analyzes content with AI, and creates notes:

  1. Scan source
  2. AI extracts title, summary, concepts, entities, tags
  3. Creates main context note + fan-out notes to Patterns/, Context/, Decisions/ as appropriate
  4. No raw archiving — the AI summary IS the stored knowledge
  5. No wiki-compiler step — notes are complete on creation

Use in a Claude Code session:

/ingest

Wiki (per-project knowledge brain)

Implements Karpathy's LLM Wiki pattern. Auto-creates a folder per project with immutable source material and LLM-maintained wiki pages. See Inspirations for background.

Structure

<vault-root>/
├── my-project/              # auto-created from CWD name
│   ├── raw/                 # immutable source material (chunked)
│   └── wiki/
│       ├── sources/         # ingested source pages
│       ├── concepts/        # domain concepts
│       ├── entities/        # external tools/services
│       ├── synthesis/       # cross-cutting themes
│       ├── sessions/        # session logs
│       ├── index.md         # auto-generated catalog
│       └── log.md           # append-only operation log
└── another-project/
    └── ...

Three operations

Ingest: Drop a source (URL, file, folder). The LLM reads it, extracts concepts and entities, creates wiki pages with cross-references. Fan-out creates linked pages automatically.

CLI command (Wiki mode only):

agent-notes memory ingest "<title>" "<summary>" "<concepts_csv>" "<entities_csv>" "<tags_csv>"
agent-notes memory ingest    # no args: scan raw/ for unprocessed files

Pipeline:

  1. Scan source (file, folder, or URL)
  2. AI analysis — extract title, summary, concepts, entities, tags
  3. agent-notes memory ingest — archives raw content to raw/, creates source page, fans out concept/entity stubs
  4. wiki-compiler agent compiles each stub into a rich page
  5. Cross-reference index rebuilt

Query: Search wiki pages by keyword. Valuable answers can be filed back as new pages.

agent-notes memory query "<keyword>"

Lint: Health check for broken links, orphan pages, stub pages needing compilation, missing cross-references.

agent-notes memory lint

Wiki-compiler agent

For rich page compilation, the wiki-compiler agent reads raw source material and writes Wikipedia-style entity/concept pages. It follows the Karpathy compile operation:

  1. Discover — grep raw chunks for concept name and variants
  2. Read — read most relevant files (model, service, controller, job, spec)
  3. Compile — write rich page with domain logic, data models, relationships
  4. Write — persist via CLI with confidence level
  5. Report — list compiled pages and findings

Pages include confidence levels:

  • High — multiple code files found, data model and logic confirmed
  • Medium — some code found, partial understanding
  • Low — inferred from naming only, do not write the page

Commands

agent-notes memory add <title> <body> [type] [agent]  # write a wiki page
agent-notes memory ingest [args...]                    # ingest source material
agent-notes memory query <keyword>                     # search wiki
agent-notes memory lint                                # health check
agent-notes memory vault                               # show storage path
agent-notes memory list                                # list all pages

Project Scoping

Both Obsidian and Wiki modes auto-create a folder named after the current working directory under the vault root.

  • Config stores only the vault root path
  • Project folder resolved at runtime via Path.cwd().name
  • Different projects get completely isolated storage
  • No cross-project contamination

Example

Working in ~/code/my-app/:

<vault>/my-app/Patterns/...     (obsidian)
<vault>/my-app/wiki/sources/... (wiki)

Working in ~/code/other-project/:

<vault>/other-project/Patterns/...     (obsidian)
<vault>/other-project/wiki/sources/... (wiki)

Switching storage

agent-notes install --reconfigure    # re-run wizard to change storage mode

Inspirations

See Inspirations for detailed credits:

  • Karpathy's LLM Wiki — the three-layer architecture and ingest/query/lint operations
  • Matt Pocock's Skills — per-project session scoping and skill-based workflows

Clone this wiki locally