How to Set Up Persistent Memory for Codex Using Obsidian (3 Approaches)

Codex has no long-term memory. Every session starts clean. You explain your project structure, your naming conventions, your testing preferences, the thing you decided last Tuesday about the API design. Then you close the terminal and do it all over again tomorrow.

The fix is giving Codex a memory layer that persists between sessions. And the best place to store that memory is Obsidian, because it's just markdown files on disk. No proprietary database. No sync service you don't control. Every note is a plain text file you can read, edit, search, and version control yourself.

I tested three different approaches to wiring Codex memory into Obsidian. Each one solves the problem differently, and the right pick depends on how much setup you want to deal with and how deep you want the integration to go.

Here's every approach, what it actually does, and how to set it up from scratch.

First: Understanding How Codex Memory Actually Works

Before wiring anything to Obsidian, you need to understand the two memory layers Codex already has built in.

Layer 1: AGENTS.md (Static Instructions)

This is a markdown file you place at the root of your repo. Codex reads it at the start of every session before doing any work. Think of it as a briefing document. You put your project conventions, testing commands, directory layout, and anything the agent needs to know every single time.

AGENTS.md is checked into version control. It's shared across the team. It's the right place for rules that should always apply.

Quick example of what goes in here:

# AGENTS.md

## Project
- Next.js 14 app with TypeScript
- Tailwind for styling, no CSS modules
- All API routes live in /app/api/

## Testing
- Run `pnpm test` before committing
- All new functions need at least one unit test
- Test files go next to the source file, named *.test.ts

## Conventions
- Use kebab-case for file names
- Commit messages follow Conventional Commits: feat(scope): description
- Never modify files in /config/production/

Codex loads this automatically. No config needed. Just create the file.

You can also run /init inside a Codex session, and it will scaffold an AGENTS.md based on your project's detected tech stack, directory structure, and config files. Good starting point if you don't want to write it from scratch.

One thing to watch: Codex concatenates AGENTS.md files from the repo root down to your current directory, and stops at 32 KiB combined size. If your instructions are being ignored, you might be hitting the size limit. You can verify by asking Codex: "Summarize the instructions you have loaded for this session."

Layer 2: Native Memories (Auto-Generated)

This is the newer system. When enabled, Codex automatically summarizes your sessions in the background and writes those summaries to ~/.codex/memories/. The next time you start a session, it reads those summaries back in. You don't paste anything. You don't reference anything. The context just shows up.

The memory pipeline works in two phases. Phase 1 runs after a session has been idle long enough (six hours by default, configurable via min_rollout_idle_hours from 1 to 48). It extracts key context from the conversation, redacts any secrets it finds, and stores a structured summary. Phase 2 periodically consolidates all those individual summaries into a unified memory file that gets injected into future sessions.

The storage layout under ~/.codex/memories/:

~/.codex/memories/
├── memory_summary.md      # High-level summary injected into every session
├── MEMORY.md              # Searchable registry of aggregated insights
├── raw_memories.md        # Temporary merge used during consolidation
├── rollout_summaries/     # Per-thread recaps with lessons learned
└── skills/                # Reusable procedures the agent discovered

To enable it:

# ~/.codex/config.toml
[features]
memories = true

Or as a one-time CLI override: codex -c features.memories=true

Or in the Codex app: Settings > Memories > Enable.

Once it's on, you can fine-tune the behavior:

[memories]
generate_memories = true    # Let new threads create memory entries
use_memories = true         # Inject existing memories into new sessions

You can also run these independently. Want Codex to read old memories but not generate new ones? Set generate_memories = false and use_memories = true. Useful for debugging or when you want to freeze the memory state.

Inside a running session, type /memories to control whether that specific thread can use or generate memories. This doesn't touch your global settings.

Important caveat: Native memories are off by default and currently unavailable in the EEA, UK, or Switzerland. Also, memories are per-user. If your team shares a Codex environment, individual memories don't pool across teammates. Team-wide context belongs in AGENTS.md.

Where Obsidian Comes In

The two layers above work, but they have limits. AGENTS.md is static and manual. Native memories are auto-generated but opaque and not easily searchable. Obsidian gives you a visual, organized, searchable knowledge base that your agent can read from and write to. And because Obsidian is just a folder of markdown files, it plays nicely with every tool in the chain.

Approach 1: Basic Memory + MCP (Easiest Setup, Cross-Tool Compatible)

This is the fastest path to persistent Codex memory that syncs with Obsidian.

Basic Memory is an MCP server that gives any AI tool (Codex, Claude Code, Cursor, Claude Desktop) persistent context through plain markdown files. You store notes in a folder. Basic Memory indexes them. Codex queries them through MCP. And because the storage format is just markdown, you point Obsidian at the same folder and everything shows up in your vault with full graph view, backlinks, and search.

What this looks like in practice

You're three weeks into building an API. You've made decisions about auth strategy, database schema, rate limiting approach, error handling patterns. All of that context lives in Basic Memory notes.

You open a new Codex session and say: "What decisions have we made about the API design? Check my notes."

