Skip to content

How To

Jump to bottom
Eugene Naumov edited this page May 11, 2026 · 1 revision

How To

Practical guide to using agent-notes with each memory mode. Covers the Karpathy wiki methodology, Pocock's session-oriented skills, and the lead + agent team model.

Choosing Your Memory Mode

If you want to... Use Why
Get started fast, no setup Local Plain files, no external tools
Track decisions, mistakes, patterns across sessions Obsidian Process memory with visual browsing
Build a compounding knowledge base from source material Wiki Domain knowledge that grows smarter over time
Track process AND build domain knowledge Obsidian + Wiki Both folders exist per project under separate roots

Local Memory

The simplest mode. Notes stored in ~/.claude/agent-memory/, one folder per agent. No project scoping, no cross-referencing.

When to use

  • Solo developer, single project
  • Don't want to install Obsidian
  • Just need the lead to remember things between sessions

How it works in practice

You: "Fix the N+1 query in the orders endpoint"

Lead discovers a non-obvious constraint during the fix:
  agent-notes memory add "Orders eager loading" \
    "orders.includes must include :line_items AND :shipping_address — 
     the PDF generator reads both in a single pass" \
    pattern coder

Next session, the lead reads this before touching orders again.

That's it. No sessions, no linking, no wiki. Simple key-value memory.

Obsidian Memory — Process Memory (Pocock Model)

Inspired by Matt Pocock's Skills. Treats each coding session as a discrete unit with its own context, decisions, and outcomes. Notes are organized by category and cross-linked with [[wikilinks]].

The mental model

Think of Obsidian memory as your team's engineering journal:

  • Sessions/ — what happened today, what was decided, what shipped
  • Decisions/ — why we chose X over Y (with rationale that survives memory loss)
  • Patterns/ — reusable solutions discovered in this codebase
  • Mistakes/ — errors to avoid (saves future sessions from repeating them)
  • Context/ — project background, constraints, stakeholder notes

Setting up

agent-notes install          # choose "obsidian" when asked about memory
agent-notes memory init      # creates folder structure in vault
agent-notes memory vault     # confirm path

Open the vault folder in Obsidian for graph view and backlinks.

Session lifecycle

1. Session starts — lead creates a session note

agent-notes memory add "Implement rate limiting" \
  "Scope: add rate limiting middleware to all API endpoints. 
   Acceptance: per-IP limits, configurable thresholds, 429 responses." \
  session lead

This creates Sessions/2026-05-12_<session-id>.md. All subsequent session calls in this session append to the same file.

2. Work happens — lead updates at every state change

# After explorer returns
agent-notes memory add "Implement rate limiting" \
  "Phase 1 — Discovery complete. Found existing middleware in src/middleware/. 
   No rate limiting yet. Tests use supertest. 12 API routes." \
  session lead

# After coder finishes
agent-notes memory add "Implement rate limiting" \
  "Phase 2 — Implementation done. Added src/middleware/rate-limit.ts, 
   wired into app.ts. Config in env vars. 3 files touched." \
  session lead

# After review + tests pass
agent-notes memory add "Implement rate limiting" \
  "Phase 4 — Verification complete. All tests pass. Reviewer approved. 
   Shipped: rate limiting on all routes, 100 req/min default." \
  session lead

3. Discoveries are saved as standalone notes

When the lead or an agent discovers something non-obvious during work:

# A decision with tradeoffs
agent-notes memory add "Rate limiting: per-IP not per-user" \
  "Chose per-IP over per-user because auth middleware runs after rate limiting. 
   Moving rate limiting after auth would expose all routes to unauthenticated floods. 
   Tradeoff: shared IPs (corporate NAT) may hit limits unfairly." \
  decision lead

# A pattern discovered in the codebase
agent-notes memory add "Middleware registration order" \
  "Middleware in this project must be registered in app.ts in exact order: 
   cors → rate-limit → auth → routes → error-handler. 
   The error handler catches thrown 429s from rate-limit." \
  pattern coder

# A mistake to avoid
agent-notes memory add "Don't mock Redis in rate limit tests" \
  "Rate limit tests must use a real Redis instance (docker-compose test service). 
   Mocked Redis passed all tests but missed a TTL bug in production." \
  mistake test-writer

4. Auto-linking ties it together

When a standalone note (Decision, Pattern, Mistake) is written during an active session, the CLI automatically appends a wikilink to the session note's ## Linked notes section. No extra work needed.

The session note becomes a navigable hub:

## Linked notes
- [[2026-05-12_rate-limiting-per-ip-not-per-user]] — decision — Rate limiting: per-IP not per-user
- [[2026-05-12_middleware-registration-order]] — pattern — Middleware registration order
- [[2026-05-12_dont-mock-redis-in-rate-limit-tests]] — mistake — Don't mock Redis in rate limit tests

