# Cairn [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/luckyjackluo/cairn  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cairn-4

## Description
Local-first file-organization tools for your AI agent: tag, query, and digest a folder. No cloud.

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

```json
"mcpServers": {
  "cairn": {
    "command": "uvx",
    "args": ["cairn-mcp-server"]
  }
}
```

## Documentation & README

# Cairn

**A local-first, open-source harness for organizing your files with an AI agent.**

Point Claude Code, Codex, Cursor — any MCP client — at a folder, and your agent
gains a full file-organization toolset: list, read, search, grep, edit, move,
tag, import documents, and semantically retrieve. No account, no cloud, no UI
required. Your files never leave your machine.

```bash
claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes
```

Then ask your agent to *"organize this folder and tag everything"* — it will,
using tools that run locally over your own files.

> A cairn is a stack of stones that marks a trail. This one keeps your files in
> order and shows the way through them.

---

## Quickstart (2 minutes)

If you use **Claude Code**, setup is one command — the only prerequisite is
[`uv`](https://docs.astral.sh/uv/), which provides `uvx`:

```bash
# 1. Install uv if you don't have it (provides uvx)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Add Cairn to Claude Code, pointed at a folder you want organized
claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes
```

Reopen Claude Code and ask:

> *"Organize this folder and tag everything."*

Cairn's tools run locally over your files — reads happen freely, and any
move/rename/edit asks for confirmation first. The first run auto-downloads the
package (~5s); no clone, no build, no account.

> [!TIP]
> Point `--workspace` at a **copy** of some notes for your first run — Cairn can
> move, rename, and edit files.

**Using Codex?** Same one-command flow (then run `/mcp` in a session to confirm):

```bash
codex mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes
```

**Using Cursor or another MCP client?** Same package, JSON config:

```json
{ "mcpServers": { "cairn": { "command": "uvx",
  "args": ["cairn-mcp-server", "--workspace", "~/Documents/notes"] } } }
```

`~` is expanded by Cairn, so `~/Documents/notes` works in the CLI and in config files alike.

**Just want to poke at it, no agent?**

```bash
uvx cairn-cli --workspace ~/Documents/notes tree
```

## Why a harness

The agent-harness ecosystem converged on a clear pattern: the model and the
agent loop are commodities supplied by the client (Claude Code, Codex, OpenCode).
The durable value is **the tools and the local data**. So Cairn ships *tools, not
an agent* — the client provides the loop, the approval prompts (driven by our
tool annotations), and the chat. Cairn is just the local file-organization
toolset that snaps into whatever harness you already use.

## Architecture

Everything is a thin adapter over one standard-library core, so the faces can
never drift.

```
core/          cairn-core — the engine (stdlib only): the .uni document format,
               file operations, tags, retrieval; optional document ingestion
               (docx/pdf/pptx/xlsx/md) and embeddings-based search.
mcp-server/    cairn-mcp-server  — MCP server: 26 tools with read-only/destructive
               annotations, resources, and prompts.        ← the flagship
cli/           cairn-cli  — scriptable CLI, a local HTTP API (`serve`),
               and an `mcp` launcher.
web/           cairn-web  — optional zero-build local web UI
               (browse / edit / view / tag / search).
```

## Use it

**In Claude Code / Codex / Cursor (primary):**

```bash
claude mcp add cairn -- uvx cairn-mcp-server --workspace ~/Documents/notes
# with real-document import: uvx --with "cairn-core[convert]" cairn-mcp-server ...
```

The server exposes read-only tools (list, read, search, grep, retrieve) that the
client runs freely, and destructive tools (move, delete, edit) that it confirms
first — driven by MCP tool annotations, so you get approval prompts with no UI
of ours.

**As a CLI:**

```bash
uvx cairn-cli --workspace ~/Documents/notes tree
uvx cairn-cli --workspace ~/Documents/notes retrieve "budget planning"
```

**With the optional web UI:**

```bash
pip install cairn-cli cairn-web
cairn --workspace ~/Documents/notes serve   # → http://127.0.0.1:4177/
```

## The `.uni` format

A `.uni` file is a small JSON document — `{ uuid, content: "<html>", metadata,
tags }` — with tags stored *in the file*. A workspace is just a directory: fully
portable, no external database. Source documents (docx/pdf/pptx/…) import into
editable `.uni` docs; the originals are kept by default.

## Local-first & bring-your-own-key

- No account, no login, no cloud sync. The filesystem is the source of truth.
- The default retriever is lexical and needs nothing. Embeddings are opt-in and
  bring-your-own-key (any OpenAI-compatible endpoint, including local servers
  like Ollama or LM Studio); vectors live in a local SQLite index under
  `<workspace>/.cairn/` and never leave your machine.

## Roadmap

Cairn is young. Rough direction, and where help is most welcome:

- **More document faces** — richer frontmatter support (nested metadata, dates),
  and round-tripping edits back into imported source formats.
- **Smarter digests** — summaries that use an embedding model when one is
  configured, and saved views (`.cairn/views/*.md`).
- **More retrieval backends** — pluggable rerankers; first-class local-model
  presets (Ollama, LM Studio) beyond the generic OpenAI-compatible path.
- **Editor/agent integrations** — thin recipes for wiring Cairn into common
  MCP clients and note-taking setups.
- **Packaging** — signed releases and a Homebrew formula.

Have a use case that doesn't fit? [Open an issue](https://github.com/luckyjackluo/cairn/issues)
or start a [discussion](https://github.com/luckyjackluo/cairn/discussions).

## Contributing

Contributions of every size are welcome — see [CONTRIBUTING.md](https://github.com/luckyjackluo/cairn/blob/HEAD/CONTRIBUTING.md)
for the project layout, dev setup, and how to add a tool. Good first issues are
labeled [`good first issue`](https://github.com/luckyjackluo/cairn/labels/good%20first%20issue).

## Develop

```bash
make setup      # uv venv (3.11) + editable install of all packages + extras
make test       # run the suite
make serve WORKSPACE=~/Documents/notes   # web UI
```

## License

MIT — see [LICENSE](https://github.com/luckyjackluo/cairn/blob/HEAD/LICENSE).