Skip to content

← agentcairn

agentcairn for Hermes Agent

agentcairn is a native Hermes Agent MemoryProvider: durable, local-first memory for Hermes, backed by your own plain-Markdown vault — the same vault your Claude Code, Codex, and Cursor agents already use.

Why it's different

It is the only Hermes memory provider that is vault-native and human-editable. Memories are plain Markdown files with YAML frontmatter and [[wikilinks]] — open them in Obsidian, fix a wrong fact by hand, drop in your own notes, and the agent picks it all up on the next session. The vault is the source of truth, not a one-way export from a database.

  • Local-first by default. No cloud account, no network call, no always-on server. The only storage is files on your disk.
  • Own your data. Apache-2.0, plain Markdown, nothing trapped in a proprietary store — your memory survives a model upgrade, an index rebuild, or uninstalling the tool.
  • One brain across agents. It writes to the same CAIRN_VAULT as the Claude Code, Codex, and Cursor plugins, so memory follows you across tools instead of fragmenting per-agent.
  • Secret-redacted, non-lossy. Regex + entropy + URL-credential redaction runs before any text reaches the vault, and distillation only adds derived notes — it never drops a fact.

How it works

agentcairn hooks into the Hermes memory lifecycle so recall and capture happen automatically, with explicit tools for curated operations:

  • Auto-recall every turn. At the start of each turn (prefetch), agentcairn runs a hybrid BM25 + semantic vector recall against your vault and injects the relevant memories into context.
  • Session-end distill. Turns are buffered with no I/O on the hot path, then distilled into durable vault notes on a daemon thread when the session ends — the same importance gate and redaction pipeline as agentcairn's normal capture.
  • Curated tools. memory_save, memory_recall, and memory_search are exposed as Hermes tools for on-demand, agent-driven memory operations.

Install

The provider ships in integrations/hermes/. Install agentcairn into Hermes's Python environment, copy the plugin into your Hermes plugins directory, and register it: 

pip install agentcairn
cp -r integrations/hermes ~/.hermes/plugins/memory/agentcairn
hermes memory setup agentcairn

All config keys are optional. By default it uses ~/agentcairn (or $CAIRN_VAULT), local FastEmbed embeddings, and no secrets. For higher recall quality, set CAIRN_EMBEDDER=voyage (requires VOYAGE_API_KEY) or CAIRN_EMBEDDER=openai (requires OPENAI_API_KEY) — these are opt-in cloud tiers; with either enabled, note text and recall queries leave your machine. See the integration README for the full config table.

What is agent memory? · Read your memory in Obsidian · How agentcairn compares

FAQ

What is the agentcairn Hermes memory provider?

It is an agentcairn plugin that implements the Hermes MemoryProvider API, giving Hermes Agent durable memory backed by your own plain-Markdown Obsidian vault — local-first, with the files as the source of truth rather than a cloud database.

Does Hermes memory share a vault with my other agents?

Yes. It writes to the same CAIRN_VAULT used by the Claude Code, Codex, and Cursor plugins, so a fact your Hermes agent learns is recalled by your other agents, and vice versa — one unified brain across every tool.

How do I install agentcairn into Hermes?

Install agentcairn into Hermes's Python environment (pip install agentcairn), copy integrations/hermes into ~/.hermes/plugins/memory/agentcairn, then run `hermes memory setup agentcairn`. All config keys are optional and default to a local, no-key setup.

Does the Hermes provider need a cloud API key?

No. Storage is local files, embeddings run locally via FastEmbed by default, and session-end capture uses agentcairn's local extractive distiller — no API key required. An optional Anthropic judge applies only to the separate `cairn sweep` CLI path over the shared vault. Two opt-in cloud embedders (`CAIRN_EMBEDDER=voyage` or `=openai`) are available for higher recall quality; with either enabled, note text and recall queries are sent to the provider.

What happens if memory capture fails during a Hermes session?

Capture is fail-safe: an error during session-end logs a warning to stderr and is silently dropped. It never raises into Hermes, so a capture problem can't crash your agent.

Get started

Install agentcairn into your agent in one command:

cairn install --all

GitHub · Full quickstart