Every Claude Code session used to start the same way. I’d open a terminal, type something like “add a retry handler to the lingopop backend,” and get back: “I don’t have information about lingopop in this session. Could you describe the project?” Fifteen minutes of re-explaining architecture later, we’d finally do the actual work.

That’s fixed now. The session I ran this morning opened with the CI pipeline spec, the k3s namespace, the HeatWave DSN catch, and the exact deploy command — all without me saying a word about any of it. The fix isn’t a new model or a longer context window. It’s a structured vault that lives on disk and a set of rules that tell the agent exactly where to look.

Here’s the whole setup.

Key Takeaways

• 84% of developers use or plan to use AI tools, but only 29% trust AI accuracy — down from 40% the year before (Stack Overflow Developer Survey, n=49,000+). The trust gap is mostly a context problem, not a model problem.
• A PARA-structured vault with per-project index.md files gives every agent session a read target before the first prompt.
• A “compile pass” — triggered explicitly, never autonomous — keeps the vault fresh by routing daily captures to the right project pages.
• The agentmemory MCP server closes the write loop: decisions made during a session get persisted back without manual note-taking.

Why do AI coding tools keep forgetting your project?

According to the Stack Overflow Developer Survey (n=49,000+), 84% of developers now use or plan to use AI coding tools, and 51% use them daily. Yet trust in AI accuracy fell from 40% to just 29% — the lowest on record (Stack Overflow). That’s a trust collapse happening right alongside an adoption boom.

Most commentary blames the models. I don’t think that’s right. The real problem is context loss between sessions. Every new conversation starts blank. The agent has no memory of your stack, your deploy targets, your architectural decisions from last week, or the TLS snag HeatWave throws at you. So it hallucinates, guesses wrong, or asks you to explain things you’ve already explained a dozen times.

A METR study (arXiv:2507.09089) found experienced developers were 19% slower with AI tools than without them. Not because the tools are bad. Because experienced devs have complex, multi-file projects with history and context that the agent can’t see. The re-explanation overhead eats the time savings.

The trust collapse and the productivity regression are both pointing at the same root cause: the quality of context the agent receives, not the quality of the model. Fix the context layer and you fix both problems. That’s what the vault does.

Citation capsule: According to the Stack Overflow Developer Survey (n=49,000+), 84% of developers use or plan to use AI tools and 51% use them daily, yet trust in AI accuracy has fallen from 40% to just 29% — the lowest recorded. The METR study (arXiv:2507.09089) found experienced developers are 19% slower with AI tools, suggesting context overhead, not model quality, is the primary drag on productivity.

[INTERNAL-LINK: my $0 OCI k3s cluster → post 09 “How I Run This Site on a $0 Kubernetes Cluster”]

What goes where: the PARA vault structure

I run five projects across three VPS instances and a k3s cluster. Without a system, project context lives everywhere: scattered across git commit messages, a half-remembered Notion page, a terminal history that scrolls off. The Asana Anatomy of Work Index (via Speakwise, 2026) found that 60% of knowledge worker time goes to “work about work” — searching, re-explaining, re-locating context that already exists.

The 46-minute figure in that chart isn’t invented. Research from Gloria Mark at the University of California Irvine found it takes an average of 23 minutes 15 seconds to regain full focus after an interruption (widely cited, 2026). When an AI confidently gives you wrong output and you have to context-switch to debug it, that’s a real interruption with a real recovery cost.

My vault lives at ~/vault/ and follows a PARA structure. The folders that matter most to AI sessions are:

~/vault/
  CLAUDE.md                    # global agent rules, folder map
  Projects/
    lingopop/index.md          # deploy commands, stack, known issues, TODOs
    pcprice.watch/index.md
    diavgeia-monitor/index.md
    car-statistics-greece/index.md
  Areas/
    infra/
      k3s-cluster.md           # cluster runbook
      cloudflare-tunnel.md     # tunnel + Access config
      oci/overview.md          # OCI account, VCN, HeatWave
  Inbox/                       # raw daily captures — drained by compile pass
  Inbox/_processed/            # archived items after compilation
  Templates/
    project-index.md           # template for new project index files

Each Projects/<name>/index.md is structured for AI consumption, not human reading. That’s a distinction most people miss. Human notes are prose. AI-consumption notes are structured tables with explicit labels: “How to deploy,” “Where it runs,” “Gotchas,” “Active TODOs.” When an agent reads a properly structured index file, it can answer operational questions without guessing.

[INTERNAL-LINK: self-hosted Umami → post 11 “Why I Moved My Analytics Off Vercel and Onto a Free MySQL Box”]

The CLAUDE.md layer: standing orders for every agent

Over 60,000 open-source projects have adopted AGENTS.md or CLAUDE.md files as of 2026, according to DeployHQ’s AI Coding Config Files Guide (DeployHQ, 2026). The pattern is simple: a file at the repo root that gives the AI agent its standing orders. What it should do, what it shouldn’t, where to look.