Using Obsidian for visual navigation

Open the vault in Obsidian to see:

  • Graph view — how sessions, decisions, and patterns connect
  • Backlinks — which sessions referenced a particular decision
  • Search — full-text search across all notes
  • Dataview — query notes by type, date, agent, tags

Skills that enhance Obsidian memory

Skill How it helps
/obsidian-memory Save/retrieve notes using the correct format
/grill-me Stress-test a plan before saving it as a Decision
/brainstorming Compare approaches, save winner as a Decision
/debugging-protocol Systematic debugging, save root cause as a Pattern or Mistake
/code-review Review findings often surface Patterns

Wiki Memory — Domain Knowledge (Karpathy Model)

Implements Karpathy's LLM Wiki pattern. Instead of re-deriving knowledge from scratch every session, build a compounding wiki that accumulates synthesis over time.

The mental model

Think of Wiki memory as a team knowledge base that gets smarter with every session:

Raw sources (immutable)  →  Wiki pages (LLM-maintained)  →  Queries (answers with citations)
       ↑                          ↑                              |
   you add these          agents compile these            valuable answers filed back

The wiki is a persistent, compounding artifact. You source material and ask questions. The agents do the grunt work — summarizing, cross-referencing, filing, and bookkeeping.

Setting up

agent-notes install          # choose "wiki" when asked about memory
agent-notes memory init      # creates raw/ and wiki/ structure
agent-notes memory vault     # confirm path

Three operations

1. Ingest — Feed source material into the wiki

Drop a URL, file, or folder. The lead analyzes the content, extracts concepts and entities, and creates cross-referenced wiki pages.

Ingest a URL:

You: /ingest https://docs.stripe.com/webhooks

Lead:
  1. Fetches the page
  2. Extracts: title, summary, concepts (webhook verification, event types, retry logic), 
     entities (Stripe, webhook endpoint), tags (payments, api)
  3. Runs: agent-notes memory ingest "Stripe Webhooks" "<summary>" "webhook verification,..." "Stripe" "payments,api"
  4. Reports: created source page + 3 concept pages + 1 entity page

Ingest a codebase folder:

You: /ingest ./app/models/

Lead:
  1. Lists files, reads key models
  2. Extracts concepts (polymorphic associations, soft deletes, state machines), 
     entities (User, Order, Payment), relationships
  3. Ingests via CLI — creates pages for each concept and entity
  4. Pages cross-reference each other with [[wikilinks]]

Ingest unprocessed raw files (no-args mode):

You: /ingest

Lead:
  1. Runs: agent-notes memory ingest (no args) — scans raw/ for unprocessed files
  2. Groups related concepts by domain
  3. Dispatches wiki-compiler agent per batch
  4. wiki-compiler reads raw chunks, writes rich Wikipedia-style pages

2. Query — Ask the wiki questions

Search wiki pages by keyword. The lead synthesizes answers from existing pages. Valuable answers get filed back as new synthesis pages, compounding the knowledge.

You: "How does payment processing work in this project?"

Lead:
  1. Runs: agent-notes memory query "payment"
  2. Reads matching pages: [[Payment]], [[ACH Processing]], [[Wire Approvals]]
  3. Synthesizes: "Payment processing follows a three-stage pipeline: 
     initiation (ACH or wire), approval workflow, and reconciliation..."
  4. If the synthesis is valuable, saves it as a new page:
     agent-notes memory add "Payment Processing Overview" "<synthesis>" synthesis wiki-compiler

3. Lint — Health check the wiki

Detects structural issues: broken links, orphan pages, stubs needing compilation, missing cross-references.

agent-notes memory lint

Output example:

Broken links: [[NonExistent]] in concepts/payment.md
Orphan pages: entities/legacy-gateway.md (no incoming links)
Stub pages: concepts/reconciliation.md (needs compilation)
Missing concepts: "escrow" mentioned 4 times but has no page

The wiki-compiler agent

For rich page compilation, the wiki-compiler agent reads raw source material and writes Wikipedia-style pages following Karpathy's compile operation:

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

Confidence levels:

  • High — multiple code files found, data model and logic confirmed
  • Medium — some code found, partial understanding
  • Low — inferred from naming only, flagged for review

How knowledge compounds

Session 1: Ingest the codebase → 50 concept pages, 30 entity pages (many stubs)

Session 2: Compile stubs → wiki-compiler reads code, writes rich pages with domain logic

Session 3: Query "how does X work?" → lead synthesizes from existing pages, files answer back

Session 4: Ingest new feature code → new pages link to existing concepts, graph grows

Session 10: New team member asks "how does the whole system work?" → wiki has the answer, with citations back to source code

