palace-rs

# palace-rs

[![CI](https://github.com/AncientiCe/palace-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/AncientiCe/palace-rs/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Rust 1.82+](https://img.shields.io/badge/rust-1.82%2B-orange.svg)](https://www.rust-lang.org)

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`:

| Table | Purpose |
|---|---|
| `drawers` | Text content + embedding BLOB + metadata |
| `entities` | KG entity nodes |
| `triples` | KG temporal relationship edges |

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:

```bash
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.

| Split | R@1 | R@5 | R@10 |
|---|---:|---:|---:|
| `longmemeval_oracle` (sanity check) | 1.000 | 1.000 | 1.000 |
| `longmemeval_s_cleaned` | **0.889** | **0.981** | **0.991** |

Per-question-type on `s_cleaned`:

| Question type | R@1 | R@5 | R@10 |
|---|---:|---:|---:|
| knowledge-update | 0.944 | 1.000 | 1.000 |
| multi-session | 0.909 | 0.983 | 1.000 |
| single-session-assistant | 1.000 | 1.000 | 1.000 |
| single-session-preference | 0.633 | 0.867 | 0.933 |
| single-session-user | 0.922 | 1.000 | 1.000 |
| temporal-reasoning | 0.835 | 0.976 | 0.984 |

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

```bash
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:**
```bash
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 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](https://registry.modelcontextprotocol.io)
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

```bash
cargo install --path .
palace install
```

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

> **Upgrading from `mempalace` (≤ 0.1.9)?** See [Migrating from `me