My global ~/vault/CLAUDE.md goes a step further. It’s not just a per-repo instruction file — it’s the operating manual for every agent session I run, regardless of which project I’m in. The key sections:

North star. One line: “Zero re-teaching tax.” If I have to explain a project to the agent, the vault has failed. That sentence keeps me honest when I’m tempted to skip updating a project index after a deploy.

Folder map. Tells the agent which folder handles what. Without this, an agent reading ~/vault/ cold has no idea that Inbox/ is raw captures and Areas/infra/ is runbooks. With it, the first thing the agent does in a new session is read Projects/<this-project>/index.md and Areas/infra/ — it knows where to go.

Commit format. Single-line subject, no AI attribution, no Co-Authored-By trailers. This is the one that saves me the most editing time. Left to its defaults, every commit message from an AI agent is a three-paragraph essay.

Pointer-secrets convention. Never write a secret into the vault. Write a pointer: OCI API key → 1Password entry "OCI-API-prod". This means the vault can live in a private git repo without becoming a secret store. The agent knows not to look for actual credentials in vault files.

Compile pass trigger. The rule “never compile autonomously — only on explicit user instruction” is load-bearing. Without it, an agent might decide to reorganize your vault mid-session, which is not what you want in the middle of a debugging run.

Citation capsule: More than 60,000 open-source projects have adopted AI coding configuration files like AGENTS.md or CLAUDE.md as of 2026, according to DeployHQ (DeployHQ, 2026). These files function as standing orders for agent sessions: they specify folder maps, commit formats, secrets conventions, and behavioral constraints that persist across every session without re-prompting.

What’s the difference between a CLAUDE.md and a system prompt you paste each time? The CLAUDE.md lives in the filesystem. The agent reads it as data, not instructions injected into the conversation. That means it can be version-controlled, diff’d, and updated like any other file. It’s a living document, not a static incantation.

The compile pass: how the vault stays fresh

A vault that doesn’t get updated is just a stale wiki. Most note-taking systems fail here: you capture something in Inbox/, you never drain it, and six months later you have 200 unprocessed captures and a vault that’s worse than useless because it has outdated information mixed with current information.

The compile pass is what keeps mine current. When I say “compile inbox,” the agent:

1. Reads every file under Inbox/ (skipping _processed/).
2. For each item, decides which existing PARA page it updates — or whether it creates a new one.
3. Integrates, doesn’t append. Operational facts — deploy commands, hosts, URLs, tricky bits — get routed to the relevant Projects/<name>/index.md and written into the right section, not pasted at the bottom.
4. Flags contradictions with > [!warning] blocks. If a new capture says “HeatWave IP is 10.0.3.200” and the existing vault says “10.0.3.117,” the agent surfaces that rather than silently overwriting.
5. Moves the raw item to Inbox/_processed/<YYYY-MM-DD>/ and commits.

I ran a compile pass last week after three days of captures had piled up. The result was changes to four project index files, two new runbook steps in Areas/infra/k3s-cluster.md, and one contradiction flag on a HeatWave connection string I’d updated in one place but not the other. The commit message was compile: 11 inbox items → 6 files updated, 0 new.

That contradiction flag is the part I’d miss most if I didn’t have it. The vault’s whole value is that it’s accurate. A flag on an inconsistency tells me exactly where to verify, which is far better than silently trusting stale data.

The “never autonomous” rule matters here. The compile pass has real write access to your project notes. You want to be in the loop when it runs. Triggering it explicitly gives you the chance to review the summary before anything gets committed.

[INTERNAL-LINK: Cloudflare Tunnel → post 10 “How I Expose Self-Hosted Services Without Opening a Single Port”]

The agentmemory MCP: closing the write loop

The Model Context Protocol has gone from a curiosity to infrastructure fast. By March 2026, MCP had reached 97 million monthly SDK downloads, up from roughly 22 million a year earlier. The server registry grew from 1,200 to 9,400+ servers over the same period (Digital Applied / Anthropic, 2026). That kind of adoption curve usually means the abstraction is genuinely useful.

The agentmemory MCP server closes a gap the vault alone doesn’t cover: write-back from live sessions. The vault holds what I’ve explicitly captured. But every session produces decisions, discoveries, and things that bit me that I never get around to capturing. The agentmemory hooks intercept those and persist them automatically.

Setup is two commands:

npm install -g @agentmemory/agentmemory@0.9.21
agentmemory connect claude-code

That adds 12 hooks to Claude Code and starts an MCP server on :3111. The hooks capture decisions and context updates from live sessions and route them back to the MCP server, which the vault can then read in a subsequent session.

Here’s the nuance most write-ups miss: agentmemory and the compile pass operate on different time horizons. The compile pass handles deliberate, structured updates — things I’ve thought about, written down, and want integrated cleanly. agentmemory handles ephemeral session state: a command that worked, a decision made mid-debug, a file path I found by trial and error. They complement each other rather than competing.

