Palace

Local-first memory for coding agents.

Your agent remembers decisions, fixes, commands, and preferences between sessions.

One binary, one SQLite file, no API keys, no cloud.

Quick start · Install · How it works · Clients · CLI · MCP tools · FAQ

---

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 (or another supported model) 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- .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

The embedding model (~23 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:

Figure 1. One palace holds many wings. Rooms group drawers, and the knowledge graph and diaries sit alongside them.

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 from you or the agent"] --> S["Sanitize strip pasted dumps"] S --> I["Classify intent decision · how_to · preference …"] I --> H["Hybrid search BM25 + cosine"] H --> B["Coding boosts

• preference pass"] B --> R{"Rerank?

optional"} R --> OUT["📎 Results scores + source + neighbours"] DB[("palace.db local embeddings")] -.-> H

Figure 2. What happens to a query. Everything runs locally on your CPU.

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).

Embedding models

Palace ships with all-MiniLM-L6-v2 and can switch a palace to another local model. Every vector is rebuilt from the stored text, so switching never loses memory.

Experimental models scored below MiniLM on the coding-agent eval and about level on probes from a real palace (see the bake-off). You can try them on your own palace: verification decides whether it switches.

palace embeddings list                       # models, which is active, which are downloaded

palace embeddings estimate minilm-l6-v2-q8 # time, disk and latency, measured on this machine palace embeddings migrate minilm-l6-v2-q8 # build, verify, switch (e.g. an older fp32 palace) palace embeddings rollback # back to the previous model, instantly palace embeddings cleanup # drop the previous model's vectors

migrate builds the new vectors in batches while search keeps using the current model, so it is safe to interrupt and rerun. When the vectors are built, it checks the new model against the current one on 200 known-item probes taken from your palace (hybrid and vector-only recall@1/@5, plus query latency). It switches only if recall@5 drops by at most 0.01 and p95 query latency stays within budget. The budget is twice the current model's p95, and at least 25 ms. Run palace embeddings cutover --force to switch anyway, or palace embeddings cancel to keep the current model.

Setting embedding_model in config.json (or PALACE_EMBEDDING_MODEL) picks the model for a new, empty palace. An existing palace never switches on its own. palace status, palace_status, and palace_session_context report the pending migration until you run migrate. Nothing migrates on its own: you run migrate, or ask your agent to, which uses the palace_embeddings MCP tool (it runs the same steps in the background of the server). In remote mode the server owns the model, so these commands run on the server.

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:

Figure 3. Three hooks read memory into the session. The fourth makes sure the session's lessons get written back.

| Session start | Injects the memory protocol, y