Giving Codex a second brain with Obsidian

I have been using Codex across quite a few different projects, and one problem started becoming increasingly obvious.

Every Codex project is smart, but also kind of stupid.

It might understand everything about the repo I am currently working in, but switch to another project and suddenly all that context is gone. Worse, some projects are related to each other, so understanding one properly sometimes requires knowledge that lives somewhere else.

Those relationships mostly live in my head.

I wanted Codex to know them too.

So today I started setting up what is basically a second brain for Codex using Obsidian.

Obsidian isn't really the important part

The thing that finally clicked for me is that Obsidian isn't actually the brain.

The Markdown files are.

Obsidian is just a really nice interface for a folder full of Markdown. This makes it unusually good for AI agents because there isn't some special database or API that Codex needs to understand.

A note can literally just be:

# Project A

Project A is related to:
- [[Project B]]
- [[Shared Authentication]]

See also:
- [[Architecture]]
- [[Deployment]]

I can read that.

Obsidian can read that.

Codex can read that.

Git can version it.

That is a pretty useful property.

Initially I was thinking about this mostly as a place where I could write documentation for Codex. But that still means I am the one maintaining everything, which is exactly the kind of thing I know I will eventually stop doing.

What I actually want is something more active.

When Codex learns something important while working in one project, it should write that knowledge into the brain.

When I later open another related project, Codex should be able to read that same knowledge.

When I open a completely different Codex project, the brain should still be there.

So instead of every repo having its own isolated memory:

Project A -> memory
Project B -> memory
Project C -> memory

I want something closer to:

             Obsidian
                |
        shared knowledge
        /       |       \
 Project A  Project B  Project C

The repos still contain their own source code and project-specific instructions. The Obsidian vault becomes the shared context between them.

AGENTS.md becomes the policy layer

The other thing I learned today is that simply giving Codex access to an Obsidian vault isn't enough.

Without rules, the "second brain" can very quickly become a folder containing 800 AI-generated Markdown files that nobody wants to read.

Very helpful.

I already use AGENTS.md to tell Codex how I want it to behave inside my projects. So the natural extension was to use it to define how Codex should interact with the brain too.

There are really two sides to this.

The project needs to tell Codex:

There is a shared knowledge base. Look there when useful, and update it when you learn something worth remembering.

Then the Obsidian vault needs its own instructions explaining what belongs there, how notes should be structured, how existing notes should be updated, and how projects relate to each other.

The important part is update existing knowledge instead of endlessly appending new notes.

If Codex learns something about how two systems interact, that probably belongs in an existing project or architecture note.

If it learns why a technical decision was made, that can go into a decision note.

If it encounters some temporary debugging output, that probably doesn't belong in the brain at all.

Basically, I don't want a transcript of everything Codex has ever seen.

I want the stuff future Codex will actually care about.

This also changes what I think a good project AGENTS.md should contain. It isn't just coding standards anymore. It can describe the project, its relationship with other projects, where shared knowledge lives, and what information should survive after the current Codex session ends.

The part I actually find interesting

The end goal isn't really "Codex can read my Obsidian notes."

That is useful, but not particularly exciting.

What I want is for the knowledge base to maintain itself while I work.

I should be able to work normally inside a project and have Codex realise:

This is information that might matter in another session. I should update the shared knowledge.

Then months later I can be working somewhere else, ask something related to it, and Codex can find the old note without me remembering which conversation the information originally came from.

I also want it to gradually inspect my existing Codex projects and fill in the missing pieces of the brain. Project relationships, architecture, important conventions, decisions, common problems, all the stuff currently scattered between repositories, AGENTS.md files, old chats, and my own memory.

There is obviously a danger of overengineering this.

I am, after all, building a knowledge management system so that my AI coding agent can remember things about my other knowledge management systems.

Which is saying something coming from a software engineer.

But I think the mental model is actually pretty simple now:

Repos contain the code. AGENTS.md tells Codex how to behave. Obsidian stores the knowledge that should survive across repos.

The part I am working towards next is making that loop automatic enough that I don't have to remember to maintain it.

Because if maintaining my second brain requires me to constantly remember to update my second brain, I already know how that is going to end.

Add a concrete setup exampleShow how updates actually flow