Here is the translation of your article into English. I have maintained your direct, pragmatic engineering tone (suitable for audiences on Hacker News or Dev.to), preserved the scannable layout, and completely avoided em-dashes to match your typography rules.

CLAUDE.md and Obsidian: How I Give AI Agents Context and Memory

In the first article, I covered my journey from Tabnine to Claude and my very first custom orchestrator. Today, we are talking about the foundation. Without it, AI agents will rapidly turn your codebase into an unmanageable mess.

The Problem: An Agent Without Context

The first time I spun up Claude Code on a real project, it wrote working code. It was technically accurate, and completely wrong for the project style.

It did not know I used Hexagonal Architecture on the backend. It did not know em-dashes were banned project-wide. It did not know the vendor/ directory was strictly off-limits. It did not know there were two active terrains in the Unity scene, or that deployment relied on a specific bash script.

An AI agent is like a brilliant senior developer with total amnesia. Every session starts from scratch. If you do not explicitly state your rules, it will make up its own.

The solution turned out to be a single file in the project root.

What is CLAUDE.md

CLAUDE.md is a file in the root of your repository that Claude Code automatically reads whenever a new session initializes. This is not documentation for human beings. It is a declarative instruction set for the agent: what is allowed, what is forbidden, how the project is structured, and where to look for deeper context.

Think of it as an onboarding checklist for a new employee who forgets everything overnight. It sounds absurd, but that is exactly how LLMs operate. This file is far more critical than any single prompt.

A prompt handles a one-off task. CLAUDE.md defines the permanent rules of the game.

Three Projects, Three Approaches

I currently run three active projects on entirely different stacks. Each has its own custom CLAUDE.md because the projects vary in complexity and stage.

1. Exorim (MMO Game): The Multi-Layered Setup

Exorim is built on Unity + Colyseus + Laravel + Nuxt. It is a monorepo with four distinct components. The config file started at a couple of kilobytes, grew to a massive 22KB, and was eventually split.

Right now, the root file is roughly 12KB and handles global rules. Each individual component (game-server, game-client, web-backend, web-frontend) has its own nested CLAUDE.md file with local specificities. When you launch a Claude Code session inside a specific component directory, it reads both the root file and the local file.