One catch: the hooks fail silently if the MCP server isn’t running. There’s no error; the hooks just don’t fire. I keep the server in a tmux pane to avoid losing session state. If you restart your machine and forget to restart the server, your next session won’t be persisting anything. Worth adding it to whatever autostart mechanism you use.

Citation capsule: The Model Context Protocol reached 97 million monthly SDK downloads by March 2026, growing from roughly 2 million in November 2024. The server registry expanded from 1,200 to over 9,400 entries in just over a year (Digital Applied / Anthropic, 2026). This adoption trajectory positions MCP as the standard persistence layer for stateful AI agent workflows.

The acid test: does it actually work?

Fresh terminal. No preamble, no “here’s what I’m working on.” Just: “What’s the deploy command for lingopop?”

Before the vault: “I don’t have information about lingopop in this session. Could you describe the project and its deployment setup?”

After: The agent reads ~/vault/Projects/lingopop/index.md from the CLAUDE.md pointer, finds the CI/CD section, and responds with the actual answer. CI triggers on push to main touching backend/**. GitHub Actions builds an arm64 image via docker buildx, pushes to ghcr.io/mariostheof/lingopop:{sha}, then runs kubectl set image deployment/lingopop-backend in the lingopop namespace and waits for rollout status. The pull secret requirement is flagged. The HeatWave TLS catch is flagged.

The first session where the agent opened by citing the deploy command without being asked was genuinely disorienting. I’d been so conditioned to the re-explanation ritual that I’d almost forgotten what productive-from-minute-one felt like. It felt less like using a tool and more like working with someone who’d been paying attention.

The honest gaps: anything decided in a recent session that hasn’t been compiled yet. A new environment variable I set yesterday won’t be in the vault until I either capture it or run a compile pass. Secrets are excluded by design — the vault has pointers, not values, so the agent can tell you where the secret lives but not what it is.

That’s the right trade-off. A vault that tried to hold everything would eventually hold secrets, outdated values, and contradictions with no flags. This one holds structured facts with explicit provenance, and it tells you when something doesn’t add up.

Is it more setup than just pasting a summary into each session? Yes, by a fair margin. Whether that overhead pays off depends entirely on how many projects you run and how often you context-switch between them. For a solo dev with five active projects across multiple servers, the math resolves quickly in favor of the vault.

Frequently asked questions

Does this work with AI tools other than Claude Code?

The vault structure works with any agent that can read files. The CLAUDE.md naming is Claude-specific, but most major AI coding tools support an equivalent — Cursor has .cursorrules, GitHub Copilot reads AGENTS.md. Over 60,000 open-source projects have adopted one of these files (DeployHQ, 2026). The compile pass workflow is agent-agnostic; any tool that can edit markdown files can perform it.

How do you avoid the vault becoming stale?

The compile pass handles this for new captures, but the deeper answer is structure. Notes written for AI consumption — with explicit section headers and structured facts rather than prose — age gracefully because they’re easy to update in-place. If your project runbook is a paragraph of prose, updating one command means rewriting sentences. If it’s a table of Command: X entries, updating a command is a one-cell edit.

What about secrets? Can you store API keys in the vault?

No. The pointer-secrets convention in CLAUDE.md is explicit: never write a secret into the vault; write a reference instead. OCI API key → 1Password entry "OCI-API-prod" tells the agent where to find the secret without the vault holding it. This matters because the vault will eventually be in a git repo, and secrets in git repos have a way of ending up somewhere they shouldn’t.

Can the agentmemory MCP replace the manual compile pass?

Not completely. agentmemory captures session state automatically, which is good for ephemeral decisions and command discoveries. The compile pass handles deliberate integration: routing a capture to the right project page, flagging contradictions, maintaining backlinks. They’re complementary. The MCP closes the write loop for things you wouldn’t remember to capture; the compile pass handles things you’ve thought about carefully enough to write down.

Wrapping up

The vault didn’t solve an AI problem. It solved an information architecture problem, and the AI benefit was a side effect of actually organizing project context well.

The Stack Overflow trust numbers are a signal worth taking seriously. Only 29% of developers trust AI accuracy (Stack Overflow). But mistrust built on context rot is different from mistrust built on model limitations. One of those you can fix with a markdown file and a compile trigger.

The setup I’ve described: a PARA vault at ~/vault/, per-project index.md files structured for AI consumption, a CLAUDE.md with standing orders, an explicit compile pass for integration, and the agentmemory MCP for session write-back. Nothing in that stack requires a subscription or a hosted service. It runs on the same free OCI cluster as everything else, costs nothing, and has eliminated the re-explanation ritual entirely.

If you try this, start with one project. Write the index.md file the way you’d brief a new collaborator who needed to get to production in an hour. That framing changes how you write it, and it’s the right framing.