# Archivist MCP

> Archivist MCP is a local-first memory server for coding agents. It persists decisions, incidents, rules, entities, and graph relationships in SQLite, then exposes them over MCP (stdio/HTTP), SSE team mode, and WebUI. Built for cross-session context continuity, conflict-safe updates, searchable recall, and auditable change history.

- **Type:** MCP server
- **Install:** `agentstack add mcp-i3t4an-archivist-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [i3T4AN](https://agentstack.voostack.com/s/i3t4an)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [i3T4AN](https://github.com/i3T4AN)
- **Source:** https://github.com/i3T4AN/Archivist-MCP

## Install

```sh
agentstack add mcp-i3t4an-archivist-mcp
```

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

## About

# Archivist MCP

*Local-first project memory server for agents and developers*

[](https://www.python.org)
[](https://www.sqlite.org)
[](https://modelcontextprotocol.io)

[Features](#features) • [Quick Start](#quick-start) • [MCP Setup](#mcp-setup) • [WebUI](#webui) • [Usage](#usage) • [Tools](#mcp-tools) • [Configuration](#configuration) • [Reliability](#reliability--ops) • [Troubleshooting](#troubleshooting)

---

**Archivist MCP** is a memory layer for coding agents. You run it alongside your project, connect your MCP client, and the agent can persist/retrieve decisions, incidents, rules, and architecture context across sessions. WebUI is for human review and controlled write actions when you want visibility before changing memory.

## Features

- **Three-tier memory model**: working memory, compact core memory (`core_memory.md/.json`), archival graph
- **Graph + lifecycle safety**: typed nodes/edges, state transitions, optimistic concurrency, immutable audit events
- **Hybrid retrieval**: FTS + local embeddings + graph degree + recency with provenance and confidence
- **MCP transports**: JSON-RPC over STDIO and HTTP (`/mcp`)
- **Team mode**: SSE transport with bearer-token auth, role matrix, and project scoping
- **Controlled write workflows**: conflict resolution, branch-to-project promotion, stale-memory invalidation
- **Security hardening**: payload allowlists, size/type validation, sanitization, redaction, retention purge
- **Reliability tooling**: integrity checks, snapshots, restore, startup recovery, rebuild index+embeddings

## Quick Start

### Prerequisites

- Python `3.11+`
- macOS/Linux/Windows

### 1) Initialize database

```bash
python3 scripts/migrate.py --db .archivist/archivist.db
```

### 2) Start STDIO server

```bash
python3 -m archivist_mcp.stdio_server --db .archivist/archivist.db
```

### 3) Seed a project/user (first-time)

```bash
python3 - .db --db .archivist/archivist.db
```

### Rebuild derived state

```bash
python3 scripts/rebuild_index_and_embeddings.py --db .archivist/archivist.db --project-id proj-1 --root .
```

## Project Structure

```text
archivist_mcp/
  mcp_stdio_server.py      # MCP JSON-RPC over stdio
  mcp_http_server.py       # MCP JSON-RPC over HTTP (/mcp)
  sse_server.py            # Team mode HTTP+SSE
  webui_server.py          # Browser UI + controlled write APIs
  tooling/server.py        # Tool router, validation, envelope/errors
  storage/repository.py    # Graph persistence + lifecycle + audit
  retrieval/               # embeddings + hybrid retrieval
  indexing/                # symbol extraction + incremental indexer
  memory/materializer.py   # core_memory.md + core_memory.json
  migrations/sql/          # schema migrations
scripts/
  migrate.py
  create_snapshot.py
  restore_snapshot.py
  check_integrity.py
  rebuild_index_and_embeddings.py
tests/
  test suites for integration, retrieval, security, team mode, and WebUI behavior
docs/
  quickstart.md
  troubleshooting.md
  recovery_runbook.md
```

## Troubleshooting

### `AUTHZ_DENIED`

Token role/scope does not permit the tool or project. Check `ARCHIVIST_SSE_TOKENS` role and `projects`.

### `CONFLICT_ERROR`

Optimistic version mismatch. Re-read node, use latest `version`, retry or resolve via conflict workflow.

### `EMBEDDING_DISABLED`

Embeddings are disabled/unavailable. Retrieval falls back to `fts_graph` mode.

### Blank WebUI timelines

The UI reads from the DB passed to `webui_server --db`. Ensure your seeding and servers all point at the same DB path.

## Documentation

- Quickstart: [docs/quickstart.md](docs/quickstart.md)
- Troubleshooting: [docs/troubleshooting.md](docs/troubleshooting.md)
- Upgrade/Migration: [docs/upgrade_migration.md](docs/upgrade_migration.md)
- Recovery runbook: [docs/recovery_runbook.md](docs/recovery_runbook.md)
- Security threat model: [docs/security_threat_model.md](docs/security_threat_model.md)

---

Built for durable project memory across agent sessions, with local-first defaults and auditable writes.

## Source & license

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

- **Author:** [i3T4AN](https://github.com/i3T4AN)
- **Source:** [i3T4AN/Archivist-MCP](https://github.com/i3T4AN/Archivist-MCP)
- **License:** MIT

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:** no
- **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-i3t4an-archivist-mcp
- Seller: https://agentstack.voostack.com/s/i3t4an
- 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%.