agent-mem-vault

Memory your coding agents share, and you can read, link and fix in Obsidian.

agent-mem-vault is an MCP server that turns an
Obsidian vault into the long-term memory of your coding agents. Claude Code,
Codex and any other MCP client record decisions, risks and project snapshots as notes in the vault,
and keep two short cards per project: what the last session did, and which work threads are open.
They read them back in the next session, in the next tool, on the next day. You see the same memory
in Obsidian, and you can correct it there.

flowchart LR
    CC["Claude Code"] <-->|"MCP, stdio"| S["agent-mem-vault<br/>MCP server"]
    CX["Codex"] <-->|"MCP, stdio"| S
    AN["Any MCP client"] <-->|"MCP, stdio"| S
    S <-->|"read, atomic write"| V[("Obsidian vault<br/>one Markdown note per record")]
    V --- O["Obsidian<br/>graph, backlinks, Bases dashboard"]
    V -.->|"optional autocommit"| G["git history"]
    Y(("You")) -->|"read and edit notes"| O

Try it in 60 seconds

The repository ships a demo vault with synthetic records for two fictional projects: decisions
with a supersedes chain, a rejected idea, open risks, snapshots, companion cards with open threads,
hub notes and the dashboard. You need uv and, to see the graph,
Obsidian.

git clone https://github.com/kursatdinc/agent-mem-vault && cd agent-mem-vault
export AGENT_MEM_VAULT_VAULT="$PWD/examples/demo-vault"

uv run agent-mem-vault doctor                                    # 10 records, 0 issues
uv run agent-mem-vault list --namespace project/harbor-api --kind decision
uv run agent-mem-vault search "backfill" --namespace project/harbor-api

Then in Obsidian choose Open folder as vault and pick examples/demo-vault. Open the graph
view to see the decision chain, _dashboards/memory.base for the active decisions and risks, and
project-harbor-api/_companion/ for the open threads. Edit a note, run doctor again, and the
change is picked up.

Install

You need uv and an Obsidian vault (create one in Obsidian, for example
~/agent-memory; running git init inside it is optional).

Claude Code:

claude mcp add agent-mem-vault -s user \
  --env AGENT_MEM_VAULT_VAULT="$HOME/agent-memory" \
  -- uvx agent-mem-vault

Codex (~/.codex/config.toml):

[mcp_servers.agent-mem-vault]
command = "uvx"
args = ["agent-mem-vault"]
env = { AGENT_MEM_VAULT_VAULT = "/Users/you/agent-memory" }

Check the setup:

AGENT_MEM_VAULT_VAULT="$HOME/agent-memory" uvx agent-mem-vault doctor

To run the development version straight from GitHub, replace uvx agent-mem-vault with
uvx --from git+https://github.com/kursatdinc/agent-mem-vault agent-mem-vault.

Then ask your agent to "record this decision", "what did the last session leave open?" or "what are
the open risks in this project?". It uses the tools below. More snippets are in examples/.

Why

• Agents forget. Every new session starts cold, and the reasoning behind yesterday's choice
  is gone.
• Agents don't talk to each other. What Claude Code decided is invisible to Codex, and the
  other way round.
• Agent memory is a black box. It hides in JSON files or databases you can't read, review or
  fix. A wrong "memory" quietly steers every later session.

What you get

One memory for all your agents.

• Claude Code and Codex read and write the same records.
• Every session starts from the same brief: the last-session card, the open threads, the latest
  snapshot and what was decided since.
• Open work is one line per thread (- <branch or topic>: <status>; next: <step>), removed when
  the thread is done, so the list stays short instead of growing into a pile.

Memory that stays current.

• Decisions are accepted or superseded; risks are open, mitigated or resolved.
• Superseding a record closes it, and the brief says Consolidation due when the latest snapshot
  is more than a week old.

Memory you can see.

• Every record is a note in your vault.
• Obsidian's graph shows how decisions supersede each other and which records belong to which
  project.
• A generated Bases dashboard lists the active decisions and risks.

Memory you can correct.

• Edit a note in Obsidian and the next query sees it.
• Mark a decision rejected, with a reason, and it stops steering agents but stays on record.
• Mark a record private and it stays out of automatic context.

Typed, not a transcript dump. Records are decision, risk, snapshot, note, assumption
and task, plus optional receipt. Agents can therefore ask precise questions: "open risks in this
project", "what did we decide about caching", "what is still open".

Yours. Memory is plain Markdown in a folder you own. Put the vault in git and you get a full
audit trail for free. Everything works offline, and Obsidian does not need to be open.

How it compares

Notes: the other columns summarize each project's public README; check their docs for current
behavior. The Obsidian-plugin servers offer broader vault access (live metadata, the active file,
the command palette) than this project, which is narrowly a memory store. Embedding services find
related memories by meaning, while this project matches stemmed keywords in titles, aliases, content and tags.

