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 use it

The provider 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 or always-on server is required. Canonical memory and its derived index stay on your disk with the default configuration.
  • 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.
  • A shared vault across agents. Point Hermes, Claude Code, Codex, Cursor, and other supported hosts at the same CAIRN_VAULT so relevant memory can follow you across tools.
  • Secret-aware automated writes. Recognized credential patterns are redacted before automated writes. Existing history is not silently erased when a newer fact supersedes it.

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/. Hermes can install that repository subdirectory directly, and provider setup installs agentcairn into the same environment:

hermes plugins install ccf/agentcairn/integrations/hermes
hermes memory setup agentcairn

Python compatibility: agentcairn currently requires Python 3.12 or newer. Hermes accepts Python 3.11+, and its managed CLI installer currently provisions 3.11, so that default environment cannot install this provider yet. Run Hermes in a 3.12+ environment before the commands above. Check Hermes’s current installation documentation and the integration README before changing a managed environment.

All config keys are optional. By default it uses ~/agentcairn (or $CAIRN_VAULT), local FastEmbed embeddings, and no secrets. A local Ollama embedder is also supported. Optional cloud embedders and the Anthropic durability judge belong to separate agentcairn CLI workflows; when enabled, remaining redacted text or queries leave your machine. See the integration README linked above 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. Point Hermes and your other supported agents at the same CAIRN_VAULT. Memories written by one host then become available for relevant recall in the others.

How do I install agentcairn into Hermes?

First ensure Hermes is running on Python 3.12 or newer. Then install the repository subdirectory with `hermes plugins install ccf/agentcairn/integrations/hermes` and run `hermes memory setup agentcairn`; setup installs the agentcairn package into that environment. All config keys are optional and default to a local, no-key setup.

Does the Hermes provider need a cloud API key?

No. The default uses local files, FastEmbed, and agentcairn's local extractive distiller. Hermes can also use a local Ollama embedder. Optional cloud features in separate agentcairn workflows are explicit egress and require their provider credentials.

What happens if memory capture fails during a Hermes session?

Capture is fail-safe: a session-end error logs a warning and does not raise into Hermes, so a capture problem does not crash the agent.