spoor
OfficialOptional integration with OpenAI as an embeddings provider for hybrid search, as an alternative to the built-in local embedding model.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Spoor Memory
Self-hosted shared memory for AI coding agents and the team that works with them.
Coding agents forget everything between sessions, and each developer's agent learns the same lessons separately. Spoor gives a whole team one memory per project: agents read and write it over MCP at a cost of about 1,500 tokens per session, and people browse, edit and review the same content in a web UI. What one agent learns on Monday, every teammate's agent knows on Tuesday.
It runs as one Docker deployment (the app image plus Postgres with pgvector) on your own server. Nothing leaves it unless you turn on an external embedding provider.

Contents
Related MCP server: onememory
What you get
Four spaces per project.
memories(atomic claims: decision, fact, procedure, observation),decisions(numbered ADRs,ADR-0001),docs(long-form pages) andlibrary(guides written by people, which agents read but cannot change). Every item is Markdown with YAML frontmatter, versioned in append-only revisions.A shared space for the whole organisation. Every project's agents read it; only people write it.
Cheap for agents. A budgeted digest at session start (about 1,500 tokens by default), hybrid search (full text plus vectors, reciprocal rank fusion), short handles such as
m42instead of ids, one short text block per tool result.Links and a map. Items link through
[[wikilinks]]and typed relations (refines,supports,depends_on,conflicts_with). Each project has an interactive graph, and Spoor suggests links between related items.Self-cleaning. Memories nobody uses or verifies go stale after 30 days and are archived 90 days later. Observations expire. Near-duplicates are flagged. People work through a review queue.
ADRs kept in step with the repository. Decisions an agent records are drafted into
docs/adr/as proposed ADRs on the developer's machine. ADR and doc files edited in the repo are pushed to Spoor.Local embeddings. A multilingual model runs inside the app container, with no API key. OpenAI, Voyage or your own Ollama server are optional.
Access control and audit. Users, invites, three project roles (admin, editor, viewer), per-project tokens, an audit log and a 14-day log of agent requests.
Export and import of a project as a zip of Markdown files with full history.
Spoor is single tenant by design: one deployment serves one organisation with many isolated projects.
AI tool integration
Each project has one MCP endpoint, https://<your-server>/p/<project>/mcp (Streamable HTTP, bearer token). Any MCP client
that can send an Authorization header can use it.
Supported tools
tool | memory tools (MCP) | digest at session start | ADR and doc mirror | setup |
Claude Code | yes | automatic (hook) | automatic (hooks) |
|
Cursor | yes | the agent calls | manual ( |
|
Codex | yes | the agent calls | manual |
|
Gemini CLI | yes | the agent calls | manual |
|
other MCP clients | yes, with Streamable HTTP and a bearer header | the agent calls | manual | endpoint and token |
Claude Code is the fully integrated client. The others get the same nine tools; they have no hooks, so a block in
AGENTS.md (written by spoor init) tells the agent when to read and write memory. A client that reads a different
rules file needs that block copied into it.
The nine MCP tools
tool | kind | what it does |
| read | the budgeted digest for the files being touched and an optional query |
| read | hybrid keyword and meaning search over memories, ADRs, docs and library pages |
| read | up to five items in full, optionally with their linked neighbourhood |
| write | record one durable fact, procedure or observation |
| write | record a decision; an ADR is drafted from it later |
| write | create or update a long-form doc |
| write | replace an outdated memory with a new claim |
| write | add or remove a typed link between two items |
| write | confirm memories are still true |
Tokens belong to one user and one project and follow that user's role: editors and admins get all nine tools, viewers and read-only tokens get the three read tools.
Claude Code
spoor login (see below) sets up the MCP server and three hooks:
Session start: the project digest is added to the context. It holds library pages, pinned items, recent accepted decisions, items anchored to the files you are changing, and recently verified items.
After a Write or Edit of an ADR or a mirrored doc: the file is pushed to Spoor.
Turn end: decisions recorded with
spoor_decideare drafted intodocs/adr/asstatus: proposed, by a small model on your machine. If the session changed files and recorded nothing, the agent is asked once to record its decisions.
An optional fourth hook, prompt recall (spoor init --recall on), looks at each prompt you send and adds the few
memory items that clearly match it, so the agent sees them without having to search. It is off by default and adds
nothing for prompts that match nothing.
Hooks never block a session: if the server is down they print one notice and exit.
Other clients
Create a token in the web UI (Project, Tokens) and put it in an environment variable, one per project
(SPOOR_TOKEN_ACME for the project acme). Never commit the token.
Cursor, .cursor/mcp.json:
{
"mcpServers": {
"spoor": {
"url": "https://spoor.example.com/p/acme/mcp",
"headers": { "Authorization": "Bearer ${env:SPOOR_TOKEN_ACME}" }
}
}
}Codex, .codex/config.toml in the repo (trusted projects only) or ~/.codex/config.toml:
[mcp_servers.spoor-acme]
url = "https://spoor.example.com/p/acme/mcp"
bearer_token_env_var = "SPOOR_TOKEN_ACME"Gemini CLI, .gemini/settings.json:
{
"mcpServers": {
"spoor": {
"httpUrl": "https://spoor.example.com/p/acme/mcp",
"headers": { "Authorization": "Bearer $SPOOR_TOKEN_ACME" }
}
}
}Every project also serves a public, secret-free install page at https://<your-server>/p/<project>/install.md with these
snippets filled in. Details: docs/agent-guide.md.
The web UI
The web UI is where people read, correct and administer what agents write. Open the server's URL in a browser and log in.
Dashboard. Counts per space, what waits for review, agent activity, and a preview of the digest agents receive.
Items. Each memory, decision, doc and library page renders as Markdown with its tags, anchors (the repo paths it applies to), links, backlinks and suggested links. Edit in a Markdown editor with live preview; every save is a revision with a diff.

Search. The same hybrid keyword and meaning search agents use, across the project and the shared space.

Map. The project as a graph of items and links, with filters by space, lifecycle and link kind, a focus mode for one item's neighbourhood, and counts of unlinked items and dangling references.

Review queue. Stale and archived items, expiring observations, conflicts and possible duplicates, with bulk verify and archive.
Administration. Members and roles, invites (a copyable link, no email server needed), tokens, device approval for
spoor login, project settings (digest budget, cleanup periods, embedding provider), export and import, the audit log, the
agent request log, and instance pages for status, usage and background jobs.
Full tour: docs/user-guide.md.
Install the server (Docker Compose)
You need Docker with the compose plugin (Compose 2.23.1 or later), 2 CPUs and about 2 GB of memory for the app container.
Spoor is published as a ready-made image, ghcr.io/spectado/spoor-memory; you do not need this repository to run it.
1. Create a folder with a docker-compose.yml:
name: spoor
services:
db:
image: pgvector/pgvector:0.8.7-pg17
restart: unless-stopped
environment:
POSTGRES_USER: spoor
POSTGRES_DB: spoor
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env}
POSTGRES_APP_PASSWORD: ${POSTGRES_APP_PASSWORD:?set POSTGRES_APP_PASSWORD in .env}
volumes:
- spoor-pgdata:/var/lib/postgresql/data
configs:
- source: app-role
target: /docker-entrypoint-initdb.d/01-app-role.sh
shm_size: 256mb
healthcheck:
test: ["CMD-SHELL", "pg_isready -U spoor -d spoor"]
interval: 5s
timeout: 3s
retries: 20
app:
image: ghcr.io/spectado/spoor-memory:latest # pin a version such as :0.7.5 in production
restart: unless-stopped
init: true
stop_grace_period: 40s
mem_limit: 2g
depends_on:
db: { condition: service_healthy }
environment:
DATABASE_URL: postgres://spoor_app:${POSTGRES_APP_PASSWORD}@db:5432/spoor
DATABASE_MIGRATE_URL: postgres://spoor:${POSTGRES_PASSWORD}@db:5432/spoor
SPOOR_PUBLIC_URL: ${SPOOR_PUBLIC_URL:-http://localhost:3000}
SPOOR_ADMIN_EMAIL: ${SPOOR_ADMIN_EMAIL:?set SPOOR_ADMIN_EMAIL in .env}
SPOOR_ADMIN_PASSWORD: ${SPOOR_ADMIN_PASSWORD:?set SPOOR_ADMIN_PASSWORD in .env}
ports:
- "3000:3000"
configs:
app-role: # runs once, on an empty volume: creates the runtime database role (no superuser)
content: |
psql -v ON_ERROR_STOP=1 -U "$$POSTGRES_USER" -d "$$POSTGRES_DB" <<SQL
CREATE ROLE spoor_app LOGIN NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION PASSWORD '$$POSTGRES_APP_PASSWORD';
GRANT CONNECT, TEMPORARY ON DATABASE $$POSTGRES_DB TO spoor_app;
GRANT USAGE, CREATE ON SCHEMA public TO spoor_app;
SQL
volumes:
spoor-pgdata:2. Put a .env next to it:
POSTGRES_PASSWORD= # openssl rand -hex 24
POSTGRES_APP_PASSWORD= # openssl rand -hex 24 (a different one)
SPOOR_ADMIN_EMAIL=you@example.com
SPOOR_ADMIN_PASSWORD= # at least 12 characters
SPOOR_PUBLIC_URL=http://localhost:3000 # the URL people will typeThe two database passwords go into connection URLs, so use URL-safe characters only.
3. Start it:
docker compose up -d
curl -s localhost:3000/healthz # {"status":"ok",...} once migrations ran and the model loaded (up to two minutes)Compose starts two containers: db (Postgres 17 with pgvector, data in the spoor-pgdata volume) and app (API, MCP
endpoint and web UI on port 3000). Postgres is the only state. To set any other option from
Environment variables, add it under environment: of the app service.
The full compose file. The docker-compose.yml in this repository is the same setup with every
option wired to .env (see .env.example), a pinned Postgres image and the optional Caddy service for
HTTPS. To use it, or to build the image yourself:
git clone https://github.com/SPECTADO/spoor-memory.git && cd spoor-memory
cp .env.example .env # fill it in; set SPOOR_IMAGE=ghcr.io/spectado/spoor-memory:0.7.5 to pull
docker compose pull && docker compose up -d
# or build from the checkout: leave SPOOR_IMAGE at its default and run
docker compose up -d --buildImage tags at ghcr.io/spectado/spoor-memory:
tag | what it is |
| a release. Use this in production |
| the highest release |
| the newest commit on |
| one specific |
HTTPS. Agents and browsers should reach Spoor over HTTPS. The repository's compose file includes an optional Caddy service that gets a Let's Encrypt certificate (ports 80 and 443 open, DNS pointing at the host):
# .env
SPOOR_DOMAIN=spoor.example.com
SPOOR_PUBLIC_URL=https://spoor.example.com
SPOOR_HTTP_BIND=127.0.0.1
SPOOR_TRUST_PROXY=privatedocker compose --profile caddy up -dFor nginx, Traefik or a load balancer of your own, see docs/operations.md, section 4.
First steps.
Open
SPOOR_PUBLIC_URLand log in withSPOOR_ADMIN_EMAILandSPOOR_ADMIN_PASSWORD. This admin is created only while the user table is empty.Create a project: Projects, New project, a name and a slug (
acme; the slug is permanent).Invite teammates under Admin, Invites, and give each a role on the project.
Install the CLI and connect a repository
The spoor CLI connects a repository to a project. Every developer installs it once (Node 22 or later):
npm i -g spoor-memory@0.7.5 # use the version of your serverThen, in the root of the repository:
spoor login --server https://spoor.example.com --project acmespoor login prints a URL and an 8-letter code. Open the URL, log in and approve the code. The command then:
stores the token in
.claude/settings.local.json(mode 0600, added to.gitignore);writes
spoor.config.json(server and project), which marks the repository as set up for Spoor: the CLI and its hooks do nothing in any other directory, and never in your home directory;writes
.mcp.jsonand the Claude Code hooks in.claude/settings.json, with no secret in either;adds a Spoor block to
AGENTS.mdand an@AGENTS.mdimport toCLAUDE.md;turns Claude Code's own auto-memory off for this repo, so Spoor is the one memory (a project setting);
if the repository still has memory files from before Spoor (
MEMORY.md,.memory/,memory-bank/and the like), asks once whether to keep them in sync with Spoor (both ways) or to import them and delete them.
Restart Claude Code and approve the spoor MCP server. Then bring in what the repository already has:
spoor adr import # docs/adr/*.md become decisions
spoor docs import # ARCHITECTURE.md, GLOSSARY.md, docs/*.md become docs
spoor status --remote # project, role, token expiry
spoor context --git # the digest an agent will getCommit spoor.config.json, .mcp.json, .claude/settings.json, AGENTS.md, CLAUDE.md and the ADR files. A teammate on a repository that is already
set up only installs the CLI and runs spoor login.
Or let the agent do it. Tell Claude Code in the repository:
Set up Spoor memory by following
https://spoor.example.com/p/acme/install.md
Updates. The CLI does not update itself. After a server upgrade, the session digest names the new version: run
npm i -g spoor-memory@<server version>, then spoor init in each repo.
All commands and options: packages/cli/README.md.
Environment variables
Server
.env.example is the annotated template. Compose reads .env; a variable left empty takes its default.
Read by Docker Compose only:
variable | default | meaning |
| required | password of the |
| required | password of the |
|
| app image. The default is the local build; set |
|
| host port of the app |
|
| host address of the app. Use |
|
| host name for the Caddy profile |
Read by the app:
variable | default | meaning |
|
| the origin users type, with no path. Drives the origin check, cookie flags and every link. A mismatch breaks logins |
| required on an empty database | the first instance admin. Password 12 to 256 characters. Ignored once a user exists |
|
| display name of that admin |
|
|
|
|
| embedding provider new projects start with: |
|
| CPU threads of the local model (1 to 64) |
| unset | enables the |
|
| OpenAI model and vector size |
| unset | enables the |
| unset | required when the Voyage key is set |
| unset | enables the |
|
| Ollama model and vector size |
| unset | reverse proxies whose |
|
| every 6 hours the server reads one small file from GitHub and tells admins about a new release. It sends no instance data. |
| the release file in this repository | where the update check reads from |
|
| repo pushes and imports in flight per project (1 to 64). More get |
|
|
|
|
| maximum Postgres connections (1 to 500) |
Set by Compose or the image. Change these only when you run the app without the compose file:
variable | default | meaning |
| required | Postgres URL of the runtime role (no superuser) |
| unset | superuser URL, used once at startup for |
|
| listen port and address inside the container |
|
| where the local embedding model lives |
| set by the image | paths of the built web UI and the migrations |
|
| do not change |
Docker secrets: DATABASE_URL, DATABASE_MIGRATE_URL, SPOOR_ADMIN_PASSWORD, SPOOR_OPENAI_API_KEY and
SPOOR_VOYAGE_API_KEY also accept a <NAME>_FILE variant that names a file holding the value. Setting both is a
startup error.
CLI
spoor login stores the first three in .claude/settings.local.json, so you rarely set them by hand.
variable | meaning |
| server URL, project slug and token. They override the stored values |
| every hook and |
| shell command that drafts an ADR, in place of the default |
| fixed per-request timeout of |
| when set, ADR drafting is skipped unless |
Architecture
flowchart TB
subgraph dev["Developer machine"]
agent["AI coding agent<br/>Claude Code, Cursor, Codex, Gemini CLI"]
cli["spoor CLI and hooks<br/>login, digest, ADR and doc mirror"]
repo[("Repository<br/>docs/adr, docs, AGENTS.md")]
agent -. "runs hooks" .-> cli
cli <--> repo
end
browser["Browser<br/>web UI"]
subgraph server["Spoor server (Docker Compose)"]
proxy["Caddy or your proxy<br/>TLS, optional"]
subgraph app["app container: Node 22, port 3000"]
mcp["MCP endpoint<br/>/p/:project/mcp, nine tools"]
rest["REST API<br/>web UI and CLI"]
core["Items, revisions, links<br/>search, digest, dedupe"]
embed["Local embedding model<br/>multilingual-e5-small"]
jobs["Background jobs<br/>cleanup, embeddings"]
end
db[("Postgres 17 + pgvector<br/>the only state")]
end
ext["Optional embedding provider<br/>Ollama, OpenAI, Voyage"]
agent -- "MCP, bearer token" --> proxy
cli -- "REST, bearer token" --> proxy
browser -- "HTTPS, session cookie" --> proxy
proxy --> mcp
proxy --> rest
mcp --> core
rest --> core
core --> embed
core --> db
jobs --> db
core -.-> extOne app container serves the MCP endpoint, the REST API and the web UI. It keeps nothing on disk; the embedding model is baked into the image.
Postgres with pgvector holds everything: items, revisions, links, full-text and vector indexes, users, tokens and the audit log. Back it up with
pg_dump.Agents authenticate with per-project bearer tokens; people with a session cookie. Agents cannot write to the shared space or to library pages.
Search fuses Postgres full-text search with vector search. The digest is assembled from the same data within a fixed token budget.
The CLI runs on the developer's machine: it logs in through a device code, feeds the digest to Claude Code through hooks, and mirrors ADR and doc files to the server.
Components, flows and reasons: ARCHITECTURE.md, GLOSSARY.md and the decision records in docs/adr/.
Optional: better search with Ollama
The built-in model needs nothing. For better recall on reworded and non-English questions, Spoor can embed with
embeddinggemma on an Ollama server instead (paraphrase MRR 0.78 against 0.48 on our benchmark,
ADR-0026). Item text is then sent to that Ollama server and nowhere else.
Add an Ollama service. Create
docker-compose.override.ymlnext todocker-compose.yml(compose merges it automatically):services: ollama: image: ollama/ollama:0.40.15 restart: unless-stopped environment: OLLAMA_KEEP_ALIVE: "-1" # keep the model loaded, so no search waits for a reload volumes: - ollama-models:/root/.ollama # no ports: only the app reaches it, on the compose network (Ollama has no authentication) volumes: ollama-models:Point Spoor at it. In
.env:SPOOR_OLLAMA_URL=http://ollama:11434SPOOR_OLLAMA_EMBED_MODEL(embeddinggemma) andSPOOR_OLLAMA_EMBED_DIMS(768) already have the right defaults.Start it and pull the model (about 620 MB, once; it stays in the
ollama-modelsvolume):docker compose up -d docker compose exec ollama ollama pull embeddinggemmaSwitch a project. In the web UI open the project's Settings, Embedding, choose
ollamaand save. Items are re-embedded in the background; search keeps using the old model until the switch. To start new projects on it, also setSPOOR_EMBEDDING_DEFAULT=ollamain.env.Check the duplicate settings only if you had changed them. embeddinggemma scores similar texts lower than the built-in model, so a project on it defaults to a duplicate threshold of 0.75 and a related-items floor of 0.50 instead of 0.87 and 0.70. Values you saved earlier under Settings, Duplicates are kept as they are and belong to the old model's scale: set them again after the switch.
Notes:
GPU. The service above runs on CPU, which is slower than the built-in model for bulk re-embedding; its speed has not been measured. With an NVIDIA GPU and the NVIDIA container toolkit, add
deploy: { resources: { reservations: { devices: [{ driver: nvidia, count: all, capabilities: [gpu] }] } } }to theollamaservice.macOS. Docker gives containers no GPU there. Skip step 1, run the Ollama app natively (
ollama pull embeddinggemma) and setSPOOR_OLLAMA_URL=http://host.docker.internal:11434.If Ollama is down, writes still succeed (their embeddings are retried every minute) and search falls back to full text.
Details and other models: docs/operations.md, section 7.
Operating it
Backup.
docker compose exec -T db pg_dump -U spoor -Fc spoor > spoor-$(date +%F).dump. The file holds password and token hashes, so treat it as a secret. A project can also be exported as a zip from its Settings page.Upgrade. Back up, set the new image version (in
docker-compose.yml, orSPOOR_IMAGEwith the repository's file), thendocker compose pull && docker compose up -d. Migrations run at startup and are forward-only; to roll back, restore the dump and start the older image.Health.
GET /healthzreports the database, migrations and the embedding model. Instance admins see status, usage and job pages in the web UI.Rate limiting belongs in your reverse proxy; the app has none of its own.
Outbound traffic. With the local embedding provider, the only call the server makes on its own is the update check, which
SPOOR_UPDATE_CHECK=offstops.
TLS, proxies, restore, troubleshooting and releasing: docs/operations.md.
Documentation
read | for |
deploying and running it: env vars, TLS, proxies, backup, restore, upgrades, troubleshooting | |
the web UI: projects, spaces, the map and suggested links, item lifecycle, editing, tokens, admin | |
what agents get: digest, tools, links, hooks, drafting, mirror rules, token costs | |
the CLI: commands, configuration, imports | |
what is in each release | |
components, flows, terms | |
decisions and the detailed design; dod-status.md maps the brief's Definition of done to evidence | |
the contract: scope and amendments |
Development
Node 22 and pnpm 10.34.7 (packageManager). pnpm install, then pnpm build, pnpm test, pnpm lint, pnpm typecheck.
The server's integration and end-to-end tests need Postgres with pgvector: pnpm test:db:up starts one in Docker on port 55432
(pnpm test:db:down removes it), or point DATABASE_URL at a database whose name ends in _test. pnpm test fails fast
with a clear message when it is unreachable; pnpm --filter @spoor/server test:e2e walks the CLI against the real server.
pnpm e2e builds and runs the Playwright browser tests (once: pnpm --filter @spoor/web exec playwright install chromium).
pnpm --filter "spoor-memory..." build && pnpm --filter spoor-memory test:pack checks the npm package as it would be published.
Releases are cut with a v* tag (operations §10, ADR 0013); every green push to main also publishes
the develop image (ADR 0019).
Package notes: server, web, CLI.
Licence
MIT, see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Team memory for AI coding agents and code reviews, reviewed by humans and served over MCP.
Shared, scoped, reviewable team memory for AI coding agents.
Hosted MCP memory for coding agents: persistent across sessions, editable markdown, team sharing.
A shared team wiki your coding agents read and write — across every repo and every MCP client.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables multiple MCP-compatible AI clients to share persistent, versioned project knowledge across sessions with conflict-safe updates, provenance, hybrid retrieval, stale-memory handling, and context-budgeted recall.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents and assistants to share a local-first, token-efficient persistent memory layer across MCP-compatible runtimes, storing typed project facts, decisions, failures, and solutions with temporal validity. It supports offline use and Postgres-compatible storage, so agents can retrieve relevant context without re-embedding entire repositories.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to share and retrieve local project knowledge via hybrid search, coordinate file or module claims, broadcast status, and access compact token-budgeted briefs through MCP tools.MIT
- AlicenseNot gradedqualityAmaintenanceGives AI agents persistent, shared memory by ingesting notes, code, transcripts, and session captures, then serving token-optimized context and hybrid keyword/semantic search over MCP and REST. Agents can classify, promote, and synthesize stored material so each session builds on prior work instead of starting from zero.10 npmMIT