Alexandria
Agent memory server with tiered maturity, hierarchical clustering, spreading activation, and progressive recall. Runs as a persistent MCP service backed by embedded SurrealDB.
Power your agent
การติดตั้งจากผู้เผยแพร่ ไม่ใช่เอนด์พอยต์ของ PlugMCP
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดจากผู้เผยแพร่
Agent memory server with tiered maturity, hierarchical clustering, spreading activation, and progressive recall. Runs as a persistent MCP service backed by embedded SurrealDB.
Long-term memory for AI agents. MCP server with local embeddings, heat-based recall, and hierarchical clustering on embedded SurrealDB.
A2).derived_from and extracted_from edges. relates_to, supports and contradicts exist in the schema but nothing in production writes them yet; auto-linking them is planned v0.3 workalexandria dream pass can be reviewed (or run on demand) againstextracted_from lineage.surql files with forward-only migration runner# Build and install
cargo install --path crates/alexandria
# Create config
mkdir -p ~/.config/alexandria
cat > ~/.config/alexandria/config.toml << 'EOF'
[server]
transport = "http"
port = 3000
[embedding]
model = "sentence-transformers/all-MiniLM-L6-v2"
device = "cpu"
# Tokens of each memory the search sees. 256 is the default and what has been measured;
# up to 512 is experimental. A database created before this key existed is stamped 128 and
# needs `alexandria migrate-embeddings` before it boots at the default. Locked on first run
# and only ever raised.
max_tokens = 256
EOF
# Run
alexandria
First run with the default MiniLM configuration downloads the embedding model from HuggingFace Hub (~80MB).
The exact model ID ibm-granite/granite-embedding-311m-multilingual-r2 selects native Rust Burn inference: 768D FP32, CLS pooling, and a default/cap of 8192 tokens. CPU is the default; explicit rocm[:index] or vulkan[:index] needs the corresponding binary Cargo feature (granite-rocm or granite-vulkan). A missing backend/device fails startup rather than falling back. Serving uses exact input lengths and a bounded serial worker.
Build the requested backend explicitly; changing embedding.device cannot add it to an existing binary:
cargo build --release --locked -p alexandria # CPU
cargo build --release --locked -p alexandria --features granite-rocm # ROCm
cargo build --release --locked -p alexandria --features granite-vulkan # Vulkan
GPU driver/toolchain availability is a separate requirement; the shipped Alpine image builds
CPU-only and contains neither GPU runtime nor model artifacts. For container CPU opt-in, mount
the exact verified local artifact directory read-only and set artifact_dir to its in-container
path; ensure the service UID can read it. Granite's XDG artifact cache is separate from HF_HOME
(the MiniLM cache); persist it explicitly if using it. No driver, model or cache is supplied by
changing a device selector.
MiniLM remains the installation default. The checksum-pinned Granite pack is not published yet: opt-in startup requires verified local artifacts or an already verified cache. A local directory supplies bytes, not replacement checksums. Publication is gated by tokenizer licensing review as well as release approval; the Gemma3-derived tokenizer is not covered by the weights' Apache-2.0 license alone.
Existing databases cannot be relabelled Granite. Stop the source server, configure the target model/budget while keeping the source data path, then use alexandria migrate-embeddings --output-data-dir /path/to/new-target. --resume continues an owned target or reports a completed one without loading weights. The original source is retained; model, budget and data path cutover (and paired rollback) remain manual. The legacy in-place command refuses Granite and owned migration targets. Do not change live model/path settings or reuse MiniLM cutoff calibration as proof of Granite quality. See embedding configuration and the artifact curator.
Granite's cosine scale differs from MiniLM's. In the small public synthetic pilot, retaining a MiniLM-style floor returned results for every unanswerable query; higher floors traded those errors for lost valid passages. This is not sufficient evidence to change defaults. See Granite test data and release gates for the multi-relevant pilot, native evaluation procedure and remaining calibration requirements.
alexandria with no arguments starts the server. The three subcommands are maintenance tools
that run once and exit.
The legacy in-place command, benchmark and dream open the data dir directly, and SurrealKV
is single-writer, so the server has to be stopped first. alexandria dream refuses a held
store before any job runs; dream --help states the constraint too. The separate-target
migration instead locks the existing source LOCK read-only and never opens its storage
engine; it opens only the copied target. Initial source-lock interoperability is admitted on
Linux only. Keep the adjacent source-manifest receipt with the target, especially while it is
unfinished. bench-retrieval can instead run against a copy of the data dir via
ALEXANDRIA_DATA_DIR, which keeps the server down only for a cp. It is not read-only: like
server boot it checks the embedding-model lock (refusing on a mismatch) and defines the HNSW
index if it is missing. alexandria dream needs neither the model nor the index — it reads the
stored vectors, heat and confidence. It validates stored embedding readiness/identity before
schema or job writes and refuses unfinished or corrupt migration targets, without loading a
provider or requiring the configured model to match. --max-rows N overrides dreaming.max_rows_per_run
for that invocation only, without touching the config file.
Tool and parameter descriptions are written directively ("call this proactively when…") because that measurably changes how often client LLMs reach for them unprompted.
Passing session_id to store_memory groups memories under a caller-chosen handle, and the session
is created on first use. retrieve_memories with session_id restricts ranking to that session's
memories, get_session reads the whole session back, list_sessions finds a session whose id you
don't have, and finalize_session records its summary.
See docs/session-memory.md for the data model and current limitations.
Reminders are scheduled messages — "remind me", "check the deploy at 3pm" — delivered into the
agent's context on the next interaction after they come due. There is no background timer: due-ness is
evaluated at query time, so delivery is lazy, transport-agnostic, and survives server downtime. The
cost of that design is that nothing reaches anyone until a client asks: the pi companion calls
check_reminders once per prompt and additionally notifies the human, and that client-side step is
where "and the user" actually lives — a client that never calls the tool receives nothing.
set_reminder validates schedules at set time and echoes the parsed next fire times for confirmation;
check_reminders delivers and consumes them, one-way. Reminders target the global
context or a specific project, and a project-targeted reminder that is overdue by at least
[reminders].escalation_hours escalates to global delivery — nothing is silently lost. Overdue
items are also surfaced read-only, capped and oldest-due first, in the due_reminders array of
retrieve_memories and recall responses.
Recurring schedules are evaluated as wall clock in [reminders].timezone, so a daily 09:00 stays 09:00
local across a DST change: a time the spring-forward gap removed does not fire that day, and a time a
fall-back fold repeats fires once, on its first pass. The cron escape hatch carries two dialect
surprises — numeric days of week are 1=Sunday (write day names), and a restricted day-of-month ANDs
with a restricted day-of-week instead of ORing as Vixie cron does — so set_reminder puts a warning
in the response when it recognizes the second one.
A memory server is only useful if agents reach for it unprompted. Alexandria nudges this at three levels:
instructions — the server advertises usage guidance (when to read vs. write memory
and how reminders get delivered) in its initialize response via ServerInfo.instructions.
Any MCP-compliant client can surface this to the model. Tool descriptions are also written
directively ("call this proactively whenever...") rather than just describing mechanics.contrib/pi/skills/alexandria-memory/
(Pi) and contrib/claude/skills/alexandria-memory/
(Claude Code) document concrete trigger conditions and tool choice guidance, mirroring how other high-usage
MCP tools ship skills alongside themselves.contrib/pi/extensions/alexandria/
runs in both directions. On before_agent_start it calls retrieve_memories for every prompt and
injects hits above a similarity threshold, and calls check_reminders to deliver whatever is due,
so the agent never has to decide to check memory or wait for a timer the server doesn't run. On the
write side it adds heuristic detectors (corrections, stated preferences, error→resolution pairs)
that store without being asked, plus an LLM extraction pass at session_shutdown for durable facts
both the agent and the heuristics missed. This trades latency and potential noise for guaranteed
recall and much denser capture; recall, store, and reminders each toggle independently. The Claude
Code equivalent is the set of UserPromptSubmit, PreToolUse, and Stop hooks at
contrib/claude/hooks/.Items 2 and 3 are client-side integrations, not part of the MCP server itself — see
contrib/pi/README.md and contrib/claude/README.md
for what they are and how to install them.
When transport = "http", a debug web UI is served alongside the MCP endpoint at
http://<host>:<port>/debug. It is read-only except for one disclosed exception: the Query
Tester's non-dry retrieve run performs spreading activation, so it writes heat exactly as a real
retrieve_memories call does. Tick Dry run for a strictly read-only probe that writes nothing.
/debug) — record counts (facts active/deleted, clusters, edges, raw documents,
sessions), the effective configuration the server is actually running with (retrieval floor,
activation knobs, cluster and heat thresholds, the dreaming scheduler's cadences, live embedding
model and dimensions) shown alongside
what the TOML asked for, rollups for cluster health, sessions finalized/idle, top tags and heat
distribution, and the schema version — applied versus compiled-in, with a mismatch called out/debug/memories) — paginated, sortable search/filter of facts by content and tag,
with include deleted and include quarantined checkboxes; click through to a detail view
showing heat, stability, timestamps, cluster membership, and graph edges. Quarantine is off by
default so the page matches what an agent can retrieve, and this is the operator view for a memory
on that middle rung — hidden from every retrieval path, still present, still reversible. Nothing
in the UI can put a row into quarantine or take it out/debug/clusters) — cluster list with live member counts and depth; drill into
/debug/clusters/{id} for member facts and cohesion. Cohesion is computed from each cluster's stored
centroid, on the detail page and in the dashboard rollup alike, so the verdict matches what
the background maintenance task will actually act on/debug/sessions) — every session with agent, model, derived memory count, start and
last-activity times, and a finalized/active badge; /debug/sessions/{external_id} shows the
summary, tags, and the session's memories. Keyed by the external_id you pass to store_memory(session_id)/debug/graph/{id}) — visualizes a memory's local edge neighborhood: nodes labelled with
content snippets rather than raw record ids (full id and hop distance in the tooltip), colour and
shape by table, edges styled by edge_type with strength banded into width, a legend generated from
those same maps, and click-through to the memory detail page. ?hops=1..3 sets the radius, clamped
server-side; the view caps at 200 nodes and says so when it truncates rather than rendering a
hairball. The backing JSON is at /debug/api/graph/{id}/debug/maintenance) — paginated history of the background scheduler's
writes: cluster splits and merges (source, resulting clusters, members moved), duplicate collapses
and cold-memory demotions, each carrying the run_id of the tick that wrote it, the job that ran,
the disposition and — for a demotion — the confidence it replaced. ?run= narrows the whole page
to one run, which is how a pass gets reviewed as a unit or reversed as one; the run ids written by
alexandria dream start run-cli-, so a manual pass is separable from a scheduler tick in that
same filter. The filter is carried
across pagination, and the form is a GET to the same route (the panel stays read-only). The only way to audit why the corpus changed since you last
looked. The heat sweep deliberately writes nothing here: it changes ranking by nothing, so an audit
trail for it would be hundreds of rows an hour recording that nothing happened./debug/query, POST /debug/query/run) — run retrieve_memories/recall live
against the real embedding model to sanity-check retrieval quality, with optional session_id
scoping and a Dry run checkbox. Results report the effective min_similarity floor, list what
that floor dropped, whether spreading activation fired and on which top-N, and carry a measured
score-band legend so a similarity number can be read without a rulerAll browser assets (htmx, vis-network) are vendored into the binary and served from
/debug/assets/{name}, so the UI loads nothing from a CDN and works fully air-gapped.
The debug UI has no authentication and is intended for a trusted network boundary (same posture as the unauthenticated MCP endpoint) — do not expose it on a public interface without putting a reverse proxy/auth layer in front of it. That tradeoff is defensible because nothing on the page mutates except the one disclosed heat write above; if a mutating route is ever added, this paragraph is the thing that has to change first.
Two guards in debug/guard.rs narrow that boundary. Every non-GET request that arrives with
Sec-Fetch-Site: cross-site or cross-origin is refused with 403, so a hidden auto-submitting
form on a page you visit cannot drive the Query Tester into writing heat on an attacker-chosen
query — this check is unconditional and needs no configuration. Separately, binding to loopback
is not by itself a security boundary: DNS rebinding lets a remote page resolve its own domain to
127.0.0.1 and then read /debug/sessions — session summaries and tags — as same-origin. Setting
allowed_hosts in [server] now guards the debug UI as well as /mcp, accepting a Host either
with or without its port, and requests with no Host at all are refused while it is armed. The
Host half is opt-in, so the shipped default of ["*"] behaves exactly as before; prefer setting
allowed_hosts explicitly (for example ["localhost", "127.0.0.1"]) over leaving the wildcard,
especially when host = "0.0.0.0".
Upgrading from a build on SurrealDB 3.2 is one-way: stop the server and copy the data dir
first ($XDG_DATA_HOME/alexandria/data by default, /data/db in the container). A 3.3 build
opens a 3.2 store, but ordinary use soon writes data 3.2 cannot read. Listing a cluster or session
with 64 or more members makes 3.3 rewrite that table's definition, and every store_memory lists
every cluster. How close that leaves a given deployment depends on its largest cluster, so check
yours before upgrading — /debug/clusters prints the member count per cluster. Measured on a
1897-memory store: 1474 clusters ranging from 1 to 51 members, median 1, 1277 of them singletons,
so nothing is at the threshold yet; merge is the job that grows the top of that distribution
toward 64. Writes to the vector index leave entries 3.2 cannot decode. A 3.2 build started on
the result still boots, then fails cluster queries and vector search, or returns empty member lists
with no error. Restoring the copy is the only way back, as SurrealDB's own
upgrade notes say.
# ~/.config/systemd/user/alexandria.service
[Unit]
Description=Alexandria Agent Memory MCP Server
After=network.target
[Service]
ExecStart=%h/.cargo/bin/alexandria
Restart=on-failure
RestartSec=5
Environment=RUST_LOG=info,rmcp=warn
[Install]
WantedBy=default.target
rmcp=warn drops the per-request transport chatter (~6 lines per call at info) while keeping Alexandria's own logs.
journald has no per-unit size cap, so bound the journal globally if you want to limit history:
# /etc/systemd/journald.conf.d/alexandria.conf
[Journal]
SystemMaxUse=200M
MaxRetentionSec=1month
sudo systemctl restart systemd-journald
systemctl --user daemon-reload
systemctl --user enable --now alexandria
journalctl --user -u alexandria -f # tail logs
The Containerfile at the repo root builds a musl-targeted release binary and
ships it on a minimal Alpine runtime as a non-root user (alexandria, uid 10001). musl is linked
dynamically — the build clears crt-static because proc-macro and cc-based crates misbehave with
the musl target's default static CRT. Build and run:
docker build -f Containerfile -t alexandria .
docker run -d --name alexandria \
-p 3000:3000 \
-v alexandria-data:/data \
alexandria
The image defaults to HTTP transport on 0.0.0.0:3000 via ALEXANDRIA_SERVER_* env vars, with
ALEXANDRIA_DATA_DIR=/data/db. Everything stateful lives under the /data volume:
Override config per-container with env vars (see docs/configuration.md) or
mount a TOML file and point ALEXANDRIA_CONFIG at it. Note the server binds 0.0.0.0 in the
image and the MCP endpoint plus debug UI are unauthenticated — publish the port only behind a
reverse proxy or on a trusted network. The debug UI needs no outbound network: its browser assets are
vendored into the binary, so a container with no egress still renders it (the first-run HuggingFace
model download is the only thing that still needs the internet).
{
"alexandria": {
"type": "http",
"url": "http://127.0.0.1:3000/mcp"
}
}
Or via stdio (for single-session use):
{
"alexandria": {
"command": "alexandria",
"args": []
}
}
claude mcp add --transport http --scope user alexandria http://127.0.0.1:3000/mcp
# optional: client-side skill (content-parity with contrib/pi, using Claude Code's mcp__alexandria__<tool> names)
cp -r contrib/claude/skills/alexandria-memory ~/.claude/skills/
# optional: auto-recall hook (see contrib/claude/README.md for the settings.json snippet)
cp contrib/claude/hooks/alexandria-recall.sh ~/.claude/hooks/
Pi 0.99 and later read MCP servers from ~/.pi/agent/mcp.json (or a trusted project's
.pi/mcp.json) with built-in support, so a long-running Alexandria is a one-entry change there:
{
"mcpServers": {
"alexandria": {
"url": "http://127.0.0.1:3000/mcp",
"exposure": "direct"
}
}
}
"exposure": "direct" is the setting that matters for a memory server you expect to be used on every
task. Pi's default is codemode, which keeps the tools out of the model's declared tool list and makes
them reachable only from JavaScript the model writes for its codemode tool; deferred is the middle
option, where tool_search loads matches on demand. An agent that has to remember to look for the
memory tools tends not to, so declare them.
Pi connects at session start, retries transient HTTP failures twice, and reconnects a dropped server on
the next call — there is no idle-eviction or keep-alive knob to tune (the earlier lifecycle and
settings.idleTimeout fields belong to the third-party pi-mcp-adapter extension, which reads
mcp-adapter.json and is not needed on 0.99+). Check the wiring with pi mcp list; for servers that
use OAuth, pi mcp login <server>. If a running session does not see a new or edited server, run
/reload or start a new session.
Pi names these tools mcp__<server>__<tool> — mcp__alexandria__store_memory,
mcp__alexandria__retrieve_memories, and so on — which is the form the skill uses. The companion's
auto-store detectors match on the tool-name suffix, so they work with either naming convention.
Then optionally add the client-side nudges — see
contrib/pi/README.md.
Config loads with precedence: defaults → $XDG_CONFIG_HOME/alexandria/config.toml → ALEXANDRIA_CONFIG env → individual env vars. Data defaults to $XDG_DATA_HOME/alexandria/data.
Legacy ~/.alexandria/config.toml is used as a fallback when the XDG config file does not exist yet. The data directory has no such fallback: it defaults to $XDG_DATA_HOME/alexandria/data, and an explicit data_dir still pointing at the old location only produces a warning telling you to move it.
Reminder delivery is configured by the [reminders] section: timezone (IANA name, empty = system-local) governs naive datetime input and pattern/cron evaluation, and escalation_hours controls overdue escalation to global delivery.
The Pi companion extension (recall / store / reminders) has its own config at $XDG_CONFIG_HOME/alexandria/client.toml.
See docs/configuration.md for all options, client config reference, and migration instructions.
crates/
├── alexandria/ # Binary — config loading, transport setup, main loop, dreaming scheduler
├── alexandria-mcp/ # MCP tool handlers + debug web UI (askama templates, vendored assets)
├── alexandria-engine/ # Core algorithms — clustering, heat, recall, import, activation
├── alexandria-pipeline/ # Embedding providers (legacy Candle + native Granite/Burn)
└── alexandria-storage/ # SurrealDB connection, models, repos, schema migrations
contrib/pi/ # Optional client-side pi integrations (skill + extension), not shipped
Data flows: MCP request → server handler → engine algorithm → storage repo → SurrealDB
Crate boundaries are held by convention, not tooling: storage owns nearly all SurrealDB access (one
inline query remains in an alexandria-mcp handler, and the binary's maintenance loop reads cluster
directly), engine is pure algorithms with no DB or async, pipeline abstracts embedding providers
behind one trait, and alexandria-mcp is the crate whose purpose is joining engine to storage — the
binary also sees both, since it wires them together at startup. See AGENTS.md for the full
set.
just recipes mirror what CI runs — install just if you don't have it:
just # list every recipe
just ext-install # ONE TIME per checkout: npm ci --ignore-scripts for the pi companion (node_modules/ is gitignored)
just test # cargo test --locked --workspace --all-features (hermetic Granite tests; native runs ignored)
just test-cpu # CPU-only workspace tests, including uncompiled-GPU admission guards
just cpu-deps # CPU binary graph rejects known GPU backend/native dependencies
just artifact-ci # standalone curator fmt/clippy/hermetic tests/cargo-deny, no official model conversion
just eval-test # dependency-free Python scorer tests; no inference
just ext-test # pi companion: npm run typecheck + npm test (needs ext-install first)
just lint # clippy, warnings as errors (matches CI)
just fmt-fix # rustfmt
just ci # CPU graph + both Rust feature sets + curator/scorer/companion/policy/assets
just run # run the server locally (prefix with RUST_LOG=debug for verbose logs)
just verify-assets # check crates/alexandria-mcp/assets against SHA256SUMS
just vendor-assets # re-download those assets and re-verify the checksums
just ci runs ext-test, so just ext-install is a prerequisite on a fresh checkout — without it
the "full pre-push check" fails in npm before it reaches anything Rust. Bare just lists the recipes
this block omits (fmt, check, clean, test-all, deny).
Use a stable toolchain. Recent nightlies fail to build diskann-wide (a SurrealDB
transitive dependency) on Apple Silicon with a trait-inference error in its NEON intrinsics,
which looks like a breakage in this repo but isn't.
Install the git pre-commit hook (fmt check + clippy) once per clone:
just install-hooks
deny.toml gates licenses and known advisories via cargo deny, which runs as its own
CI job. .github/workflows/ci.yml runs five jobs — fmt, clippy,
test, extension (displayed as "Pi companion": the extension's typecheck and tests) and deny — on
PRs against any branch and pushes to main; it does not call just ci, so a new local gate has to be wired
into the workflow as well. just verify-assets runs in the test job ahead of just test.
Curator fmt/Clippy/tests/dependency-policy gates run in the corresponding existing jobs; the
test job also runs CPU-only workspace and Python scorer tests. Optional GPU backend compilation
is not a hardware acceptance pass: native GPU tests require explicitly verified local assets
and supported hardware. No official Granite model download/conversion runs in ordinary CI.
The test job disables debug info (CARGO_PROFILE_DEV_DEBUG=0,
CARGO_PROFILE_TEST_DEBUG=0) and incremental compilation (CARGO_INCREMENTAL=0) to
fit both feature sets and the curator on the hosted runner. Optimization levels,
debug assertions, overflow checks and test coverage are unchanged; CI backtraces
have less detail. Local builds retain their normal debug settings.
During dependency refreshes, retain the resolved SurrealDB and Burn families in addition to their exact top-level pins: pinning the SurrealDB SDK alone does not freeze its internal engine crates. Engine changes need the deployment/storage-format review described below; inference-stack changes need artifact and vector validation.
.github/workflows/container.yml additionally builds the Docker
image and boot-tests it — waits on /debug, then performs a real MCP initialize handshake against
/mcp — but only when a change touches the Containerfile, .dockerignore, the manifests, or
crates/**. A green CI run therefore says nothing about the image, and vice versa.
Distributed under AGPL-3.0-or-later — see LICENSE and the license field in
Cargo.toml. AGPL rather than MIT is deliberate: Alexandria is a long-running
network service, and the AGPL source-availability clause closes the network-service loophole that
MIT would leave open for anyone hosting a modified fork.
Long-term memory for AI agents. MCP server with local embeddings, heat-based recall, and hierarchical clustering on embedded SurrealDB.
เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
Alexandria ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-10-28 Long-term memory for AI agents. MCP server with local embeddings, heat-based recall, and hierarchical clustering on embedded SurrealDB.