# Alexandria

> A local knowledge vault for your AI agents — saves tokens, remembers across sessions, and turns every model into a disciplined engineer.

- **Type:** MCP server
- **Install:** `agentstack add mcp-ureckchan-alexandria`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [UreckChan](https://agentstack.voostack.com/s/ureckchan)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [UreckChan](https://github.com/UreckChan)
- **Source:** https://github.com/UreckChan/alexandria
- **Website:** https://alexandria.ureck.dev

## Install

```sh
agentstack add mcp-ureckchan-alexandria
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🏛️ Alexandria

> A local knowledge vault for your AI agents — saves tokens, remembers across sessions, and turns every model into a disciplined engineer.

[](https://www.npmjs.com/package/@ureck/alexandria)
[](./LICENSE)
[](https://buymeacoffee.com/ureck)

[](https://ureckchan.github.io/alexandria/) **[Documentation / Documentación](https://ureckchan.github.io/alexandria/)**

Alexandria automatically captures your AI prompts and sessions, searches that knowledge **before** spending tokens, and connects everything in an Obsidian-style graph. **100% local**: no database, no API keys, no telemetry, no cost.

Works with the most popular agents via MCP: **Claude Code · Cursor · OpenCode · Devin CLI · Cline · Codex CLI · Gemini CLI · VS Code (Copilot) · OpenClaw · Hermes Agent · Windsurf (legacy)**.

## Why?

Every new AI session starts from zero: it re-explores your code, re-derives decisions you already made, re-spends the same tokens. Alexandria breaks that cycle:

- **Saves tokens**: every prompt triggers a local semantic search ( **Plan → Execute one task → Verify with evidence → (on failure: reuse past lessons) → Extract the lesson**

It lives in the MCP tools themselves — their names and descriptions carry the instructions — so it works identically across every agent, with or without hooks:

| MCP tool | What the agent does with it | Token payoff |
|---|---|---|
| `plan_create(title, goal, dod, tasks, design?)` | Plans like an **architect**: clarifies vague goals first, optionally records the architecture (`design` → a `## Design` section), and the response surfaces **similar past plans + relevant lessons** plus quality hints (verifiable DoD, small tasks) — suggestions, never a gate | No wandering; open plans are re-injected next session so work is resumed, not repeated |
| `task_verify(plan, task, passed, verify_command, cwd?)` | **Runs** `verify_command` (e.g. `npm test`) and takes the verdict from the real exit code — not from the agent's word. Flags a **discrepancy** if the agent claimed otherwise; without a command the note is tagged `self-reported` and `ale audit` calls it out | "✅ 12/12 passed" (5 tokens) instead of a 500-line log; on failure it automatically surfaces **past lessons** that match |
| `lesson_extract(title, lesson, links)` | Distills the root cause + fix after solving something non-obvious | ~200 tokens today replace ~20,000 tokens of re-debugging next month |

Lessons and solutions get a ranking boost in search, so the most valuable knowledge always surfaces first. The protocol is **on by default**; toggle it anytime:

```bash
ale config set protocol false   # classic vault only
ale config set protocol true    # back on
ale init --no-protocol          # install without it
```

## Install

```bash
# npm (Node ≥ 20)
npm install -g @ureck/alexandria

# bun
bun add -g @ureck/alexandria

# deno
deno install -grA -n ale npm:@ureck/alexandria/ale
# (if Deno complains about "minimum dependency date", add --minimum-dependency-age=0)
```

Verify:

```bash
$ ale --version
1.3.1
```

## Getting started

One command installs everything (embedding model ~130MB downloaded once, hooks, MCP registration, index):

```bash
# Global — one shared vault for all your sessions (~/Alexandria)
ale init

# Per project — vault INSIDE the repo (./Alexandria)
cd my-project
ale init --project

# Point at an existing Obsidian vault
ale init --path ~/Documents/MyObsidianVault

# Choose which agents get the MCP server
ale init --agents all                      # every supported agent
ale init --agents claude,cursor,opencode   # just these
# (without --agents: Claude Code + whatever is detected on your machine)
```

`ale init --project` also, automatically:
- adds the vault to your `.gitignore` (personal knowledge, not repo code),
- **scans the project** (stack from package.json, npm scripts, folder structure, README excerpt) into an initial `Map - ` note — context from the very first session,
- asks *"Configure Claude to use Alexandria automatically?"* and writes the usage rules into `CLAUDE.md` (`--auto` / `--manual` to skip the question).

After `init` there is nothing to reconnect, ever. Important: hooks load **when a session starts** — open a *new* agent session in that folder (an already-open one won't see them).

## Daily usage — examples

### Search by meaning, not keywords

```bash
$ ale search how do I publish my app to the google store

Flutter release deployment (Alexandria/notes/2026-07-09-deploy.md, note) ● high relevance
  To publish on Play Store: keystore outside git, key.properties,
  flutter build appbundle. Always sign with the production key.
```

The query shares zero keywords with the note ("google store" → "Play Store"). More:

```bash
ale search cors error in the api        # finds your fix from months ago
ale search "architecture decision" -k 10
ale search auth --expand                # also pulls notes CONNECTED to the results (graph)
```

The `● high/medium/low relevance` label is relative to the best hit — trust it over the raw number.

### Save notes manually

```bash
# Quick note
ale add "Prisma setup" -c "Singleton in src/lib/prisma.ts using globalThis" -t "prisma,db"

# From a file in your project (or a pipe)
ale add "Q3 architecture decisions" --file DECISIONS.md
cat DECISIONS.md | ale add "Q3 architecture decisions"

# With [[wikilinks]] to connect knowledge
ale add "Vercel deploy" -c "Region cdg1, see [[Prisma setup]]" -t deploy
```

(Automatic capture via hooks already does this in every Claude Code session — `add` is for extra knowledge.)

### Control what spends tokens (`ale toggles`)

Every token-spending behavior is opt-out — before or after installing (the config is global, independent of the vault):

```bash
$ ale toggles          # interactive menu: each toggle with its real approximate cost
ale init --off architect.enrich,digest.map   # disable from the start
ale config set tokens.solutionCache false    # scriptable, one by one
```

The toggles: Protocol manifest (~6% of the session digest), Architect enrichment in `plan_create` (~+90 tokens/plan), solution cache (up to ~500 tokens/prompt), per-prompt semantic search (the **main saving mechanism** — up to ~1500 tokens/prompt, disabling it defeats the point), project map in the digest (up to ~1000 tokens), title index (~200 tokens), and background index rebuild at session close (costs no tokens). All on by default; nothing changes unless you touch them.

### Deep project context (`ale scan`)

`ale init --project` already runs it; re-run anytime the project changes:

```bash
$ ale scan
✓ API: 12 rutas · Env: 8 vars (solo nombres) · Datos: 5 · Convenciones: 4 · .gitignore ✓
```

Four read-only scanners write compact notes (one line per entry) that the agent receives **only when relevant** (per-prompt semantic search — the session digest doesn't grow):

- **`API - `** — App Router routes with HTTP methods, Pages Router handlers, `"use server"` actions, Express/Hono routes.
- **`Env - `** — environment variable **NAMES only, never values** (from `.env.example` / `.env` / `.env.local`).
- **`Datos - `** — data schema parsed from files (prisma models, drizzle tables, `CREATE TABLE` in migrations) — no DB connection.
- **`Convenciones - `** — package manager, monorepo, TS strict, import aliases, framework.
- **`Flujo - `** — what a request goes through: `GET /api/x → auth: requirePermiso(...) → datos: getX, createX → audits`, plus what the middleware protects. The others say what exists; this one says how it connects.

It never touches your source code, and it guarantees the vault (and personal configs) are gitignored before writing — your notes never reach a shared repo, even if you never ran `ale init`.

### Create a plan from a file

Instead of typing a whole plan into the terminal, keep it as markdown in your repo:

```bash
$ ale plan PLAN-migration.md
✓ Plan created: notes/2026-07-11-plan-migrate-to-postgres-17.md
  DoD detected: 3 criteria — backup verified · migrations run clean · app responds on staging
```

Checkbox lines (`- [ ] ...`) become the Definition of Done. The agent sees it as an **open plan** at the start of the next session and resumes it with `task_verify`.

### View the knowledge graph

**The graph maintains itself** — every vault change (automatic capture, `ale add`, reindex) regenerates `/grafo.html`. Double-click it anytime.

```bash
ale graph                  # LIVE viewer in your browser: auto-refreshes every 3s
ale graph --out other.html # static copy elsewhere (optional)
```

Nodes = notes (size = connections, color = type: 🟪 plans, 🟦 verifications, 🟨 lessons, 🟩 sessions…), solid lines = `[[wikilinks]]`, dashed = semantic similarity. Auto-fit, hover highlights neighbors, click shows details, Obsidian-style **type filters** (prompts hidden by default — they're visual noise). The graph shines from ~20-30 notes on — it's cumulative by design.

**In Obsidian**: open the vault folder as a vault and use the native graph view — notes carry `aliases` in their frontmatter so Obsidian resolves the `[[wikilinks]]`. Old notes are migrated automatically on the next reindex. Note: `grafo.html` is for your browser; Obsidian doesn't render HTML.

### Measure what it saves you

```bash
$ ale stats

🧠 Vault: /Users/you/Alexandria (global)
  Notes: 142 {"note":80,"prompt":38,"session":22,"map":2}
  Indexed chunks: 385 · Connections: 91
  Semantic search: active

🏛️  Protocol
  Plans: 6 (1 open) · Verifications: 14 (86% ✓)
  Lessons: 9 (4 reused — each reuse = a debug session that never happened)

📊 Measured (facts, not estimates)
  Context injections: 57
  Solution cache hits: 12 (~9,400 tokens — clearest win: solutions not re-derived)
  Injected tokens (cost): ~21,300

💰 Estimated savings (band, NOT audited)
  ~63,900 – 170,400 tokens
  Assumption: injected context replaces re-reading 3–8× its size in files. Not a
  measurement — the real number depends on what you'd have re-read without the vault.
```

### Audit your vault's health

```bash
$ ale audit

🏛️  Alexandria Protocol audit
  Plans: 2 (2 open, 0 completed, 0 failed)
  Verifications: 1 (1 failures) · Lessons: 1
  ⚠ Notes without connections (invisible to vault_related): 1
    - Plan - Migrate to Postgres 17 → connect it with vault_link or [[wikilinks]]
```

Flags plans without a Definition of Done, failures without lessons, and orphan notes.

### Maintenance (you rarely need it)

```bash
ale doctor                    # checks & repairs: model, hooks, MCP, index
ale reindex [--force]         # incremental by default
ale consolidate [--days 45]   # ARCHIVES old unused prompts to Alexandria/archive/
                              # — out of the graph and injection, still searchable: nothing is ever lost
ale uninstall                 # removes hooks; your notes stay untouched
```

Every command self-repairs before running: missing model → downloads it; stale index → updates it.

## Supported agents

```bash
ale agents                 # list with auto-detection (● = found on your machine)
ale agents all             # register the MCP server in all of them
ale agents cursor,gemini   # just these
```

| Agent | Config written | Per-project |
|---|---|---|
| Claude Code | `.mcp.json` / `claude mcp add` + hooks | ✓ |
| Cursor | `~/.cursor/mcp.json` / `.cursor/mcp.json` | ✓ |
| OpenCode | `opencode.json` | ✓ |
| Devin CLI (Cognition) | `.devin/mcp_config.local.json` | ✓ |
| Windsurf (legacy) | `~/.codeium/windsurf/mcp_config.json` | — |
| Cline | `cline_mcp_settings.json` (VS Code) | — |
| Codex CLI | `~/.codex/config.toml` | — |
| Gemini CLI | `~/.gemini/settings.json` / `.gemini/settings.json` | ✓ |
| VS Code (Copilot) | `mcp.json` (profile) / `.vscode/mcp.json` | ✓ |
| OpenClaw | `~/.openclaw/openclaw.json` | — |
| Hermes Agent (Nous) | `hermes mcp add` / `~/.hermes/config.yaml` | — |

Registrations are **idempotent merges** — your other MCP servers are never touched.

**Note**: automatic capture via hooks (session digest, per-prompt injection, session save on close) is Claude Code-only — other agents don't have a hook system. There, knowledge flows through the MCP tools, which the agent uses on its own (the protocol instructions travel inside the tool descriptions).

## How it works

```
AI agent session
  │
  ├─ SessionStart ──► injects digest: protocol manifest + project map + open plans   (hooks, Claude Code)
  ├─ Every prompt ──► local hybrid search → injects only what's relevant             (hooks, Claude Code)
  │                   └─ near-identical prompt already solved → injects the solution (cache)
  ├─ MCP tools ─────► vault_search · vault_save · vault_related · vault_link         (all agents)
  │                   plan_create · task_verify · lesson_extract                     (the Protocol)
  └─ Stop/PreCompact► saves the session outcome into the vault                       (hooks, Claude Code)
                                │
                        /Alexandria/*.md   ← markdown, [[wikilinks]]
                        /.vault/                    ← index (regenerable)
```

- **Hybrid search**: local embeddings (transformers.js, multilingual e5-small) + BM25, combined with RRF, boosted by recency, usage, and note type (lessons/solutions rank highest).
- **Incremental index**: only re-processes notes whose mtime changed. The graph is never rebuilt from scratch.
- **Deduplication**: near-identical prompts don't create new notes — they add `hits` (and climb the ranking).
- **About scores**: the e5 model compresses cosines (~0.76–0.86 even for unrelated topics); the *ranking* is what's reliable, hence the relevance label.

## Command reference

| Command | What it does |
|---|---|
| `ale init [--project] [--path ] [--agents ] [--auto\|--manual] [--no-protocol] [--portable]` | Installs everything: vault, hooks, MCP, .gitignore, project scan, CLAUDE.md. `--portable` writes an npx-based MCP command safe to commit for teams |
| `ale scan` | Deep project context: API routes, env var **names**, data schema (file parse), conventions → compact notes (adaptive cap ≤200 entries, fair sampling in monorepos). Read-only; ensures .gitignore |
| `ale toggles` | Interactive menu to enable/disable every token-spending behavior, each with its real approximate cost. Works before or after install; scriptable via `ale init --off ` |
| `ale skills:evolve` | Generates/updates a **living skill for the project** from what the vault knows (stack, conventions, app flow, lessons). Always shows a diff and asks before writing |
| `ale agents [ids] [--project]` | List agents / register the MCP server |
| `ale search  [-k n] [--expand]` | Hybrid search; `--expand` pulls graph neighbors. With the Protocol on, appends the **chain** (plan + verification + lesson) connected to the top hit |
| `ale add  [-c text] [--file ] [-t tags]` | Save a note (inline, from file, or stdin) |
| `ale plan  [--title t]` | Create a Protocol plan from a .md/.txt file (checkboxes → Definition of Done); surfaces similar past plans + quality hints |
| `ale graph [--out file.html] [--no-open]` | Live local graph viewer |
| `ale audit` | Protocol health: plans without DoD, failures without lessons, orphan notes |
| `ale stats` | Notes, connections, protocol metrics, estimated tokens saved |
| `ale config   [value]` | Configuration (e.g. `protocol` true/false) |
| `ale skills [-y] [--project]` | Recommends & installs Claude skills — semantic (e5) + keyword detection over your vault. Local source configurable with `ale config set skills.repo `; otherwise installs from skills.sh |
| `ale reindex [--force]` | Reindex (incremental by default) |
| `ale consolidate [--days n] [--dry]` | Archive old unused prompts — never deletes |
| `ale doctor [--project]` | Check & repair: model, hooks, MCP, index |
| `ale uninstall [--project]` | Remove hooks (notes stay untouched) |
| `ale --vault  ` | Run any command against another vault |

`alexandria` works as an alias of `ale`.

## Privacy & security

- **Ev

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [UreckChan](https://github.com/UreckChan)
- **Source:** [UreckChan/alexandria](https://github.com/UreckChan/alexandria)
- **License:** MIT
- **Homepage:** https://alexandria.ureck.dev

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ureckchan-alexandria
- Seller: https://agentstack.voostack.com/s/ureckchan
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.