Tools

• Records are grouped by namespace. Without one, a call uses project/<git root name> of the
  directory the server runs in.
• Every listing line ends with id <8 characters>, and every id parameter takes that prefix.
• Free-text search is stemmed, so "caching" finds "cache" and "cached". Search and listings leave
  out superseded and resolved records unless include_closed is passed.
• Memory content is written in English.

Every parameter is documented in the
tools reference.

How it looks

agent-memory/                         # your Obsidian vault
├── project-harbor-api/
│   ├── project-harbor-api.md         # generated hub: the records, the cards and the dashboard
│   ├── _companion/last-session.md    # what the last session did, what is unverified, next step
│   ├── _companion/threads.md         # one line per open work thread
│   ├── decision/2026-03-06-move-order-storage-to-postgresql-234bc139.md
│   └── risk/2026-03-08-migration-script-locks-the-orders-table-728f9c30.md
├── project-lantern-mobile/
│   └── ...
└── _dashboards/memory.base           # active decisions and risks, all records

---
id: 234bc139-823f-5c1c-b7bb-d37ea1c3ee3c
kind: decision
namespace: project/harbor-api
agent: claude-code
title: Move order storage to PostgreSQL
created: 2026-03-06T09:01:00Z
updated: 2026-03-08T09:02:00Z
revision: 2
visibility: internal
validity: valid
tags: [storage]
status: superseded
supersedes: ['[[project-harbor-api/decision/2026-03-02-use-sqlite-for-the-first-release-d61740a1]]']
superseded_by: '[[project-harbor-api/decision/2026-03-08-pin-postgresql-16-in-ci-and-production-eb0b3836]]'
agent-written: true
---
The pilot grew to three workers, which SQLite cannot serve safely. PostgreSQL gives concurrent writers and point-in-time recovery.

<!-- avm:related:start -->
## Related
- Supersedes [[project-harbor-api/decision/2026-03-02-use-sqlite-for-the-first-release-d61740a1|Use SQLite for the first release]]
- Superseded by [[project-harbor-api/decision/2026-03-08-pin-postgresql-16-in-ci-and-production-eb0b3836|Pin PostgreSQL 16 in CI and production]]
<!-- avm:related:end -->

Configuration

~/.config/agent-mem-vault/config.yaml. Every key is optional, and environment variables win.
A copy with comments is in examples/config.yaml.

vault: ~/agent-memory              # or AGENT_MEM_VAULT_VAULT
default_namespace: default         # outside a git repo; or AGENT_MEM_VAULT_DEFAULT_NAMESPACE
redact_secrets: true               # or AGENT_MEM_VAULT_REDACT_SECRETS
features:
  visibility: true                 # private records stay out of automatic context
  receipts: false                  # immutable records of finished work, with file/commit refs
  companion: true                  # per-project "last session" and "open threads" cards
  hooks: false                     # session-start brief and stop nudge for Claude Code / Codex
  git_autocommit: false            # commit every change, fast-forwarding to the upstream first (never pushes)
companion:
  max_chars: 3000

With hooks on, agent-mem-vault hook print-config --client claude|codex prints the snippet
to add to your client settings. The hook command must be on your PATH: run
uv tool install agent-mem-vault once. The server never edits client settings itself.

Upgrading from 1.x

2.0 removes handoffs. Run agent-mem-vault migrate --dry-run, then agent-mem-vault migrate --apply
to move the old handoff notes to <project>/_archive/handoffs/, and re-register the hooks with
hook print-config. The full list of changes and steps is in the
changelog.

Guarantees

• No lost writes. Two agents writing at once are serialized by a file lock, and every file is
  replaced atomically.
• No silent overwrites. Updates check the record's revision. A note you edited by hand is
  never overwritten; the agent gets a conflict and re-reads.
• Broken notes are reported, not dropped. A note with invalid frontmatter shows up in
  list_issues and doctor, untouched.
• Hands off your setup. It never writes .obsidian/, never launches Obsidian, never pushes
  git and makes no network calls.
• Secrets stay out. Token, key and password patterns are redacted before anything is
  written.

Documentation

• Wiki: getting started, configuration, tools
  reference, record format, memory model, Obsidian integration, FAQ.
• docs/DESIGN.md: the design contract the implementation follows.
• CHANGELOG.md and docs/RELEASING.md.
• Discussions for questions and ideas,
  Issues for bugs.

Development

uv sync
uv run ruff check
uv run pytest -q

Requires Python 3.12+ on macOS or Linux; file locking uses fcntl, so Windows is not supported
yet. See CONTRIBUTING.md. Releases follow docs/RELEASING.md.

Star History

License

MIT © 2026 Kürşat Dinç