Every new Claude session started from zero. Here's how I fixed it.

There's a specific kind of frustration that comes after you've been working with Claude Code for a few weeks.

You open a new session. You start describing your project. The agent asks a clarifying question — and you realize it's the same question it asked in session three. You've explained this before. You've made this decision. You've already ruled out that approach, and you even remember why. But the agent doesn't.

The context window closes. The session ends. Everything that wasn't written somewhere permanent evaporates.

I hit this wall hard while working on a governance software product with interconnected decisions across infrastructure, product architecture, compliance scope, and research writing. Every session felt like onboarding a new contractor who needed to be caught up from scratch. I was spending 20% of every session on re-explanation.

The fix wasn't a better prompt. It was a memory layer.

What the problem actually is

Claude Code is stateless by design. Each session starts with whatever you hand it at the top: a CLAUDE.md, some file paths, maybe a few recent commits. That's the entire context budget for "what is this project and how does it work."

Most people solve this by making CLAUDE.md longer. That doesn't scale. You can't fit the full reasoning behind a year of architectural decisions into a header file.

What you actually need is a knowledge graph that the agent can traverse — not a flat dump it has to read all at once.

The architecture that works

I use Obsidian as the memory layer. The structure has three zones:

raw/         ← unsynthesized captures, preserved exactly as written
wiki/        ← synthesized notes with inline [[links]] to related concepts
CLAUDE.md    ← entry point: points to the project hub, not a wall of text

The wiki/ directory is the knowledge graph. Every note in it must have at least two meaningful inline [[links]] to other notes — not links dumped at the bottom in a "Related" section, but links woven into the body where the actual connection is made.

The CLAUDE.md is deliberately short. It points to a project hub note, which links outward to decision logs, architecture notes, people, open questions, and constraints. The agent traverses the graph instead of reading a monolith.

The note types that matter

Decision log:

# Decision: Auth Layer Scope

**Status:** Locked  
**Date:** 2026-03-12

## Decision
Keep auth separate from the API gateway layer.

## Alternatives Rejected
- Unified middleware: rejected — couples deploy cycles, adds latency on every request.
- Auth-in-gateway: rejected — obscures auth logic, harder to test independently.

## Open Questions
- [ ] Whether internal calls should bypass gateway or proxy through

When this note is linked from the project hub, the agent sees it before making architectural suggestions. It won't re-propose the unified middleware. It already knows why you rejected it.

Active constraints note:

# Project Constraints

- [[Deployment Target]]: Cloudflare Pages + Workers only (no VMs)
- [[Language]]: TypeScript frontend, Python backend — no language additions without discussion
- [[Compliance]]: PIPEDA + Quebec Law 25 in scope; EU AI Act out of scope v1
- [[Timeline]]: Revenue-positive by 2026-06-22

Short, linked, updated as constraints change. The agent loads this in the first traversal hop and never proposes something that violates a locked constraint.

Open questions note:

# Open Questions

- [ ] Railway vs Hetzner for backend hosting — decision pending cost analysis
- [ ] Whether regulatory corpus ingestion is in scope for v1
- [ ] CF Pages recreate vs rename — CF dashboard action required first

This replaces the end-of-session "TODO" you write in chat that disappears when the session closes.

The linking rule that makes it work

The structure only holds if every note is connected into the graph — reachable via traversal, not just search.

A note that exists in wiki/ but has no backlinks from anywhere is invisible to the agent unless it reads every file. That defeats the purpose.

The test I use: can the agent get from CLAUDE.md to this note in three hops or fewer? If not, something in the chain is broken.

I enforce this with a simple protocol:

• Before creating any note, search for related existing notes
• Always add [[links]] inline in the body (not just at the end)
• After creating a note, update the relevant hub or MOC page so it links back
• Never create orphan notes

With 212 notes in my vault, the agent reliably finds relevant context without brute-force reading. It traverses. That's the difference.

What I packaged

After building and refining this over several months, I packaged the vault structure as a template:

• Vault skeleton with the raw/wiki/maps/templates structure pre-configured
• Hub templates (project, person, concept, decision) that enforce the linking pattern before you fill in content
• Four named skill guides (Caelir for research synthesis, Ilyris for topic mapping, Ariun for linking hygiene, Mnara for archiving stale material) — these are plain-language instruction files the agent follows when invoked
• Optional local runtime (setup.sh + ask.py + vault_watcher.py) for running queries against the vault without a cloud subscription
• CLAUDE.md patterns that actually scale as the vault grows

The template is $49 and available here: Obsidian Agent Vault

There's also a $299 guided setup option if you want help adapting the structure to your specific project type, and a $2,500 team license for small teams wanting a shared memory layer.

---

The core insight: an AI agent with a well-structured graph of your project's decisions, constraints, and open questions is a fundamentally different tool than one reading a long CLAUDE.md cold. The structure is what makes context persistent. The linking discipline is what makes it traversable.

Happy to share the hub template or the linking-hygiene skill guide in the comments if there's interest.