Palinode

Persistent memory for AI agents. Markdown in, markdown out, git everything.

Your agent's memory is a folder of markdown files. Palinode indexes them with hybrid search, compacts them with an LLM, and exposes them through any interface you want — MCP, REST API, CLI, or plugin hooks. 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.

---

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, plugin hooks)
  ↓ compacted by
LLM (proposes ops → deterministic executor applies them → 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 same 17 tools work everywhere:

Interface	Transport	Best For
MCP Server	Streamable HTTP or stdio	Claude Code, Claude Desktop, Cursor, Zed
REST API	HTTP on :6340	Scripts, webhooks, custom integrations
CLI	Wraps REST API	Cron jobs, SSH, shell scripts (8x fewer tokens than MCP)
Plugin	Agent 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.

{
  "mcpServers": {
    "palinode": { "url": "http://your-server:6341/mcp/" }
  }
}

That's the entire client config for Claude Code, Claude Desktop, Cursor, or Zed. See docs/MCP-SETUP.md for multi-IDE setup, or docs/INSTALL-CLAUDE-CODE.md for Claude Code specifically.

---

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 where an LLM proposes structured operations (KEEP / UPDATE / MERGE / SUPERSEDE / ARCHIVE) and a deterministic executor applies them. The LLM never touches your files directly. Every compaction is a git commit you can review, blame, or 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.

---

Quick Start

# Install
git clone https://github.com/phasespace-labs/palinode && cd palinode
python3 -m venv venv && source venv/bin/activate
pip install -e .

# Create your memory directory
mkdir -p ~/.palinode/{people,projects,decisions,insights,daily}
cd ~/.palinode && git init
cp /path/to/palinode/palinode.config.yaml.example palinode.config.yaml  # adjust path

# Start services
PALINODE_DIR=~/.palinode palinode-api        # REST API on :6340
PALINODE_DIR=~/.palinode palinode-watcher     # auto-indexes on file save
PALINODE_DIR=~/.palinode palinode-mcp-sse     # MCP server on :6341 (optional)

# Verify
curl http://localhost:6340/status

Your memory directory is private. It contains personal data. Never make it public. The code repo contains zero memory files.

---

Tools

17 tools available through every interface:

Tool	What It Does
search	Hybrid BM25 + vector search with category filter
save	Store a typed memory (person, decision, insight, project)
list	Browse memory files by type, filter by core status
read	Read the full content of a memory file
ingest	Fetch a URL and save as research
status	Health check — file counts, index stats, service status
history	Git history with diff stats, rename tracking, and limit
entities	Entity graph — cross-references between memories
consolidate	Preview or run LLM-powered compaction
diff	What changed in the last N days
blame	Trace a fact back to the commit that recorded it
rollback	Revert a file to a previous commit (safe, creates new commit)
push	Sync memory to a remote git repo
trigger	Prospective recall — auto-inject when a topic comes up
lint	Health scan — orphans, stale files, missing fields
session_end	Capture summary, decisions, and blockers at end of session
prompt	List, show, or activate versioned LLM prompts

Every tool is accessible as palinode_<name> via MCP, palinode <name> via CLI, or POST/GET /<name> via the REST API.

---

Stack

Layer	Choice	Why
Source of truth	Markdown + YAML frontmatter	Human-readable, git-versioned, portable
Vector index	SQLite-vec (embedded)	No server, single file, zero config
Keyword index	SQLite FTS5 (embedded)	BM25 for exact terms, zero dependencies
Embeddings	BGE-M3 via Ollama	Local, private, no API key needed
API	FastAPI	Lightweight, async, one process
MCP	Python MCP SDK (Streamable HTTP)	Works with every IDE over the network
CLI	Click (wraps REST API)	Shell-native, TTY-aware output
Behavior	PROGRAM.md	What to remember, how to extract, how to compact — edit one file to change all behavior

---

Memory File Format

---
id: project-palinode
category: project
name: Palinode
core: true
status: active
entities: [person/paul]
last_updated: 2026-04-05T00:00:00Z
summary: "Persistent memory for AI agents."
---
# Palinode

Your content here. As detailed or brief as you want.
Files marked `core: true` are always in context.
Everything else is retrieved on demand via hybrid search.

Open your memory directory as an Obsidian vault for visual browsing. See docs/OBSIDIAN-SETUP.md.

---

Configuration

All behavior is in palinode.config.yaml:

memory_dir: "~/.palinode"
ollama_url: "http://localhost:11434"
embedding_model: "bge-m3"

recall:
  search:
    top_k: 5
    threshold: 0.4
  core:
    max_chars_per_file: 3000

search:
  hybrid_enabled: true
  hybrid_weight: 0.5         # 0.0 = vector only, 1.0 = BM25 only

consolidation:
  llm_model: "llama3.1:8b"   # any chat model that outputs JSON
  llm_url: "http://localhost:11434"
  llm_fallbacks:              # tried in order if primary fails
    - model: "qwen2.5:14b-instruct"
      url: "http://localhost:11434"

All models are swappable. Any Ollama embedding model, any OpenAI-compatible chat endpoint. See palinode.config.yaml.example for the full reference.

---

Requirements

• Python 3.11+
• Ollama with bge-m3 (ollama pull bge-m3)
• Git

Optional: a chat model for consolidation (any 7B+ works).

---

API Reference

Method	Path	Description
GET	/status	Health check + stats
POST	/search	Hybrid search with filters
POST	/search-associative	Entity graph traversal
POST	/save	Create a typed memory file
POST	/ingest-url	Fetch URL, save as research
GET/POST	/triggers	Prospective recall triggers
POST	/consolidate	Run or preview compaction
GET	/list	Browse files by type
GET	/read?file_path=...	Read a memory file
GET	/history/{file_path}	Git log for a file
GET	/diff	Recent changes
GET	/blame/{file_path}	Git blame
POST	/rollback	Revert a file
POST	/push	Push to git remote
POST	/reindex	Rebuild indices
POST	/session-end	Capture session summary
POST	/lint	Health scan

---

Design Principles

1. Files are truth. Not databases, not vector stores. Markdown files that humans can read, edit, and version with git.

2. Typed, not flat. People, projects, decisions, insights — each has structure. This enables reliable retrieval and consolidation.

3. Consolidation, not accumulation. 100 sessions should produce 20 well-maintained files, not 100 unread dumps.

4. Invisible when working. The human talks to their agent. Palinode works behind the scenes.

5. Graceful degradation. Vector index down? Read files directly. Embedding service down? Grep. Machine off? It's a git repo, clone it anywhere.

6. Zero taxonomy burden. The system classifies. The human reviews. If the human has to maintain a taxonomy, the system dies.

---

What's Unique

• Git operations as agent tools — diff, blame, rollback, push exposed via MCP. No other system makes git ops callable by the agent.
• Operation-based compaction — KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE DSL. LLM proposes, deterministic executor disposes. Every compaction is a reviewable git commit.
• Per-fact addressability — <!-- fact:slug --> IDs inline in markdown, invisible in rendering, preserved by git, targetable by compaction.
• 4-phase injection — Core (always) + Topic (per-turn search) + Associative (entity graph) + Triggered (prospective recall).
• Multi-transport MCP — stdio for local, Streamable HTTP for remote. One server, any IDE on any machine.
• If everything crashes, cat still works.

---

Acknowledgments

Palinode builds on ideas from Karpathy's LLM Knowledge Bases, Letta (tiered memory), and LangMem (typed schemas + background consolidation). See docs/ACKNOWLEDGMENTS.md for the full list.

See also the epistemic integrity discussion in the Karpathy gist thread — particularly the problem of LLM wikis that "synthesise without citing, drift from sources without knowing it, and present false certainty where disagreement exists." Git-based provenance is Palinode's answer to that problem.

If you know of prior art we missed, please open an issue.

---

License

MIT

---

Built by Paul Kyle with help from AI agents who use Palinode to remember building Palinode.