# ccf/agentcairn [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/ccf/agentcairn  
**GitHub Stars:** 75  
**Views:** 12  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ccf-agentcairn

## Description
Local-first agent memory: a plain-Markdown Obsidian vault is the source of truth, with a rebuildable DuckDB index for hybrid BM25 + vector + graph recall. Non-lossy capture with secret redaction; works across Claude Code, Codex, Cursor, and any MCP host. uvx agentcairn

## Tools
Capabilities this server exposes over MCP:

- **search** — Hybrid search over memory; returns a compact id+snippet index.
        Reranks by default (set CAIRN_RERANK=0 to disable, or pass rerank=false).
        Recall prefers your current project's memories (boosted, non-lossy): pass
        `project` (a repo name) to target another project, else the server's working
        directory is used. `scope="project"` hard-limits results to that project.
- **recall** — Search then hydrate the top-k notes' full text.
        Reranks by default (set CAIRN_RERANK=0 to disable, or pass rerank=false).
        Recall prefers your current project's memories (boosted, non-lossy): pass
        `project` (a repo name) to target another project, else the server's working
        directory is used. `scope="project"` hard-limits results to that project.
- **build_context** — Return a note plus its 1-hop linked neighbors.
- **recent** — List the most-recently-modified notes.
- **remember** — Persist a distilled memory (redacted, non-lossy) into the vault.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "agentcairn": {
    "command": "uvx",
    "args": ["agentcairn"]
  }
}
```

## Documentation

## What ccf/agentcairn MCP server does

The ccf/agentcairn MCP server provides durable memory for coding agents. It stores canonical notes as Markdown files in a local vault, while DuckDB holds a disposable index for retrieval. The vault can be inspected and edited directly, including through the companion Obsidian integration, so the stored memory is not confined to a hosted service or an opaque database.

The server supports two central memory operations: recalling relevant context and remembering a durable fact. A successful remember operation writes the Markdown note and updates the index together, making the note available to a subsequent recall. Recall results include context such as project association, validity state, and a permalink.

## How it works

AgentCairn can receive context through host integrations and transcript ingestion. Capture applies credential redaction, deduplication, importance gating, and distillation before automated plaintext writes. Host hooks improve immediate capture, while `cairn sweep` provides an out-of-band backstop for supported transcript stores.

On read, the server reconciles the vault with its DuckDB cache. Retrieval combines BM25 text search and semantic vectors using Reciprocal Rank Fusion, with optional reranking. If an embedding or reranking model fails, the system can fall back to BM25 and report diagnostics rather than using incompatible vectors.

The current project receives a default ranking boost, while cross-project memories remain available and labeled. Validity fields such as `valid_from`, `valid_until`, and `superseded_by` keep older evidence inspectable while favoring current information. Markdown wikilinks and optional `cairn link` neighbors provide deterministic graph context.

## Setup and configuration

The ccf/agentcairn MCP server can run through `uvx agentcairn`; the documented default vault is `~/agentcairn`, created on first use. Install `uv` first if `uvx` is unavailable. The server uses stdio, does not require a daemon or external database, and runs FastEmbed locally by default. The first local run may download and warm embedding or reranking models.

Claude Code and Codex have first-class plugin installation commands that bundle the MCP server, memory skill, and host-specific hooks. Cursor, VS Code with Copilot, Claude Desktop, and other supported hosts can be configured with `cairn install` or the portable MCP command. Installation previews detected hosts, backs up MCP configuration before changes, and preserves unrelated server entries.

No environment variables are required by the documented default setup. The vault is the durable store; the DuckDB index is rebuildable and can be deleted without deleting the Markdown files.

## Tools and capabilities

The ccf/agentcairn MCP server exposes memory recall and durable remember operations for connected agents. Its surrounding capabilities include:

- Store durable context as Markdown with provenance.
- Recall using lexical, vector, and graph-related signals.
- Redact recognized credentials before automated writes.
- Preserve superseded and expired notes instead of silently deleting them.
- Share one configured vault across supported coding agents.
- Return project, validity, and permalink context with recalled results.
- Reconcile a disposable DuckDB cache from the canonical files.

Supported integrations listed by the project include Claude Code, Codex, Cursor, OpenCode, Hermes Agent, Antigravity, VS Code with Copilot, and Claude Desktop. Other MCP hosts can use the portable stdio server, subject to host-specific integration behavior.

## Limitations and notes

The server does not provide useful recall from an empty vault; a durable fact must be saved first. Automatic recall and capture vary by host. Claude Code and Codex provide documented ambient hooks, Cursor uses out-of-band sweep, and some hosts expose only the MCP server. The index is a cache rather than the source of truth, so direct Markdown edits are honored during reconciliation.

Model downloads may occur during the first local run. Retrieval quality depends on the available local models and can fall back to BM25 when model or provider operations fail. Automatic recall is project-scoped by default, although explicit cross-project results remain possible. The repository is licensed under Apache-2.0.

_Full upstream README: https://allmcps.com/mcp/ccf-agentcairn/readme_