agent-vault

Own your coding-agent memory.

agent-vault is a dead-simple, markdown-first memory engine for AI coding tools. It keeps one canonical vault in plain files you can read, edit, version, fork, and sync yourself, then exports that memory into the formats different tools already understand:

• AGENTS.md
• CLAUDE.md
• GEMINI.md
• CODEX.md

No hosted backend. No vector database. No mandatory MCP server. No provider lock-in.

If you like Obsidian-style ownership, local markdown, and git as your source of truth, this is the model.

Why This Exists

Most agent tools push you toward one of two bad options:

• keep memory trapped inside one provider's format
• adopt a heavier memory runtime with servers, hooks, storage layers, and retrieval infrastructure

Sometimes you do want the heavier runtime. But a lot of developers just want:

• one place to keep durable agent memory
• plain markdown files they fully own
• git history and backups
• a way to switch between Claude, Codex, Gemini, OpenCode, and future tools
• a quick way to rebuild a new machine

That is what agent-vault is for.

Core Idea

Treat memory like notes, not infrastructure.

Your vault is just a folder of markdown files plus a small registry. You can:

• browse it in Obsidian
• edit it in VS Code
• diff it in git
• sync it through GitHub or GitLab
• fork it and customize the structure however you want

agent-vault then projects that vault into agent-native files in your projects.

Install

npm install -g @typosbro/agent-vault

Quick Start

Create a vault, scan your project folders, sync provider files, and install shell wrappers:

agent-vault init \
  --vault ~/agent-vault \
  --scan ~/code \
  --scan ~/work \
  --mode authoritative

This will:

• create a canonical markdown vault
• discover git repos under the scanned folders
• create per-project memory files in the vault
• render provider-facing memory files into project roots
• install shell wrappers for claude, codex, gemini, and opencode

What You Get

After init, your vault looks like this:

agent-vault/
├── agent-vault.config.json
├── registry.json
├── shared/
│   └── MEMORY.md
├── projects/
│   ├── my-app/
│   │   ├── MEMORY.md
│   │   └── AGENT.md
│   └── api/
│       ├── MEMORY.md
│       └── AGENT.md
└── agent-vault.hook.sh

Each project keeps its durable memory as markdown in the vault. agent-vault then writes the exported agent-facing files into each repo.

Philosophy

Markdown First

Everything important lives in plain files.

You should be able to:

• open your memory in Obsidian
• grep it
• rename things by hand
• move notes around
• fork the repo and change the conventions

If you ever stop using this tool, your data is still just markdown.

Git Is the Database

For a lot of personal and small-team workflows, git is enough:

• history
• backups
• review
• sync across machines
• branch experiments

That is the default model here.

Provider Neutral

Your memory should outlive whichever coding agent is popular this year.

The vault is canonical. Providers get exports.

Simple by Default

No daemon. No cloud account. No retrieval benchmark arms race. No hidden state as the default path.

If you want richer retrieval later, you can add it. But ownership and portability come first.

Commands

agent-vault init

Initialize a vault and optionally discover projects.

agent-vault init --vault ~/agent-vault --scan ~/code --scan ~/work

agent-vault discover

Traverse one or more parent folders and register git repos.

agent-vault discover --vault ~/agent-vault ~/code ~/work

agent-vault register

Register the current project or a specific path.

agent-vault register --vault ~/agent-vault --path .

agent-vault sync

Render provider-facing memory files into every registered project.

agent-vault sync --vault ~/agent-vault

agent-vault hook install

Install shell wrappers so launching supported CLIs auto-registers the current project.

agent-vault hook install --vault ~/agent-vault --shell zsh

Current Behavior

• The vault is the source of truth.
• Sync is authoritative: existing AGENTS.md, CLAUDE.md, GEMINI.md, and CODEX.md are backed up and replaced.
• Files are copied rather than symlinked for better cross-platform behavior.
• Discovery is git-root aware.

Dead-Simple by Design

This project is intentionally opinionated:

• keep memory in markdown
• keep structure understandable
• make machine setup easy
• avoid provider-specific lock-in
• prefer transparency over cleverness

You should be able to explain how it works in one sentence:

Keep one markdown vault, export it everywhere.

Why Not agentmemory / memories.sh / KnowIt?

Those are serious projects, but they solve a somewhat different problem.

agentmemory

rohitg00/agentmemory is a full memory runtime:

• MCP server
• auto-capture hooks
• hybrid retrieval
• viewer
• API surface
• replay/import pipeline

If you want a memory backend and runtime, it is a strong option.

agent-vault is different:

• not a runtime-first product
• not a retrieval engine
• not a server by default
• not trying to be the smartest memory system

It is a source-of-truth and portability layer.

memories.sh

memories.sh is closer in spirit because it also generates agent-native outputs for many tools.

The difference here is the default mental model:

• memories.sh is a broader memory platform with generation and MCP-oriented flows
• agent-vault is deliberately narrower: local markdown vault first, simple exports second

If your priority is maximum feature coverage, look there. If your priority is "I own a folder of notes and can fork the whole system," this project is a better fit.

KnowIt

KnowIt focuses on shared team memory with structured knowledge and MCP-native workflows.

That is useful when you want a more managed shared-memory system.

agent-vault is more bare-metal:

• markdown files
• git workflow
• easy for individuals and small teams
• minimal infrastructure assumptions

When to Use This

Use agent-vault if:

• you want to own your memory as files
• you want git as the source of truth
• you want easy migration between tools
• you want to keep the system simple enough to fork
• you like Obsidian-style knowledge organization

You may want a different tool if:

• you need semantic retrieval out of the box
• you want automatic tool-use capture from every session
• you want a shared server-backed team memory system
• you want dashboards, viewers, or query APIs as the primary interface

Roadmap Direction

The long-term direction is still simple:

• better import from existing CLAUDE.md / AGENTS.md / GEMINI.md
• better project discovery and machine bootstrap
• more provider adapters
• cleaner vault conventions
• optional richer features without breaking the markdown-first core

License

MIT