palinode

<!-- mcp-name: io.github.phasespace-labs/palinode -->

```
┌─ palinode ─┐
│ ░░░░░░░░░░ │
│ ▓▓▓▓▓▓▓▓▓▓ │
│ ██████████ │
└────────────┘
```

**Audit-grade memory for AI agents. Every stored claim can carry an explicit epistemic status (`fact` / `inference` / `open_question` / `unverified`), typed links to the evidence that backs or contradicts it, and a verifiable quote-level citation to its source. MCP-first, so one memory works in every editor.**

Agent memory is becoming a commodity. *Auditable* agent memory is not: Palinode is the memory layer where a remembered fact says how strongly it is believed and what evidence backs it — and where every fact is a line in a git-versioned markdown file, readable, diffable, attributable to the commit that recorded it, and revertible when it's wrong. An unmarked memory is unmarked, never silently promoted to fact. No black-box vector store you have to trust.

Your agent's memory is a folder of markdown files. Palinode indexes them with hybrid search, compacts them with an LLM, and serves them through MCP — so the same memory works in Claude Code, Cursor, Windsurf, Zed, VS Code (Continue/Cline), and any other MCP-compatible editor. Bring your own Obsidian vault, or use Palinode as one: `palinode init --obsidian /path/to/vault` scaffolds a full vault with graph defaults, daily-notes wiring, and an LLM-maintained wiki contract. Enterprises can govern AI memory the same way they govern code. If every service crashes, `cat` still works.

*A palinode is a poem that retracts what was said before and says it better. That's what memory compaction does.*

