palinode

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

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

**Audit-grade memory for AI coding agents. Git-versioned and file-native — every fact your agent recalls, you can `blame`, `diff`, and `rollback`. 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 every remembered 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. 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.*

---

## 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` |

All platforms share the same MCP server — install once on your server, connect from any IDE. See [docs/MCP-SETUP.md](docs/MCP-SETUP.md) and [docs/MCP-INSTALL-RECIPES.md](docs/MCP-INSTALL-RECIPES.md) for per-client config snippets.

---

## 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 → validated updates → git history)
```

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-sse` serves **streamable-HTTP** at `/mcp/` — the binary name is historical; 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. Keyword precision when you need exact terms, semantic recall when you don't. Optional associative entity graph and prospective triggers.

**Compact** — Weekly consolidation produces structured, previewable changes and commits applied updates to git. You can review, blame, or revert every compaction.

**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

One 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 the same way: `palinode doctor` (or `curl http://127.0.0.1:6340/status`).

---

## Connect your editor

Palinode speaks MCP. Generate the correct config with the CLI instead of hand-pasting JSON (which drifts):

| Editor / harness | One command |
|---|---|
| **Claude Code (CLI)** | `claude mcp add palinode -- palinode-mcp` |
| **Claude Desktop** | `palinode mcp-config --stdio` → paste into the config it prints (quit Desktop first) |
| **Cursor / Windsurf / other MCP clients** | `palinode mcp-config --stdio` (local) or `--http` (remote / streamable-HTTP) |
| **Diagnose an existing setup** | `palinode mcp-config --diagnose` |

`palinode mcp-config` never writes your editor's config file — it prints a ready-to-paste block (pipe it straight to the target). Full per-harness detail: [docs/MCP-INSTALL-RECIPES.md](docs/MCP-INSTALL-RECIPES.md).

---

## Daily use — drop into a project

Already installed with `palinode-api` running? Scaffold any project in one command:

```bash
cd your-project
palinode init
```

That scaffolds `.claude/CLAUDE.md` (memory instructions, appended if one exists), `.claude/settings.json` (`SessionStart` + `SessionEnd` hook registration), both hook scripts, and `.mcp.json` (points Claude Code at the `palinode` MCP server). Sessions then start smart and end captured: the `SessionStart` hook injects your `core: true` memories into every fresh session (startup and `/clear`) so standing context is there before the first prompt, and the `SessionEnd` hook auto-captures on `/clear`, logout, and exit. Re-run with `--dry-run` to preview, `--force` to overwrite, or `--no-mcp` / `--no-hook` to scope it. See [`examples/hooks/`](examples/hooks/) for tuning knobs.

Projects that use other harnesses get the same memory instructio