palace-rs

<p align="center"> <img src="docs/images/banner.svg" alt="palace banner: decisions, commands, and preferences from today's session go into a local palace, so the agent's next session remembers them" width="100%"> </p> <p align="center"> <a href="https://github.com/AncientiCe/palace-rs/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/AncientiCe/palace-rs/actions/workflows/ci.yml/badge.svg"></a> <a href="https://github.com/AncientiCe/palace-rs/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/AncientiCe/palace-rs?sort=semver"></a> <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a> <img alt="Platforms: Linux, macOS, Windows" src="https://img.shields.io/badge/platforms-Linux%20%7C%20macOS%20%7C%20Windows-informational"> <img alt="Rust 1.82+" src="https://img.shields.io/badge/rust-1.82%2B-orange?logo=rust"> <a href="https://registry.modelcontextprotocol.io"><img alt="Listed in the MCP registry" src="https://img.shields.io/badge/MCP-registry-8250df"></a> <img alt="Works with Claude Code, Codex, Cursor, Gemini CLI, VS Code, OpenCode, Cline, Zed, Goose, Windsurf and Claude Desktop" src="https://img.shields.io/badge/works%20with-11%20AI%20agents-8A2BE2"> </p> <p align="center"> <b>Local-first memory for coding agents.</b><br> Your agent remembers decisions, fixes, commands, and preferences between sessions.<br> One binary, one SQLite file, no API keys, no cloud. </p> <p align="center"> <a href="#-quick-start">Quick start</a> · <a href="#-install">Install</a> · <a href="#-how-it-works">How it works</a> · <a href="#-supported-clients">Clients</a> · <a href="#-cli-reference">CLI</a> · <a href="#-mcp-tools">MCP tools</a> · <a href="#-faq">FAQ</a> </p>

---

Palace gives Claude Code, Codex, Cursor, Gemini CLI, VS Code, OpenCode, Cline, Zed, Goose, Windsurf, and Claude Desktop a memory that lasts between sessions. It stores what happened verbatim, recalls it automatically when it's relevant, and cites where each answer came from.

You:    why did we switch the queue to SQLite last month?
Agent:  [palace_search → wing my_api, room decisions, filed 2026-09-03]
        You dropped Redis because the deploy target had no persistent volume.
        The benchmark you ran is in the same drawer.

---

🧭 Why Palace

Every new agent session starts with no memory. You explain the architecture again. The agent repeats a fix you rejected last week. It greps the whole repo to rediscover a convention you settled months ago.

Palace fixes that by:

• Storing text verbatim. Code, notes, and conversations are stored as written, not as an LLM summary that loses detail.
• Running locally. Embeddings come from all-MiniLM-L6-v2 on ONNX Runtime, on your CPU. Nothing leaves your machine unless you turn on remote mode.
• Recalling without being asked. Hooks inject relevant memory when a session starts, when you send a prompt, and while the agent investigates. The agent does not need to remember to search.
• Citing sources. Every result carries its wing, room, source file, drawer id, and score breakdown, so you can check where an answer came from.
• Shipping as one binary. No Python, no vector database, no Docker. One palace executable and one palace.db file.

It also works outside software projects. The creative and personal profiles adapt it for worldbuilding, fiction, coaching, or household notes.

---

📦 Install

Pick one. Each method installs the palace binary. Run palace install afterwards to connect your agents.

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/AncientiCe/palace-rs/main/scripts/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/AncientiCe/palace-rs/main/scripts/install.ps1 | iex

The scripts download the matching GitHub Release binary, verify its SHA-256 checksum, and install it. To upgrade later, run the same command again.

Homebrew (macOS Apple Silicon / Linux)

brew tap AncientiCe/palace
brew install palace

To upgrade, refresh the tap first. Without brew update, Homebrew can keep reporting the old version as already installed:

brew update && brew upgrade palace

When a release changes the memory protocol rule (the CHANGELOG says so), run palace install again afterwards so your agents get the new rule text.

MCP registry / MCPB bundle. Palace is listed in the official MCP registry as io.github.ancientice/palace-rs. Each release also ships a palace-<version>.mcpb bundle (Linux x86_64, macOS arm64, Windows x86_64) for one-click install in MCPB-aware hosts such as Claude Desktop.

From source

git clone https://github.com/AncientiCe/palace-rs && cd palace-rs
cargo build --release   # binary at target/release/palace

| Platform | Status | |---|---| | Linux x86_64 | Supported | | macOS Apple Silicon | Supported | | Windows x86_64 | Supported | | macOS Intel | Not supported (no ONNX Runtime build) |

The embedding model (~90 MB) downloads from Hugging Face the first time you mine or search, then stays cached in ~/.cache/huggingface.

---

⚡ Quick start

palace install            # connect every supported agent on this machine
palace doctor             # check that every client is wired up
palace init ~/my-project --yes --auto-mine   # detect rooms, write palace.yaml, mine

Restart your agent app so it reloads its MCP config. Then try:

"What do we know about how this project handles database migrations?"

The agent should call palace_search and answer from memory, citing the drawer it used. You can also search from the terminal:

palace search "how did we decide on the database schema"

From then on, the agent writes a diary entry after substantial work and stores durable decisions as facts. Tomorrow's session, from any of your agents, picks up where today's left off.