Built by [Paul Kyle](https://github.com/Paul-Kyle) at [phasespace-labs](https://github.com/phasespace-labs). See [AUTHORS](AUTHORS.md).

---

## Supported Platforms

| Platform | Session Skill Path | MCP Config |
|----------|--------------------|------------|
| **Claude Code CLI** | `~/.claude/skills/` | `~/.claude.json` |
| **Claude Desktop** | `~/.claude/skills/` | `claude_desktop_config.json` |
| **Cursor** | `.cursor/skills/` | `.cursor/mcp.json` |
| **VS Code + Claude** (Continue / Cline) | `~/.claude/skills/` | see [MCP-INSTALL-RECIPES.md](docs/MCP-INSTALL-RECIPES.md) |
| **JetBrains + Claude** | `~/.claude/skills/` | `~/.claude.json` |
| **Antigravity IDE** | `.agent/skills/` | native 3-dot MCP menu |
| **Codex CLI** | N/A (no skills) | `~/.codex/config.toml` |
| **Pi** | N/A (native extension) | [plugins/pi/](plugins/pi/) — per-turn recall via lifecycle hooks |
| **Cline CLI / SDK** | N/A (native plugin) | [plugins/cline/](plugins/cline/) — per-turn recall via `AgentPlugin` hooks |

All platforms share the same MCP server — install once on your server, connect from any IDE. **[docs/HARNESSES.md](docs/HARNESSES.md) is the cross-harness map**: what each harness gets (native hooks vs. plugin vs. MCP), how the tiers stack, and where to start. Per-client config snippets: [docs/MCP-SETUP.md](docs/MCP-SETUP.md) and [docs/MCP-INSTALL-RECIPES.md](docs/MCP-INSTALL-RECIPES.md).

---

## The Idea

Most agent memory is a black box. You can't read it, you can't diff it, you can't `grep` it when the vector DB is down. Palinode bets on **plain files as the source of truth** and builds everything else as a derived index.

```
Files (markdown + YAML frontmatter)
  ↓ watched
Index (SQLite-vec vectors + FTS5 keywords, single .db file)
  ↓ queried by
Interfaces (MCP server, REST API, CLI, OpenClaw plugin)
  ↓ compacted by
Consolidation (structured operations → validation and application → git commits)
```

That's the whole architecture. One directory of `.md` files, one SQLite database, one API server. No Postgres, no Redis, no cloud dependency.

---

## One Backend, Every Interface

Palinode doesn't care how you talk to it. The full toolkit — save, search, doctor, dedup-suggest, orphan-repair, diff, blame, rollback, and more — works through every interface:

| Interface | Transport | Best For |
|-----------|-----------|----------|
| **MCP Server** | Streamable HTTP or stdio | Claude Code, Claude Desktop, Cursor, Windsurf, Zed, VS Code (Continue/Cline) |
| **REST API** | HTTP on :6340 | Scripts, webhooks, custom integrations |
| **CLI** | Wraps REST API | Cron jobs, SSH, shell scripts (8x fewer tokens than MCP) |
| **Plugin** | OpenClaw lifecycle hooks | Agent frameworks with inject/extract patterns |

Set up once on a server. Connect from any machine, any IDE, any agent framework. The MCP server is a pure HTTP client — it holds no state, no database connection, no embedder. Point it at the API and go.

```json
{
  "mcpServers": {
    "palinode": { "type": "http", "url": "http://your-server:6341/mcp/" }
  }
}
```

That's the entire client config. Works with Claude Code, Claude Desktop, Cursor, Windsurf, Zed, and VS Code (Continue/Cline). `palinode-mcp-http` serves **streamable-HTTP** at `/mcp/` — use `"type": "http"`, not `"type": "sse"`. Always include the trailing slash in the URL. See [docs/MCP-SETUP.md](docs/MCP-SETUP.md) for editor-specific install recipes.

---

## How It Works

**Store** — Typed markdown files (people, projects, decisions, insights) with YAML frontmatter. Git-versioned. Human-readable. Editable in Obsidian, VS Code, vim, or anything.

**Index** — A file watcher embeds with BGE-M3 and indexes with FTS5 as you save. Content-hash dedup skips re-embedding unchanged files (~90% savings). Single SQLite file, zero external services.

**Search** — Hybrid BM25 + vector search merged with Reciprocal Rank Fusion. The two arms have different jobs: on full-sentence questions the vector arm does nearly all the retrieval (FTS5 requires every query token to co-occur, which questions rarely satisfy), while BM25 catches the exact terms and identifiers embeddings blur. Measured together: 0.981 evidence recall@10 on LongMemEval_S ([benchmarks](docs/BENCHMARKS.md)). Optional associative entity graph and prospective triggers.

**Compact** — Weekly consolidation where an LLM returns structured operations and Palinode validates and applies them. Every compaction is a git commit you can review, blame, or revert.

**Dream** — If you've met "dreaming" as the name for this, `palinode dream` is an alias for `palinode consolidate`. Use `--dry-run` to inspect the proposed operations; each completed pass lands as a git commit, so a bad consolidation is a diff to review and a commit to revert.

**Audit** — `git blame` any fact. `git diff` any change. `rollback` any mistake. These aren't just git-compatible files — `palinode_diff`, `palinode_blame`, and `palinode_rollback` are first-class tools your agent can call.

---

## Requirements

- **Python 3.11+**
- **Git**
- **Ollama** with `bge-m3` (`ollama pull bge-m3`, ≈1.2 GB) — for semantic search.
  **Optional:** without an embedder Palinode runs in **keyword-only mode** (BM25/FTS5) — save,
  search, and audit all still work; you just don't get vector recall until you add one.

Optional extras: a chat model for weekly consolidation (any 7B+ that outputs JSON), OpenClaw for agent plugin hooks.

---

## Install

**Homebrew (macOS/Linux) — quickest path to the CLI:**

```bash
brew install phasespace-labs/palinode/palinode
palinode --version
```

That taps and installs in one command. It puts the `palinode` CLI on your PATH; the
service binaries (`palinode-api`, `palinode-watcher`, `palinode-mcp`) currently live in
the tap's private prefix, so for running services use the source install below or Docker.

**From source — the full-stack path.** Clone, install, point at a memory directory,
check it worked:

```bash
# 1. Get the code (lives separately from your memory — never the same directory)
git clone https://github.com/phasespace-labs/palinode ~/palinode-src && cd ~/palinode-src
python3 -m venv venv && source venv/bin/activate
pip install -e .

# 2. Create your memory directory (this is where your data lives — keep it private)
mkdir -p ~/.palinode && cd ~/.palinode && git init
cp ~/palinode-src/palinode.config.yaml.example palinode.config.yaml
# memory_dir stays commented out in the copied config → it inherits PALINODE_DIR below

# 3. Start the services (each in its own terminal — or as a service, next section)
PALINODE_DIR=~/.palinode palinode-api        # REST API on :6340
PALINODE_DIR=~/.palinode palinode-watcher     # auto-indexes on file save

# 4. Did it work?
palinode doctor
```

`palinode doctor` is the single "did it install correctly?" command — run it after every install, upgrade, or server move. On a fresh venv, use the venv's absolute path for the MCP command (`~/palinode-src/venv/bin/palinode-mcp`) so it resolves its own dependencies — see [llms-install.md](llms-install.md) for the wrong-Python trap.

> Your memory directory is **private** — it holds personal data. Never make it public; the code repo contains zero memory files. For a pre-populated demo, copy `examples/sample-memory/` into `~/.palinode/`.

---

## Running as a service

Three long-running processes (API, watcher, embedder) shouldn't live in terminal tabs. Pick one:

| Platform | How | Details |
|---|---|---|
| **Anywhere with Docker** | `docker compose up -d` from the repo root — API + watcher + Ollama, with the `bge-m3` pull handled for you (≈1.2 GB on first run) | [docker-compose.yml](docker-compose.yml) header comments |
| **Linux** | systemd units via `deploy/systemd/install.sh --enable` | [deploy/systemd/README.md](deploy/systemd/README.md) |
| **macOS** | launchd LaunchAgents from templates | [deploy/launchd/README.md](deploy/launchd/README.md) |
| **Windows** | use Docker Compose (set `PALINODE_DATA_DIR` to a Windows path) | [docker-compose.yml](docker-compose.yml) header comments |

With compose, your memory stays on the **host** at `~/.palinode` (override with `PALINODE_DATA_DIR`) — the containers mount it; files remain the source of truth. Already running Ollama on the host? `OLLAMA_URL=http://host.docker.internal:11434 docker compose up -d palinode-api palinode-watcher` skips the bundled one. Verify any of the three