Each session adds knowledge that future sessions build on. The wiki never starts from scratch.

Using Both: Obsidian + Wiki

For projects that need both process memory and domain knowledge, use both modes with separate vault roots:

  • Obsidian (notes/) — sessions, decisions, patterns, mistakes
  • Wiki (knowledge/) — source pages, concepts, entities, synthesis

Both are per-project scoped. The lead uses Obsidian memory for session tracking and the wiki for domain knowledge:

Start of session:
  → Read wiki pages for domain context (how does X work?)
  → Read recent Obsidian sessions for process context (what did we try last time?)

During work:
  → Save decisions/patterns/mistakes to Obsidian
  → Ingest new source material to wiki

End of session:
  → Update session note in Obsidian with outcomes
  → Lint wiki for broken links or stubs

The Lead + Agent Team Model

The lead orchestrates. Agents execute. This is how the pieces fit together with memory.

Before starting work

The lead reads memory to understand context:

1. Read wiki index — what domain knowledge exists?
2. Read recent session notes — what was done recently? What's in progress?
3. Read decisions — any constraints or past choices that affect this task?
4. Read mistakes — anything to avoid?

During work

Lead: "We need to refactor the payment module"

  → explorer reads wiki pages for [[Payment]], [[ACH Processing]], [[Reconciliation]]
     (cheaper than re-reading all the source files)
  
  → architect proposes new module boundaries based on wiki domain knowledge
  
  → coder implements the refactor
  
  → reviewer checks against patterns saved in Obsidian memory
  
  → lead saves the refactoring decision:
    agent-notes memory add "Payment module split" \
      "Split monolithic Payment model into PaymentInitiation, PaymentApproval, 
       and PaymentReconciliation. Reason: SRP violation causing test coupling." \
      decision lead

After work

Lead updates session note with outcomes:
  agent-notes memory add "Refactor payment module" \
    "Done. Split into 3 models, 12 files changed, all tests pass. 
     Deferred: PaymentReconciliation still has N+1 — tracked as follow-up." \
    session lead

How agents use memory

Agent Reads Writes
lead Sessions, Decisions, wiki pages Session notes, Decisions
coder Patterns (for conventions) Patterns (when discovering new ones)
reviewer Patterns, Mistakes — (read-only)
wiki-compiler Raw sources, existing wiki pages Wiki concept/entity pages
debugger Mistakes (known failure modes) — (read-only, hands fix to coder)
explorer Wiki index (for context) — (read-only)

Recipes

Recipe: Onboard to an unfamiliar codebase

1. Ingest the codebase:
   /ingest ./app/

2. Compile the stubs:
   /ingest  (no args — triggers wiki-compiler)

3. Browse the wiki in Obsidian — graph view shows how concepts connect

4. Ask questions:
   "How does authentication work?"
   "What's the relationship between Orders and Payments?"
   
   → Lead answers from wiki pages, not from re-reading all the code

Recipe: Capture institutional knowledge before someone leaves

1. Interview the expert:
   /grill-me about the payment system

2. Save each answer as a wiki page:
   agent-notes memory ingest "Payment edge cases" "<answers>" "..." "..." "payments"

3. Future sessions can query this knowledge without the expert

Recipe: Audit a codebase and build a knowledge base simultaneously

1. Start the audit:
   "Run a full codebase audit — security, performance, architecture"
   
   → [security-auditor, performance-profiler, system-auditor, database-specialist] run in parallel

2. Save audit findings to wiki:
   Each finding becomes a concept or entity page with cross-references

3. Save action items to Obsidian:
   Critical findings → Decisions ("we will fix X because Y")
   Recurring issues → Patterns ("always check Z when touching this area")
   
4. Future sessions can query:
   "What security issues did the audit find?"
   → Wiki has the answer, with links to affected code

Recipe: Track a multi-session feature across weeks

Session 1 (Monday):
  → Session note: "Started auth rewrite — Phase 1 discovery"
  → Decision: "JWT over session cookies — reason: mobile API needs stateless auth"

Session 2 (Wednesday):
  → Session note: "Auth rewrite Phase 2 — implementation"
  → Pattern: "Token refresh uses sliding window, not fixed expiry"
  → Mistake: "Don't invalidate all tokens on password change — only flag for re-auth"

Session 3 (Friday):
  → Session note: "Auth rewrite Phase 3 — review + ship"
  → All sessions linked via wikilinks in Obsidian
  → Graph view shows the full story of the rewrite

Further Reading

  • Workflow — Session phases and task pipelines in detail
  • Agents — Full agent roster and delegation rules
  • Skills — All available skills
  • Memory-Storage — Storage mode comparison and configuration
  • Inspirations — Karpathy's LLM Wiki and Pocock's Skills in depth

Clone this wiki locally