palace-rs

A local-first memory retrieval engine for coding agents, implemented in Rust.

This project stores verbatim project and conversation memory, embeds it locally, and retrieves source-grounded context through MCP. It is built for coding agents that need to remember decisions, prior fixes, commands, project conventions, and user preferences across sessions without running a separate vector database.

What It Does

• Stores project files and conversation turns in a local SQLite database.
• Generates local embeddings with ONNX Runtime and all-MiniLM-L6-v2.
• Retrieves memories with hybrid semantic/BM25 search plus coding-agent intent boosts.
• Tags preference-shaped drawers and runs a dedicated preference recall pass for fuzzy "what do I prefer?" and convention questions.
• Stores preference spans with optional secondary embeddings and exposes a preference_match score for preference-shaped queries.
• Classifies search intent (preference, decision, how_to, definition, temporal, unknown) and can optionally rerank top results with a local interaction reranker.
• Sanitizes agent-generated query dumps before retrieval.
• Returns source-grounded results with score provenance and nearby source context.
• Warms up agents from recent diary entries with project, topic, timestamp, tags, and compact session text.
• Provides a knowledge graph for temporal entity relationships.
• Measures real-world usefulness through palace gain precision metrics and optional folded feedback on the existing palace_gain MCP tool.
• Exposes MCP tools for assistants that support Model Context Protocol.
• Offers a small Rust library API for embedding memory into other services.
• Tracks a first-class wings registry (project vs. topic wings) with on-demand project mining and topic-wing creation.
• Pins the nine protocol-critical MCP tools resident with alwaysLoad so the memory protocol doesn't depend on tool-search deferral (Claude Code >= 2.1.121).
• Injects real recalled memory — recent diary entries plus top drawers for the session's project — directly into SessionStart, not just protocol text.

Agent Memory Reliability

Palace focuses on the retrieval cases that matter most during coding work: preferences, project conventions, recent session continuity, source-grounded answers, and measurable usefulness in real agent sessions. Drawers that look like user preferences or conventions are tagged in metadata during writes and updates, record the matched preference span, and can store a secondary preference embedding. Preference-shaped queries receive a dedicated preference_match score alongside hybrid semantic/BM25 search.

MCP search responses expose score provenance (combined, cosine, bm25, and coding_boost, preference_match, optional rerank_score, and intent) plus adjacent source context so agents can cite why a memory was returned. Diary tools provide warm-start context for recent sessions, including project path, topic, timestamp, session ID, tags, and compact text.

Library consumers can use Palace::search_with_provenance when they need the same structured score details that MCP tools return.

Storage

Collapses Python's dual-store (ChromaDB + SQLite) into one file at ~/.palace/palace.db:

Embeddings are stored as f32 vectors from all-MiniLM-L6-v2. Search uses local cosine similarity over the stored vectors.

Benchmarks

Coding-Agent Memory Eval

The repository includes a focused eval fixture for practical coding-agent memory questions. It stores realistic memories about project decisions, prior failures, commands, conventions, user preferences, and current direction, then asks 40 questions such as:

• why did we choose bundled sqlite?
• how did we fix the migration test failure last time?
• what clippy command should I run?
• what is the project convention for search results?
• what changed in the current product direction?

Run it with:

cargo test --test coding_agent_eval -- --nocapture

The test reports recall@1 and recall@5 and fails if retrieval drops below the stable threshold. This is the product-shaped proof: not broad memory theater, but whether a coding agent can recover the right project context when it matters.

LongMemEval

Retrieval recall on the LongMemEval s_cleaned split — 500 questions over conversational haystacks of ~50 sessions / ~115k tokens each (30 abstention questions are filtered out per the standard convention, leaving 470 evaluated).

The recipe behind the numbers below:

• Granularity: one drawer per session.
• Indexed content: the full session — both user and assistant turns are stored and embedded together. No user-turn filtering, no summarization, no LLM extraction.
• Embedder: all-MiniLM-L6-v2 (384-dim, ONNX), 512-token cap, run locally — no API calls.
• Retrieval: hybrid baseline — BM25 (k1=1.5, b=0.75, weight 0.35) fused with cosine similarity (weight 0.65), top-K = 10. These reported LongMemEval numbers used pure score fusion, before the coding-agent intent boosts used by current project-memory search.
• No LLM at any stage: no extraction, no rerank, no answer generation. The recall numbers measure the retriever in isolation.
• Metric: recall_any@K at session granularity — does any gold session appear in the top-K results?
• Hardware: Apple M1 Pro, 10 cores (8P + 2E), 32 GB RAM.

Per-question-type on s_cleaned:

Reading the numbers

• oracle is a sanity check, not a real result. That split hands the retriever only the sessions known to contain the answer, so perfect recall just confirms the pipeline is wired up correctly.
• s_cleaned is the real test. ~50 sessions / ~115k tokens of conversational haystack per question, no hints. R@5 = 0.981 means that for 461 of 470 evaluated questions, a gold session appears somewhere in the top 5 retrieved.
• R@1 → R@5 → R@10 tells you where the failures cluster. The jump from 0.889 to 0.981 means most "misses" at top-1 are near-misses — the right session is usually rank 2–5, displaced by a lexically similar distractor. The further jump to 0.991 at top-10 means only ~9 questions out of 470 fall outside the top-10 entirely; those are the genuinely hard cases.
• Per-question-type breakdown is where the model's blind spots show.
  • single-session-assistant, single-session-user, knowledge-update: ≥0.94 at R@1, ≈1.0 at R@5. The retriever handles direct questions where the answer is stated verbatim in one session.
  • multi-session and temporal-reasoning: strong at R@5 (~0.98) but lower at R@1 (~0.83–0.91). Multiple sessions are relevant and the "best" one is a judgement call — top-1 ranking among near-equivalents is genuinely ambiguous.
  • single-session-preference: the visible weak spot at 0.633 / 0.867 / 0.933. Preference questions ("what's my favorite X") are answered by sentences like "I like…" / "I prefer…" that don't share keywords with the question. Pure BM25 + frozen MiniLM has no signal for preference-shaped sentences specifically; closing this gap would require either an LLM-extracted preference index or a hand-rolled pattern booster.
• What's deliberately not in these LongMemEval numbers. No LLM at any stage — no extraction during ingest, no query rewriting, no rerank, no answer generation. No per-dataset hyperparameter tuning. No GPU. The result is the baseline retriever in isolation, on a single CPU, with fixed defaults.

Installation

Homebrew (macOS Apple Silicon / Linux)

brew tap AncientiCe/palace
brew install palace

# Configure MCP servers
palace install --all

Note: macOS Intel is not supported due to ONNX Runtime unavailability. Apple Silicon and Linux x86_64 are fully supported.

Install Script (macOS / Linux / Windows)

macOS / Linux:

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

Windows:

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

The installer downloads the matching GitHub Release binary, verifies its SHA-256 checksum, installs it locally, and registers the MCP server with Cursor, Codex, and Claude Code.

MCP Registry / MCPB bundle

Palace is published to the official MCP registry as io.github.ancientice/palace-rs. Registry-aware clients can discover and install it directly. Each release also ships a self-contained palace-<version>.mcpb bundle (Linux x86_64, macOS arm64, Windows x86_64) as a GitHub Release asset for one-click install in MCPB-aware hosts such as Claude Desktop.

Development Install

cargo install --path .
palace install

The first time you run mine, the embedding model is downloaded automatically from HuggingFace and cached.