Codex uses semantic search through MCP, finds the relevant notes across your project, and answers grounded in your actual project history. No re-explaining. No pasting old conversations.

You switch to Claude Code for a different task on the same project. Same notes. Same context. Zero re-setup.

Setup (Local)

codex mcp add basic-memory bash -c "uvx basic-memory mcp"

That's the entire install. One command. The uvx approach handles dependency resolution automatically and runs Basic Memory as a child process.

To scope it to a specific project:

codex mcp add basic-memory bash -c "uvx basic-memory mcp --project your-project-name"

Verify it's connected:

codex mcp list

You should see basic-memory listed.

Setup (Cloud, for remote access)

If you want cloud-hosted memory:

1. Create an API key at app.basicmemory.com under Settings > API Keys

2. Add it to your shell profile:

echo 'export BASIC_MEMORY_API_KEY=your-key-here' >> ~/.zshrc
source ~/.zshrc

3. Add to your Codex config:

# ~/.codex/config.toml
[mcp_servers.basic-memory]
url = "https://cloud.basicmemory.com/mcp"
bearer_token_env_var = "BASIC_MEMORY_API_KEY"

Connecting Obsidian

Open Obsidian. Create a new vault. Point it at your Basic Memory directory (~/basic-memory by default, or your project folder). That's it. The same markdown files your AI writes show up in Obsidian with graph view, backlinks, and rich editing. No import or export step.

Notes you create in Obsidian are immediately available to Codex. Notes Codex creates show up in Obsidian. Same files, two interfaces.

When to use this approach

You want the fastest setup, you use multiple AI tools (not just Codex), and you want your memory notes to be plain markdown you can browse and edit in Obsidian.

Approach 2: Structured Obsidian Vault with AGENTS.md + Codex Hooks (Deepest Integration)

This is the power-user option. Instead of a third-party memory layer, you build a structured Obsidian vault that Codex reads directly through AGENTS.md and lifecycle hooks.

The idea is simple: your Obsidian vault becomes your project's knowledge base. AGENTS.md tells Codex how the vault is organized, what the naming conventions are, and where to find things. Codex hooks automatically inject context from the vault at session start so you never have to re-explain what's going on.

Where Basic Memory gives you a shared note store through MCP, this approach gives you full control with zero external dependencies. Everything stays in your vault, everything is plain markdown, and Codex reads it natively.

What this looks like in practice

You open the terminal in your vault directory and run Codex. The SessionStart hook fires automatically, reads your vault's index file, and injects a summary of active projects, recent decisions, and open tasks into the session. Codex knows what's going on before you type a single word.

You say: "What did we decide about the caching strategy last week?" Codex reads the decision records in your vault and pulls the answer from your own notes.

During the day, every note you create gets filed with YAML frontmatter, tagged, and linked. Decision records, project notes, architecture docs. Codex follows the structure defined in AGENTS.md and files things consistently.

The vault structure

projects/          # One folder per active project
decisions/         # Architecture and design decision records
memory/            # Persistent context Codex reads across sessions
memory/goals.md    # Current priorities and focus areas
memory/index.md    # Map of everything in the vault
templates/         # Note templates with YAML frontmatter
reference/         # Codebase knowledge, API docs, architecture maps

Step 1: Create AGENTS.md at the vault root

This is Codex's operating manual for your vault. Here's a practical example:

# AGENTS.md

## Vault Structure
- /projects/ contains one folder per active project
- /decisions/ contains architecture decision records (ADR format)
- /memory/goals.md has current priorities. Read this first every session.
- /memory/index.md is the vault map. Scan it to know what exists.

## Note Conventions
- All notes use YAML frontmatter with: title, date, status, tags
- Status values: active, completed, archived, deprecated
- File names use kebab-case: my-decision-about-caching.md
- Link related notes using [[wikilinks]]

## When Creating Notes
- Decision records go in /decisions/ with ADR format
- Project notes go in /projects/{project-name}/
- Always update /memory/index.md when creating new notes

## When Starting a Session
- Read /memory/goals.md for current priorities
- Check /memory/index.md for vault overview
- Look at recent git commits to see what changed since last session

Step 2: Set up the SessionStart hook

Codex hooks let you run scripts at specific lifecycle events. The SessionStart event fires when a session begins and can inject context automatically.

Hooks are experimental and currently disabled on Windows. You need to enable the feature flag first:

# ~/.codex/config.toml
[features]
codex_hooks = true

Then create .codex/hooks.json in your vault:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "cat memory/goals.md memory/index.md",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

The structure is: event name as a key, then an array of matcher groups, each containing a matcher regex and a hooks array. For SessionStart, the matcher filters on how the session started (startup or resume). The timeout is in seconds (default is 600 if omitted). Any plain text the command writes to stdout gets injected as developer context into the session.

This reads your goals and vault index, then injects them as context at the start of every Codex session. Codex sees this before you type a single word.

You can make the hook smarter. A script that pulls recent git changes, scans for notes modified in the last 48 hours, and builds a compact briefing:

