Scratchpads, Memory, and Markdown Knowledge Bases
Applies to: any task that spans more than one session, and any engagement longer than a few days · Time to learn: 30 min reading + 20 min exercise · Lever: context
Agents forget everything when a session ends, and the context window is the wrong place to keep what matters (context engineering). Durable memory means files: working notes for one task, plans, instruction files, documentation, and optionally a code index. This page maps those layers and shows how to set them up so a fresh session can pick up where the last one stopped.
- Use layers: scratchpad for one task, plan for one change,
AGENTS.mdfor the repo,docs/and ADRs for decisions, and a knowledge base for the engagement. - A
SCRATCHPAD.md(findings, dead ends, working commands, open questions) survives/clearand is cheap to reload. - Plain markdown with wikilinks and frontmatter works for agents, humans, grep, and git. Keep it in the client's repo or approved storage.
- A code knowledge graph MCP helps on large unfamiliar codebases. In small ones, grep is enough.
- Memory rots. Update it in the same change as the code, and prune what is stale.
Why it matters in the AI age
FDEs move between client systems fast, and each new session starts cold. Anthropic describes structured note-taking, where the agent writes notes to memory outside the context window and reads them back later, as a core technique for long-horizon work (Effective context engineering). Karpathy's "LLM wiki" idea goes further: have the LLM build and maintain a persistent wiki instead of re-deriving knowledge on every question (gist). Both rest on the same principle: notes in plain files, owned by the repo.
Core concepts
The memory layers
| Layer | Holds | Lifetime | Who writes it |
|---|---|---|---|
| Session context | Everything in the current conversation | Until /clear or session end | You and the agent, implicitly |
| Scratchpad / scratchbook | Findings, dead ends, working commands, open questions for one task | The task | Agent and you |
| Execution plan | Steps, status, verification for one change | The change | Agent drafts, you review |
| AGENTS.md / CLAUDE.md | Build and test commands, conventions, boundaries | Life of the repo | Humans, reviewed in PRs |
docs/ and ADRs | Architecture, decisions with context and consequences | Life of the repo | Humans and agents, reviewed |
| Knowledge base (vault) | Client glossary, systems map, runbooks, meeting notes | The engagement | Humans and agents |
| Agent auto memory | Learnings the tool decided to keep | Per project, until deleted | The agent |
| Code knowledge graph MCP | Derived index of symbols, calls, and structure | Rebuilt as code changes | The indexer |
Rule of thumb: write each fact in the narrowest layer that will still need it, and promote it up when it proves durable. A command that worked today goes in the scratchpad; a command every contributor needs goes in AGENTS.md.
How to do it
1. Keep a scratchpad for each task
A scratchpad (some teams call it a scratchbook) is a markdown file for one task's working notes. Use SCRATCHPAD.md in the repo root or one file per task under notes/. Gitignore it if it holds client-sensitive detail or half-formed ideas; commit it if the team should see it, for example on a long-running branch.
Why it beats chat history:
| Chat history | Scratchpad |
|---|---|
Lost on /clear or a new session | Survives both |
| Full of noise: tool output, retries | Only what you decided was worth keeping |
| Expensive to reload (the whole thread) | A few dozen lines |
| Hard to review or edit | Plain text you can fix by hand |
| Invisible to teammates | Readable by humans, agents, and git |
# Task: fix duplicate invoice emails (TICKET-1234)
Updated: 2026-10-22
## Goal
Invoices must be emailed once per payment. Done when `test_invoice_email_once` passes.
## Findings
- Duplicate comes from `billing/retry.py:88`: retry re-enqueues the send job.
- Job id is not idempotent (uses timestamp).
## Dead ends (do not retry)
- Deduplicating in the mail gateway: gateway has no stable key.
## Commands that worked
- `pytest tests/billing -q -x`
- `make run-worker LOG_LEVEL=debug`
## Open questions
- [ ] Does finance expect a resend after a refund? Ask the finance lead.
## Next step
Make job id = payment id; add test; then update docs/runbooks/billing.md.
Tell the agent to maintain it: "Keep SCRATCHPAD.md updated as you learn things. Before I clear the session, make sure Findings, Dead ends, and Next step are current." At the start of the next session: "Read SCRATCHPAD.md and continue." When the task is done, promote durable lessons (to AGENTS.md, a doc, or an ADR) and delete the file.
2. Build an Obsidian-style markdown knowledge base
For anything bigger than one task, use a folder of plain markdown notes: one note per concept, linked with wikilinks, with YAML frontmatter for metadata, and an index note as the entry point. In Obsidian's syntax, a link looks like [[Three laws of motion]], a folder-qualified link like [[Projects/Three laws of motion]], a heading link like [[About Obsidian#Links are first-class citizens]], and display text uses | (Obsidian links). Because it is plain text, the same vault works with Obsidian for browsing, with grep and agents for retrieval, and with git for history and review.
---
type: system
owner: platform-team
status: active
updated: 2026-10-22
tags: [billing, python]
---
# Billing service
Handles payment retries and invoice emails. Part of [[Systems map]].
- Repo: `client-org/billing`
- Depends on: [[Payments gateway]], [[Mail gateway]]
- Runbook: [[Runbook - billing retries]]
- Decisions: [[ADR-0007 idempotent job ids]]
- Terms: [[Glossary#Dunning]]
Suggested vault layout for an FDE engagement
vault/
index.md # entry point: what is here, where to start
glossary.md # client terms and acronyms, one heading each
systems/ # one note per system: purpose, repo, owners, dependencies
systems-map.md # how the systems connect (Mermaid is fine)
people-and-roles.md # roles and responsibilities, no personal data
decisions/ # short decision notes; link to ADRs in the repo
runbooks/ # how to deploy, debug, recover
meetings/ # dated notes with decisions and actions
inbox/ # unsorted notes, triaged weekly
Conventions that keep it useful to agents:
- Write a one-sentence summary at the top of each note, so a search hit is self-explanatory.
- Name notes with the term people actually use, so
grepand wikilinks find them. - Put dates and a
statusin frontmatter; an agent can then tell stale from current. - Link generously. Each link is a pointer an agent can follow instead of searching.
- Point the agent at the vault from
AGENTS.md: "Client knowledge lives invault/; start atvault/index.md."
Data handling
The vault holds client information, so it follows the client's rules.
- Keep it in the client's repository or in storage the client has approved, not in a personal cloud folder or a public repo.
- Record roles and responsibilities, not personal data (no private contact details, no HR information).
- Never store secrets, tokens, or customer data in notes. Link to the secret manager entry instead.
- Check whether the client permits sending vault content to your AI provider at all before pointing an agent at it; see how we build for our security baseline.
- Hand the vault over at the end of the engagement, in the client's repo, so the knowledge stays with the client.
Karpathy's LLM wiki
Andrej Karpathy's April 2026 gist llm-wiki.md describes a pattern with three parts: raw sources (a curated, immutable collection the LLM reads but never modifies), a wiki (a directory of LLM-generated markdown files), and a schema (a document such as CLAUDE.md or AGENTS.md that tells the LLM how to maintain the wiki). An index catalogues the wiki and is updated on every ingest. The central idea is that the LLM incrementally builds and maintains a persistent wiki (gist). The vault above is this pattern applied to an engagement: raw sources in meetings/ and client documents, synthesised notes in systems/ and runbooks/, and the schema in AGENTS.md.
3. Use markdown docs in the repo (docs-as-code)
Documentation that lives next to the code is reviewed in the same PR, versioned with it, and readable by every agent without extra tooling.
- Keep
docs/in the repo with architecture notes, runbooks, and onboarding. - Record significant decisions as ADRs in
docs/adr/(context, decision, consequences). Agents read ADRs to learn why the code looks the way it does, and avoid reversing a deliberate choice. Our ADR standard and template are in how we build. - Make documentation part of the definition of done, so a change that alters behaviour also updates the doc.
4. Know what Claude Code remembers for you
Claude Code has two memory mechanisms, both loaded at session start (memory docs):
CLAUDE.md (and AGENTS.md) | Auto memory | |
|---|---|---|
| Content | Instructions and rules | Learnings and patterns |
| Written by | You | Claude |
| Scope | Project, user, or organisation | Per project |
| Location | Repo root, .claude/, ~/.claude/ | ~/.claude/projects/<project>/memory/ |
| Loaded | Every session | Every session: first 200 lines or 25KB |
Auto memory is on by default in local sessions; toggle it with /memory, which also opens and edits the files (memory docs). Treat it as a convenience, not a source of truth: it lives on your machine, not in the repo, so teammates and other harnesses cannot see it. Anything the team needs belongs in AGENTS.md or docs/. Review the auto memory files now and then and delete entries that are wrong or client-specific when you leave an engagement. The instruction files are covered in AGENTS.md and rules.
5. Add a memory MCP only when files are not enough
MCP servers can add queryable memory. Each one costs context and an install decision; see MCP servers.
| Server | What it is | Good for | Notes |
|---|---|---|---|
codebase-memory-mcp (DeusData/codebase-memory-mcp) | Persistent local knowledge graph of code, docs, config, and infrastructure | Large unfamiliar codebases, call-graph and structure questions | Backend only, no built-in LLM; single native binary |
Basic Memory (basicmachines-co/basic-memory) | Markdown notes stored as files, exposed over MCP | Letting an agent read and write the same vault you browse in Obsidian | AGPL-3.0 licence: check it fits your use before adopting |
Reference MCP memory server (@modelcontextprotocol/server-memory) | "A basic implementation of persistent memory using a local knowledge graph": entities, relations, observations | Simple experiments | Stores memory.jsonl (override with MEMORY_FILE_PATH) |
Serena (oraios/serena) | Semantic retrieval and editing toolkit using symbol-level tools via LSP | Symbol-aware navigation and edits | Licence: SolidLSP MIT, app GPL-3.0-or-later |
codebase-memory-mcp in more detail
It parses a repository with tree-sitter (the README lists 162 vendored grammars as of 2026-10) and adds hybrid LSP-based resolution for selected languages such as Python, TypeScript, Go, Java, and Rust. A background watcher re-indexes on change. The README says it exposes 17 MCP tools, including index_repository, index_status, search_graph, search_code, trace_path, get_architecture, detect_changes, and manage_adr (repo).
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
{
"mcpServers": {
"codebase-memory-mcp": {
"command": "/path/to/codebase-memory-mcp",
"args": []
}
}
}
The README also suggests asking the agent to "Install this MCP server" with the repo URL. Review the install script before you run it on a client machine, as you would any curl | bash.
Claimed savings, with a caveat. The preprint and README claim about 10x lower token use and 2.1x fewer tool calls than file-by-file exploration, with answer quality of 83% versus 92% for a file-exploration agent. The README also cites roughly 3,400 versus 412,000 tokens for five structural queries (preprint, repo). These come from the project's own preprint and README, and the quality figure shows the trade-off: cheaper, but less accurate than reading the files. Verify on your own repository.
Basic Memory
Install for Claude Code: claude mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp. Notes are markdown files, and Obsidian shows the same wikilinks, frontmatter, and graph view (repo). It is AGPL-3.0, so confirm the licence is acceptable to you and your client before running it in a client environment.
When a code graph helps, and when grep is enough
| Situation | Use |
|---|---|
| Small or familiar repo; you know the names | grep/rg and file reads |
| "Where is this string or symbol used?" | grep/rg |
| Large unfamiliar monorepo; where does the request flow? | Code graph (trace_path, get_architecture) |
| "What calls this function, across modules?" | Code graph |
| Exact text, config values, error messages | grep |
| Need answers you can fully trust | Read the files the graph points to |
Start with grep and subagents. Add a graph server when exploration cost is a real problem on a specific repository, and measure the difference.
6. Keep memory fresh
Stale notes are worse than none, because the agent will trust them.
- Update in the same change. When code changes behaviour, update the doc, runbook, and
AGENTS.mdline in the same PR. A post-change-update skill can prompt the agent to check which notes the diff affects, and a hook or pre-commit gate can remind you or fail the build when it does not. - Date and own your notes.
updated:andowner:in frontmatter make staleness visible. - Prune weekly. Triage
inbox/, delete finished scratchpads, and remove auto-memory entries that no longer hold. - Promote, then delete. Move durable lessons from the scratchpad to the right layer, then remove the scratchpad.
- Let the agent help. "List notes in
vault/that mention billing and check them against the current code" is a cheap review.
Best practices
- Write to the narrowest layer first and promote what proves durable.
- Keep each note small and focused: one concept, one summary line, links to related notes.
- Prefer files in the repo over tool-private memory, so every teammate and harness benefits.
- Give agents an entry point (
vault/index.md) rather than the whole vault. - Ask the agent to cite which note it relied on, so you can spot stale ones.
- Treat memory servers as optional accelerators over files, not replacements.
Pitfalls to design around
- Store knowledge where the team can see it. Auto memory on one laptop does not help the next engineer.
- Keep client data in client-approved locations, and never put secrets in notes.
- Use dates and owners so old notes are recognisable as old.
- Keep scratchpads task-scoped, and delete them when done, so they do not become a second, unreviewed docs folder.
- Check licences (AGPL for Basic Memory, GPL for Serena's app, BUSL for parts of rtk) before using a tool on client work.
- Verify graph answers against the code for decisions that matter.
Try it
Lab 20 minutes on a real repository.
- Start a task and ask the agent to create
SCRATCHPAD.mdusing the template above, updating it as it works. - After 10 minutes, run
/clear. Start a new session with "ReadSCRATCHPAD.mdand continue." Note what you did not have to re-explain. - Create
vault/index.md,vault/glossary.md, and one system note with frontmatter and wikilinks. Add a line toAGENTS.mdpointing to the vault. - Ask the agent a question about the system and check that it follows your links.
- Optional: on a large repo, install codebase-memory-mcp and compare one "who calls this" question against grep.
Checklist
- I know which layer each kind of fact belongs in.
- I keep a scratchpad for multi-session tasks and resume from it after
/clear. - The engagement vault has an index, glossary, systems notes, and frontmatter with dates.
- The vault lives in the client's repo or approved storage and holds no secrets or personal data.
- Decisions are recorded as ADRs, following how we build.
- Docs and notes are updated in the same change as the code.
- I checked the licence and client approval before installing any memory MCP.
Sources
- Anthropic, Claude Code memory (CLAUDE.md, auto memory, 200 lines or 25KB)
- Anthropic, Effective context engineering for AI agents (structured note-taking)
- Karpathy, llm-wiki.md gist (2026-04-04)
- Obsidian, Internal links
- DeusData/codebase-memory-mcp (README as of 2026-10: 162 grammars, 17 tools, savings claims)
- Preprint, codebase-memory-mcp (arXiv 2603.27277)
- basicmachines-co/basic-memory (AGPL-3.0)
- oraios/serena (licences)
- MCP reference memory server