Key elements of the Exorim root file:

  • The Typography Rule: This sits at the very top of the file. Em-dashes are strictly banned project-wide. It sounds trivial, but after the agent broke YAML parsing three times by inserting em-dashes into configuration files, this rule became priority number one. If it encounters an em-dash in existing code, it must replace it upon editing.
  • Session Start Checklist: Before touching anything, the agent is required to read the architectural overview for that component, check the active issue status in Linear, and read the DEVELOPMENT/ logs from past sessions. Without this, it works blind.
  • Post-Task Responsibilities: Once a task is complete, the agent must update the internal architectural docs and append a new log to DEVELOPMENT/*.md. If the agent changes a MongoDB schema or introduces a new service without logging it, the next session will run into immediate conflicts.
  • Off-Limits Directories: A strict list of folders the agent must never touch: misc/, 3d/, NFT/, ton/. This prevents the agent from wasting tokens indexing non-essential asset folders or modifying areas outside its current assignment.
  • Quick Reference: A clean table mapping components to their respective stacks and paths. The agent immediately sees that game-server runs on Node.js + Colyseus + MongoDB, rather than Django + PostgreSQL.

2. ProVybor (B2B Marketplace): The Minimalist Manifesto

ProVybor runs on Laravel + Nuxt across two repositories. The CLAUDE.md file here is tiny: only about 30 lines. This is an intentional choice, not laziness.

ProVybor is a standard web application. Because the agent already understands Laravel, Nuxt, and Hexagonal Architecture out of the box, it does not need extensive hand-holding. The file simply contains a single-paragraph product description, tracking links (using YouTrack instead of Linear), a pointer to DECISIONS.md, and the current primary blocker.

The standout feature here is the everyday-tasks/ directory, which holds granular summaries of completed tasks indexed by date and slug. The agent scans this index before planning a new feature to ensure it does not contradict or duplicate past architectural decisions.

3. WII Home (Smart Home): Hardware-Specific Rules

This project links TypeScript on a Raspberry Pi, Python on an RTX 3060 server, MQTT, and a voice assistant. Because the stack is highly customized, it requires the largest and most detailed CLAUDE.md file of the three.

  • ASCII Network Topology: A literal text-based network diagram mapping out device IPs and their relationships over MQTT. The agent reviews this at startup to understand the physical architecture.
  • Three Layers of Memory: We maintain explicit separation here. Layer one is the agent instruction file itself. Layer two is the voice assistant memory file on the server (which the agent cannot write to directly). Layer three is the curated knowledge vault inside Obsidian (docs/memories/), which the agent updates when it learns something new. Without this structure, the agent would pollute the wrong memory files and break the voice assistant.
  • Hardware Specifics: The file states that building on the Raspberry Pi via SSH requires running source ~/.nvm/nvm.sh before executing any npm command. Non-interactive SSH sessions do not inherit the NVM environment automatically. This rule was written in blood after the very first automated deploy failed.

The Four Essential Pillars of any CLAUDE.md

Regardless of the project size, a highly functional agent config file requires four core sections:

  1. Strict Bans: Clearly define what the agent cannot do. List forbidden commands, directory exclusions, and style violations. An agent assumes everything is permitted by default. If you do not explicitly forbid destructive commands like migrate:fresh, it will eventually run them.
  2. Project Context: Explicitly map out the stack, general architecture, and directory layout. Avoid making the agent guess your tech choices.
  3. Mandatory Pre-reads: Links to files the agent must read before writing code: the core architecture guide, the decision log, and current sprint goals.
  4. Nested Configurations: For multi-component or polyglot repositories, use a high-level root file paired with specialized, nested files in subdirectories. Claude Code handles the resolution automatically based on your active directory.

What to exclude: Keep full feature documentation, running TODO lists, complete change logs, and raw prompt text out of your CLAUDE.md. Apply the 8-out-of-10 rule: if a piece of information is required for 80% of daily tasks, keep it in the root config. If it is only needed occasionally, move it to a dedicated docs/ folder.

Obsidian: Solving Long-Term Amnesia

While CLAUDE.md provides perfect context within a session, it does not solve the long-term memory problem. Every time you close and reopen a Claude Code session, the agent resets to a blank slate.

I solve this by turning the project docs/ folder into an Obsidian vault.

The Setup

The docs/ folder inside the Git repository is a symlink directly to an active Obsidian vault. I manage and navigate it as a local developer wiki, while the AI agent interacts with it as standard markdown files over the local file system.

When the agent finishes a task and appends a log entry to docs/DEVELOPMENT/SERVER_TASK.md, my Obsidian graph updates in real time. When I write a design note inside Obsidian, the agent picks it up the second the next session starts.

Inside the Vault

  • DEVELOPMENT/*.md: Chronological operational logs. The agent appends (never overwrites) what was built, which files were touched, and any technical debt left behind.
  • DECISIONS.md: A numbered Architecture Decision Log (ADR) containing dates, choices, and justifications. If the agent knows exactly why MongoDB was chosen over PostgreSQL for the game server, it will not suggest a database migration during a routine refactor.
  • architecture/*.md: Component-level architectural documentation that the agent is explicitly tasked with updating after completing any structural changes.

For the smart home project, I use an MCP server called MCPVault to connect Obsidian directly to Claude. This gives the agent native utilities like advanced BM25 note searching and precise file editing via a patch_note tool. This tool modifies specific blocks without risking a full file overwrite, which is a known issue with standard file tools. For standard web projects, native file reading is more than enough. MCP servers become useful once your vault scales past 100 deep technical notes.

Why Not RAG?

A common question I get is why I do not just spin up a Retrieval-Augmented Generation pipeline, index everything into a vector database, and let the model query embeddings.

The reality is that a well-structured CLAUDE.md paired with an Obsidian vault delivers 80% of the value of RAG with 0% of the infrastructure overhead.

A proper RAG pipeline requires a vector database (like Chroma or Pinecone), a document chunking strategy, embedding updates on every commit, and continuous retrieval evaluation. It quickly becomes an entirely separate software project to maintain.

Modern context windows are massive. Claude Code can natively parse your core architecture guides, the active issue details, and your recent change history without breaking a sweat. For a solo developer managing a few codebases, RAG is pure overengineering. I will look into vector backends the day a project hits hundreds of thousands of lines of code with a large team. Until then, flat markdown files win.

The Three Stages of Evolution

My configuration system evolved through three distinct phases driven by real production issues:

  • Stage 1: The 2KB Flat File. A brief description of the stack and a couple of basic bans. It works for about a week, right until the agent makes a critical structural mistake you thought you already explained.
  • Stage 2: The 22KB Megalith. You put everything into a single root file. It stops the bugs, but you end up burning roughly 20,000 tokens at the start of every single session. You waste 10% of your context window just reading your own rules.
  • Stage 3: Split System (Root + Nested + Docs). The root file shrinks back down to 12KB for universal rules. Component-specific files sit in their respective folders and load only when needed. Deep references stay in docs/ and are opened purely on demand. The agent gets highly relevant context, and your token usage drops significantly.

Practical Implementation Tips

If you are setting up Claude Code on your own project today, use this roadmap:

  • Start with explicit bans. Document the exact destructive terminal commands, unapproved libraries, and directories the agent must never touch.
  • Write rules in response to bugs. Every time your agent makes a stupid mistake, do not just fix the code. Ask yourself: What single sentence can I add to CLAUDE.md to ensure this never happens again? My em-dash ban and NVM path fixes came directly from real-world triage.
  • Do not write for humans. Skip the polite transitions, pleasantries, and philosophical explanations. Use clean, imperative, declarative blocks: Do X, Never do Y, Read Z first.
  • Keep an architecture decision log from day one. Document your technical choices early. It prevents the model from wasting time trying to redesign your entire core system layout during a simple bug fix.

This is the second installment in a series detailing solo game development using AI agents. In the next article, we will dissect the prompt cycle: how to write unambiguous tasks, how to audit code diffs efficiently, and the exact architectural boundaries where modern LLMs still consistently fail.