#!/bin/bash
# .codex/session-start.sh
echo "## Current Goals"
cat memory/goals.md
echo ""
echo "## Recently Modified Notes"
find . -name "*.md" -mtime -2 -not -path "./.codex/*" | head -20
echo ""
echo "## Recent Changes"
git log --oneline -10 2>/dev/null || echo "No git history"

Then update the hook to point to the script:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "bash .codex/session-start.sh",
            "timeout": 10,
            "statusMessage": "Loading vault context"
          }
        ]
      }
    ]
  }
}

Step 3: Open the vault in Obsidian

Open the same folder as an Obsidian vault. You get graph view across all your notes, backlinks between decisions and projects, full-text search, and a visual interface for browsing everything Codex writes. Same files, two interfaces.

Step 4: Run Codex from the vault directory

cd ~/your-vault && codex

Codex loads AGENTS.md, the SessionStart hook fires and injects your goals and index, and you're working with full context from the first prompt.

What sets this apart from the other approaches

No external tools. No MCP servers. No API keys. Everything is AGENTS.md (instructions), hooks (automation), and markdown files (knowledge). The vault is fully portable. You can version control it with git, sync it however you want, and switch to a different agent later without rebuilding anything. A well-documented vault in markdown is not locked to any single AI tool.

When to use this approach

You want Obsidian as the center of your workflow with zero external dependencies. You want to control exactly what Codex sees and how the vault is organized. You're comfortable writing an AGENTS.md and a simple hook script.

Approach 3: Native Memories + Manual Obsidian Sync (Minimal Setup, Good Enough for Most)

If you don't want to install anything extra, you can use Codex's built-in memory system and just point Obsidian at the memory folder.

This is the simplest approach. Enable native memories, let Codex auto-generate summaries, and open ~/.codex/memories/ as an Obsidian vault (or add it as a folder inside an existing vault). You get visual browsing and search over everything Codex remembers.

The tradeoff: this is read-only from Obsidian's perspective. You can look at the memory files, but hand-editing them isn't the supported path. Codex treats ~/.codex/memories/ as generated state that it manages itself. If you want to give Codex persistent instructions, put them in AGENTS.md instead.

Setup

1. Enable memories:

# ~/.codex/config.toml
[features]
memories = true

2. Open ~/.codex/memories/ as an Obsidian vault, or symlink it into an existing vault:

ln -s ~/.codex/memories/ ~/your-vault/codex-memories

3. Work normally. After sessions go idle (six hours by default), Codex processes them in the background. Summaries appear in the folder. Obsidian picks them up automatically.

What this looks like in practice

You've been using Codex on a project for two weeks. You open the codex-memories folder in Obsidian and see rollout summaries for each session, a consolidated memory summary, and any skills the agent discovered. You can search across all of them, see patterns in your workflow, and spot context that Codex is carrying forward.

When you start a new Codex session, the agent reads memory_summary.md (capped at 5,000 tokens to preserve context window) and has access to the rest of the memories folder if it needs deeper context.

When to use this approach

You just want Codex to remember things between sessions and you want a way to browse what it remembers. You don't need cross-tool memory sharing or a structured vault system.

Which Approach Should You Pick?

Start with Approach 3 if you just want Codex to stop forgetting things. It takes 30 seconds to enable native memories and one more minute to point Obsidian at the folder.

Move to Approach 1 when you start using multiple AI tools or want your notes to be the source of truth (not Codex's auto-generated summaries). Basic Memory gives you clean two-way sync between your vault and every MCP-compatible tool.

Go with Approach 2 when you want full control with zero external dependencies. AGENTS.md plus a SessionStart hook gives you a self-contained vault that Codex reads natively. No MCP servers, no API keys, just markdown and a hook script.

You can also combine them. I run native memories for auto-capture plus Basic Memory for structured project knowledge that I want searchable across tools. The native layer catches things I forget to document. Basic Memory holds the deliberate notes I want to persist long-term.

Quick Gotchas

A few things that tripped me up during setup.

AGENTS.md vs Memories: Don't rely on memories for rules that must always apply. Memories are a personal recall layer. Put team-wide conventions and project rules in AGENTS.md where they're version controlled and shared.

Memory timing: Codex doesn't generate memories immediately when you close a session. It waits until the thread has been idle long enough (six hours by default). Don't panic when the memories folder doesn't update right away.

Size limits: The memory summary injected into each session is capped at 5,000 tokens. If you're building a massive knowledge base, not everything will make it into every session. The agent can still read deeper into the memories folder when it needs to, but the automatic injection has a ceiling.

Secret redaction: Codex redacts secrets from generated memories, but review your memory files before sharing your ~/.codex directory or committing any memory artifacts. The redaction is good but not perfect.

EEA/UK/Switzerland: Native memories aren't available in these regions yet. Use Approach 1 or 2 instead.

---

If you found the breakdown of Hermes and how it scales from one agent to a full team useful, the architecture behind that post pairs well with this one: I Put an Autonomous AI Agent on My Laptop. It Saved Me 7 Hours in Week One.

---

We cover practical AI agent setups like this twice a week at Web After AI. No hype, just what works and how to set it up.