agent-cabinet

Obsidian is a great tool, and you can even tell agent-cabinet to write into an Obsidian vault instead of its own directory.

There are two main differences.

First, who's writing. Obsidian is built for a person writing by hand, so its frontmatter is freeform: that flexibility is the point. agent-cabinet's frontmatter is structured and schema-validated instead, following the ORC spec for shaping this kind of claim. Nothing else catches a malformed or missing field for an agent writing unsupervised.

Second, Obsidian is an application first. Extending it means writing a plugin that runs inside Obsidian itself, not linking a library into your own service, so another program can't just call into it directly. agent-cabinet is meant to be a dependency that applications build on, not an application in itself.

To see what's stored, you have two options:

• Open the .cabinet directory and read the files directly. Each entry is one .md file with YAML frontmatter. There's no export step, no hidden format, so you can just read it.
• Query it instead: agent-cabinet has built-in ranked search. See agent-cabinet recall "<query>" above.

On init, agent-cabinet finds the project root by walking up from your current directory until it finds .git (or the current directory, if you're not in a git repo yet).

This project root will then hold two new entries:

• .cabinet is a directory built at <project root>/.cabinet.
• AGENTS.md, created if it doesn't exist yet, with a short block telling your agent agent-cabinet is available. This is the file most agents (Cursor, Copilot, Codex, Windsurf, Cline, ...) read natively, so it's the source of truth.
• CLAUDE.md, created if it doesn't exist yet, with a one-line @AGENTS.md import. Claude Code is the one agent that won't otherwise ever load AGENTS.md on its own, so this is what tells it to — a no-op for every other agent.

Want .cabinet somewhere else, like inside an Obsidian vault? Override with --root <path> or the AGENT_CABINET_ROOT environment variable. Note this only moves .cabinet: AGENTS.md/CLAUDE.md always go to the project root found above, regardless of --root.

Promoting a note to a fact is just adding evidence to the same entry: call file() on the same id with evidence/provenance filled in and overwrite=True, and it replaces the note in place. Those fields are optional on file() too, though. What actually makes something a fact is only ever whether they're filled in, not which function wrote the entry.

remember() writes down what you tell it, exactly as told. file() is for a claim something else has already checked, usually a pipeline that computed it and can show its work: a dict with an id, a type, a scope saying where it came from, and the statement itself required, plus optional evidence and provenance fields for showing that work. (This shape is called ORC, short for OpenReasoningComponents, in case you want other tools to read the same files; you don't need to know that name to use any of this.)

Here's the actual file remember("The DB is Postgres, not MySQL.") writes:

---
id: example-project/the_db_is_postgres_not_mysql
type: domain_knowledge
scope: { source: example-project }
---
The DB is Postgres, not MySQL.

And this promotes it in place, once something verifies the claim:

cabinet.file({
    "id": "example-project/the_db_is_postgres_not_mysql",
    "type": "domain_knowledge",
    "scope": {"source": "warehouse-connection-check"},
    "statement": "The DB is Postgres 16.2, confirmed by direct connection.",
    "evidence": {"confirmed_by": "SELECT version() -> PostgreSQL 16.2"},
    "provenance": {"derivation": "check_db_dialect", "derivation_version": "a1b2c3"},
}, overwrite=True)

Which overwrites the file in place to be:

---
id: example-project/the_db_is_postgres_not_mysql
type: domain_knowledge
scope: { source: warehouse-connection-check }
evidence: { confirmed_by: "SELECT version() -> PostgreSQL 16.2" }
provenance: { derivation: check_db_dialect, derivation_version: a1b2c3 }
---
The DB is Postgres 16.2, confirmed by direct connection.

The server is one command: agent-cabinet mcp. As with most local MCP servers, it defaults to stdio. Your client runs the command itself and owns the process, so there's nothing you start or keep running yourself.

Here's how to point common clients at it (all three clients below can already call agent-cabinet remember/recall directly as shell commands once you run agent-cabinet init).

Claude Code

claude mcp add agent-cabinet -- agent-cabinet mcp

Cursor

Add to .cursor/mcp.json:

{ "mcpServers": { "agent-cabinet": { "command": "agent-cabinet", "args": ["mcp"] } } }

Codex CLI

codex mcp add agent-cabinet -- agent-cabinet mcp

Multiple clients

Want one server shared by more than one client, or a client on another machine? agent-cabinet mcp --transport http --port 7879 binds a port instead. You run and keep that one alive yourself; clients point at http://localhost:7879/mcp.

The same remember/recall calls, direct from Python, the way you'd embed agent-cabinet in your own service instead of shelling out:

from agent_cabinet import Cabinet

cabinet = Cabinet("./.cabinet", namespace="example-project")
cabinet.remember("User said the DB is Postgres, not MySQL.", basis="stated")
cabinet.recall("database")[0].body
# 'User said the DB is Postgres, not MySQL.'

--root takes any directory, so pointing it at a folder inside a real vault works as-is:

agent-cabinet init --root ~/MyVault/agent-notes

Every entry is a standard frontmatter Markdown file, so Obsidian shows it as a real note: Properties panel, full-text search, all of it.

Two things worth knowing. relations/links are plain strings (acme/other), not Obsidian's [[wikilink]] syntax, so they won't wire into Obsidian's own graph view or backlinks panel on their own. And hand-editing a note through Obsidian's Properties UI is exactly the kind of edit this is built to tolerate: a required field going missing, or the id property getting retyped, produces a clean error for that one entry rather than breaking recall() for the rest of the cabinet.