Skip to content

Palinode v0.5.0 — First Tagged Release

Choose a tag to compare

View all tags
@Paul-Kyle Paul-Kyle released this 10 Apr 23:14
· 169 commits to main since this release
v0.5.0
b012832

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

This is the first tagged release of Palinode. 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.

Highlights

One backend, four interfaces, 18 tools. MCP server (Streamable HTTP or stdio), REST API on port 6340, Click-based CLI, and OpenClaw plugin. All expose the same capabilities. Set up once on a server, connect from any machine or IDE.

Hybrid search that actually works. SQLite-vec for vector similarity + FTS5 for BM25 keyword matching, fused via reciprocal rank fusion. Catches exact terms (model names, IDs, code snippets) that pure vector search misses.

Deterministic compaction. LLMs propose KEEP / UPDATE / MERGE / SUPERSEDE / ARCHIVE operations as structured JSON. A deterministic Python executor validates and applies them. The LLM never rewrites files directly. Every operation is a git commit. See ADR-001 for the reasoning.

Local-first. BGE-M3 embeddings via Ollama. Consolidation LLM via any OpenAI-compatible endpoint (vLLM, Ollama, whatever). Cloud API keys are opt-in. Nothing leaves your machine unless you configure it to.

Git-backed provenance. palinode blame traces every line in a memory file back to the session that wrote it. palinode history shows a file's evolution. palinode rollback reverts to a prior version safely. palinode diff --days 7 shows what changed across all your memory files in the last week.

See examples/compaction-demo/ for a walkthrough of a memory file across three consolidation passes with blame + diff output.

What's in this release

Core

  • SQLite-vec vector store with BGE-M3 embeddings (1024d)
  • Hybrid search (vector + BM25 via reciprocal rank fusion)
  • Hash-on-read freshness validation — detects out-of-band edits
  • File watcher daemon with debounced reindex and fault isolation

Consolidation

  • Deterministic executor for KEEP/UPDATE/MERGE/SUPERSEDE/ARCHIVE ops
  • Weekly full-corpus consolidation
  • Nightly lightweight pass (--nightly) bounded to UPDATE/SUPERSEDE
  • Model fallback chains (primary → fallback on timeout or HTTP error)
  • Versioned prompt system — extraction/compaction prompts as memory files with active: true

Interfaces (all four expose the same capabilities)

  • MCP server: Streamable HTTP transport (stdio also supported), 18 tools. Stateless HTTP client.
  • REST API: FastAPI on port 6340, 20+ endpoints including search, save, diff, history, blame, rollback, lint, migrate, session-end
  • CLI: 26 Click commands wrapping the API. TTY-aware. PALINODE_API env var for remote
  • Plugin: OpenClaw lifecycle hooks

New MCP tools since pre-release

  • palinode_lint — scan memory for orphans, stale active files, missing frontmatter, contradictions
  • palinode_blame / palinode_history / palinode_timeline / palinode_rollback — git-backed provenance
  • palinode_trigger — register prospective triggers that inject memory when context matches
  • palinode_prompt — list, read, activate versioned LLM prompt files

Capture

  • /session-end endpoint appends to daily notes + project status
  • Claude Code session-end hook — auto-captures on exit, idempotent, non-blocking
  • Entity extraction with keyword fallback

Migration

  • palinode migrate imports existing markdown memory systems with --review dry-run

Security

  • Path validation on all file operations
  • Secret scrubbing on save path via configurable regex patterns
  • Exclude-paths list prevents search from surfacing files in .secrets, credentials, etc.

Documentation

  • ADR-001: Tools Over Pipeline — why the executor is deterministic
  • Remote MCP setup guides for Claude Code, Claude Desktop, Cursor, Zed
  • Example memory files and compaction walkthrough

Tests

  • 92 tests covering parser, store, executor, API, CLI, migration, hybrid search

Breaking changes from pre-release

  • Deprecated SSE MCP transport removed. Use Streamable HTTP (canonical MCP SDK pattern).
  • REST API now binds to 127.0.0.1 by default. Set PALINODE_API_HOST=0.0.0.0 to expose on LAN.

Install

From source:

git clone https://github.com/Paul-Kyle/palinode
cd palinode
pip install -e .

PyPI release coming in a follow-up. See docs/INSTALL-CLAUDE-CODE.md for the full setup guide.

What's next

Palinode is being actively developed. Open issues track the roadmap:

  • Event-driven consolidation (see #86 — research complete, architecture proposed)
  • Multi-platform install guides (#24)
  • Generic markdown import for Obsidian / Logseq (#23)
Assets 2
Loading