---

🔍 How it works

The palace

Memory is organised like a building, which keeps search focused:

<p align="center"> <img src="docs/images/structure.svg" alt="Inside a palace: a project wing my_api with rooms backend, decisions, and testing full of drawers; a topic wing sales_notes; a knowledge graph fact my_api uses_queue SQLite; and agent diaries from claude and codex" width="100%"> </p>

_{<i>Figure 1. One palace holds many wings. Rooms group drawers, and the knowledge graph and diaries sit alongside them.</i>}

| Concept | What it is | Example | |---|---|---| | Wing | A project or a topic | my_api, sales_notes | | Room | An area inside a wing | backend, testing, decisions | | Drawer | One chunk of verbatim text plus its embedding and metadata | a paragraph of db.rs, a diary entry | | Knowledge graph | Time-stamped facts: subject → predicate → object | my_api → uses_queue → SQLite (valid from 2026-09-03) | | Diary | Per-agent session notes for continuity | "Fixed the flaky migration test by…" | | Tunnel | A link between rooms in different wings | my_api/auth ↔ my_web/login |

Wings are either project wings (a folder on disk, created by palace mine) or topic wings (no folder, such as chat history or meeting notes, created with palace_create_wing).

Retrieval

flowchart LR
    Q["💬 Question<br/>from you or the agent"] --> S["Sanitize<br/>strip pasted dumps"]
    S --> I["Classify intent<br/>decision · how_to · preference …"]
    I --> H["Hybrid search<br/>BM25 + cosine"]
    H --> B["Coding boosts<br/>+ preference pass"]
    B --> R{"Rerank?<br/>optional"}
    R --> OUT["📎 Results<br/>scores + source + neighbours"]
    DB[("palace.db<br/>local embeddings")] -.-> H

_{<i>Figure 2. What happens to a query. Everything runs locally on your CPU.</i>}

Search fuses BM25 keyword scoring with cosine similarity over local embeddings. It then applies intent boosts for coding questions. Each query is classified as preference, decision, how_to, definition, temporal, or unknown. Preference-shaped questions ("how do I like my commits?") get a dedicated pass against tagged preference spans. A local cross-encoder reranker is available as an option (--rerank or PALACE_RERANK=1).

Agent-generated query dumps are cleaned up before retrieval. Results come back with score provenance (combined, cosine, bm25, coding_boost, preference_match, rerank_score, intent) and the neighbouring chunks from the same source file.

Automatic recall (hooks)

palace install registers user-level hooks, so memory works in every project without editing per-project files:

<p align="center"> <img src="docs/images/hooks.svg" alt="One agent session, four hooks: session start, prompt submit, and post tool use recall from palace.db; stop asks the agent to save a diary entry and decisions" width="100%"> </p>

_{<i>Figure 3. Three hooks read memory into the session. The fourth makes sure the session's lessons get written back.</i>}

| Hook | What it does | |---|---| | Session start | Injects the memory protocol, your standing rules from general/preferences (verbatim, in every project), recent diary entries for this project (from any agent), and the top drawers of the project's wing. | | Prompt submit | Searches Palace with your actual question and injects matching drawers before the agent answers. If a history question finds nothing, it tells the agent to run palace_search. In Claude Code it also adds a one-line reminder until the session calls a Palace tool. Skips short prompts and slash commands. Claude Code and Codex only. | | Post tool use | While the agent greps and reads files, recalls related memory so earlier decisions surface without a search. In Claude Code it also records the session's Palace calls. | | Stop | If the session did real work but saved nothing, asks the agent once to write a diary entry and record decisions before it finishes. In Claude Code this is judged per session, including sessions that never used Palace; other agents use a recent-activity window. |

Auto-recall is limited to the current project. Drawers from your other project wings and diaries from other projects stay out. Topic wings still appear.

All hooks fail open: if the palace is missing or empty, the agent works as normal.

The memory protocol

palace install also writes a short rule into each client's instruction file. The rule tells the agent when to use memory:

1. Session start: palace_status → palace_session_context → palace_diary_search.
2. Before answering a question about past decisions, preferences, or history: palace_search and palace_kg_query, before grep.
3. After work: palace_diary_write, plus palace_kg_add for durable facts.

Grep remains the right first tool for current symbols, exact definitions, and code that may have changed since it was mined.

The nine protocol tools are marked _meta."anthropic/alwaysLoad" = true, so Claude Code 2.1.121 and later keeps them loaded instead of deferring them behind tool search.

Memory layers

| Layer | Name | Contents | |---|---|---| | L0 | Identity | ~/.palace/identity.txt, always loaded (~100 tokens) | | L1 | Essential story | Top drawers by importance, grouped by room (~600–900 tokens) | | L2 | On demand | Wing- and room-filtered retrieval | | L3 | Deep search | Full hybrid search across the palace |

palace wake-up prints L0 and L1. Agents reach L2 and L3 through MCP tools.

---

🔌 Supported clients

palace install configures every supported client by default (--client all). Gemini CLI, VS Code, Windsurf, OpenCode, Cline, Zed and Goose are included only when their config folder exists, so Palace never sets up an agent you don't have. Use `--client