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 at phasespace-labs. See AUTHORS.

Supported Platforms

All platforms share the same MCP server — install once on your server, connect from any IDE. 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 and 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:

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.

{
  "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 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). 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:

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:

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