Skip to content
Back to search

archivist-tools

MarketplaceWorks with Claude CodeGitHub

Shared long-term memory for teams of AI coding agents, served as a remote MCP server. Hybrid full-text + vector search, no LLM on the server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/schengatto--archivist/badge.svg)](/listings/schengatto--archivist)

HTML

<a href="/listings/schengatto--archivist"><img src="/api/listings/schengatto--archivist/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 12 lines
  1. {
  2. "name": "archivist-tools",
  3. "owner": { "name": "Codepress S.r.l.", "url": "https://github.com/CODEPRESS-SRL" },
  4. "plugins": [
  5. {
  6. "name": "archivist-companion",
  7. "source": "./companion",
  8. "version": "1.1.0",
  9. "description": "Session-end auto-capture, sweep, and session-start memory index for Archivist."
  10. }
  11. ]
  12. }
README.md · README · 336 lines
  1. <div align="center">
  2. # 🗄️ Archivist
  3. **Shared, keyword-based memory for coding agents.**
  4. A remote [MCP](https://modelcontextprotocol.io) server that lets a whole team's
  5. AI coding agents — Claude Code, Codex, Cursor, anything that speaks MCP — save
  6. and recall hard-won context across sessions, machines, and people.
  7. [![CI](https://github.com/CODEPRESS-SRL/archivist/actions/workflows/ci.yml/badge.svg)](https://github.com/CODEPRESS-SRL/archivist/actions/workflows/ci.yml)
  8. [![npm](https://img.shields.io/npm/v/archivist-connect)](https://www.npmjs.com/package/archivist-connect)
  9. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  10. [Concepts](docs/concepts.md) &nbsp;·&nbsp; [Tools](docs/mcp-tools.md) &nbsp;·&nbsp; [Self-hosting](docs/self-hosting.md) &nbsp;·&nbsp; [Architecture](docs/architecture.md) &nbsp;·&nbsp; [Troubleshooting](docs/troubleshooting.md)
  11. </div>
  12. ---
  13. ## Choose your path
  14. | You are... | Go to |
  15. |---|---|
  16. | **Joining a team server** — you were given a URL and an API key | [Join a team server](#join-a-team-server) |
  17. | **Trying it on your laptop** — single user, no domain, no TLS | [Run it on your laptop in 5 minutes](#run-it-on-your-laptop-in-5-minutes) |
  18. | **Hosting it for a team** — a VPS with a domain | [Self-hosting](#self-hosting) and the [self-hosting guide](docs/self-hosting.md) |
  19. ### Prerequisites
  20. - **Docker Desktop** or **Docker Engine** with **Compose v2.24+** (the compose
  21. files use `env_file.required`, which older versions reject). Only needed to run
  22. the server (laptop or VPS), not to join a team server.
  23. - **Node.js 20 or newer** (for `npx archivist-connect`).
  24. - One coding agent: **Claude Code**, **Codex CLI**, or **Cursor**.
  25. - About **1 GB of disk** for the server image (the embedding model is baked in).
  26. - **Internet access at build time**: the image build downloads the embedding
  27. model from Hugging Face. The running containers need no outbound access.
  28. Stuck? See [docs/troubleshooting.md](docs/troubleshooting.md).
  29. ---
  30. ## The problem
  31. Coding agents forget everything between sessions. The lesson your agent learned
  32. debugging the auth flow on Monday is gone by Tuesday — and your teammate's agent
  33. never learned it at all. Knowledge that should compound instead evaporates,
  34. over and over, per person.
  35. ## What Archivist does
  36. Archivist is a small, self-hosted server that gives your team **one shared
  37. memory**, addressed by keyword. Agents refine what they learn into dense notes
  38. and save them; any teammate's agent can search and reuse them later. The server
  39. is **pure storage and search — it runs no LLM.** Refining and merging content is
  40. the agent's job, so there's no per-request model cost, no latency spike, and no
  41. provider lock-in.
  42. ```text
  43. Your agent learns something A teammate's agent, next week
  44. ┌────────────────────────┐ ┌────────────────────────┐
  45. │ "the deploy needs XFF │ │ memory_search │
  46. │ trust or the throttle │ ──────▶ │ "deploy proxy" │
  47. │ keys on the proxy IP" │ Archivist│ ──▶ finds the note, │
  48. └────────────────────────┘ (shared) │ no rediscovery │
  49. └────────────────────────┘
  50. ```
  51. ### How it works — the cycle
  52. 1. **Refine** *(agent)* — extract 1–3 keywords, compress the concept into a
  53. dense, self-contained note.
  54. 2. **Write** — new keyword → create it; existing keyword → **append** a
  55. fragment. Writes are events: they never block and never conflict, even when
  56. two teammates save at once.
  57. 3. **Compaction (merge-on-read)** — when someone reads a keyword with queued
  58. fragments, their agent merges everything back into one refined note. Lazy,
  59. safe, fully versioned.
  60. 4. **Retrieve** — `memory_search` (exact keyword + Postgres full-text) whenever
  61. context is needed; `scope="all"` searches across every project.
  62. Read the full model in **[docs/concepts.md](docs/concepts.md)**.
  63. ### Highlights
  64. - 🧠 **Zero server-side LLM** — pure SQL in the critical path; the agent does the thinking.
  65. - ✍️ **Append-only writes** — no write races by construction, never a blocked write.
  66. - ♻️ **Merge-on-read compaction** — notes stay dense; every version kept in history.
  67. - 👥 **Team-scoped** — one API key per team; strict cross-team isolation.
  68. - 🔎 **Hybrid FTS + pgvector retrieval**, on by default (`ENABLE_HYBRID_SEARCH=false` for FTS only).
  69. - 🔌 **Any MCP client** — one command to connect; the usage protocol ships in the handshake.
  70. - 🖥️ **Admin console** at `/admin` to browse a team's archive.
  71. - 🐳 **One `docker compose up`** to self-host, TLS included.
  72. ---
  73. ## Join a team server
  74. Your administrator gives you two things: the server URL (`https://<domain>/mcp/`,
  75. with the trailing slash) and a team **API key** (`arc_…`, a secret — treat it
  76. like a password). Then run:
  77. ```bash
  78. npx archivist-connect --server https://<domain>/mcp/ --key arc_xxx
  79. ```
  80. On a shared machine, omit `--key`: `archivist-connect` then prompts for it, so
  81. the key stays out of your shell history and the process list.
  82. This verifies the token against the server, registers the MCP in Claude Code,
  83. wires Codex and Cursor when their config directories (`~/.codex`, `~/.cursor`)
  84. exist, installs the companion plugin, and writes its config. Verify with
  85. `claude mcp list`.
  86. - Adds a short "use Archivist" rule to your user-level agent rules
  87. (`~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`) for each detected agent.
  88. Pass `--no-rules` to skip it. The rule is a managed block, so re-running
  89. updates it in place.
  90. <details><summary>Advanced / manual setup (per client)</summary>
  91. ### Claude Code
  92. ```bash
  93. claude mcp add --transport http archivist https://<domain>/mcp/ \
  94. --header "Authorization: Bearer <key>" -s user
  95. ```
  96. Verify: `claude mcp list`.
  97. ### Codex CLI
  98. Set the token in the shell that starts Codex, then add the server to
  99. `~/.codex/config.toml`.
  100. ```bash
  101. export ARCHIVIST_TOKEN="<key>" # macOS / Linux (add to your shell profile)
  102. ```
  103. ```powershell
  104. setx ARCHIVIST_TOKEN "<key>" # Windows (applies to new terminals)
  105. ```
  106. `setx` stores the key in plaintext in your user environment
  107. (`HKCU\Environment`), readable by every process you run.
  108. ```toml
  109. [mcp_servers.archivist]
  110. url = "https://<domain>/mcp/"
  111. bearer_token_env_var = "ARCHIVIST_TOKEN"
  112. ```
  113. ### Cursor
  114. Add to `~/.cursor/mcp.json` (or a project-local `.cursor/mcp.json`):
  115. ```json
  116. {
  117. "mcpServers": {
  118. "archivist": {
  119. "url": "https://<domain>/mcp/",
  120. "headers": { "Authorization": "Bearer <key>" }
  121. }
  122. }
  123. }
  124. ```
  125. That's it — start a session and your agent can `memory_search`,
  126. `memory_append`, and the rest. See the [tools reference](docs/mcp-tools.md).
  127. </details>
  128. ---
  129. ## Run it on your laptop in 5 minutes
  130. A single-user server on `localhost`: no domain, no TLS, no `make` needed. You
  131. need the [prerequisites](#prerequisites) above.
  132. ```bash
  133. git clone https://github.com/CODEPRESS-SRL/archivist
  134. cd archivist
  135. docker compose up -d --build
  136. ```
  137. The first build downloads the embedding model and takes a few minutes. When it
  138. finishes, `curl http://localhost:8000/healthz` returns
  139. `{"status":"ok","db":"ok"}`. The api applies database migrations on every start.
  140. Create a team and issue yourself a key (the key is printed **once**):
  141. ```bash
  142. docker compose exec api python scripts/create_api_key.py team-create me
  143. docker compose exec api python scripts/create_api_key.py key-issue --team me --label laptop
  144. ```
  145. Connect your agent with that key (`arc_…`). Keep the trailing slash in the URL:
  146. ```bash
  147. npx archivist-connect --server http://localhost:8000/mcp/ --key arc_xxx
  148. ```
  149. Verify and try it:
  150. ```bash
  151. claude mcp list # archivist should be listed as connected
  152. ```
  153. Then, in a new agent session in any project:
  154. 1. "Save in Archivist that this project uses …" (the agent saves a note).
  155. 2. "What does Archivist know about this project?" (the agent searches and
  156. recalls it).
  157. The admin console is at <http://localhost:8000/admin>; sign in with the key. It
  158. needs Chrome or Firefox over `http://localhost` (see
  159. [troubleshooting](docs/troubleshooting.md#admin-login-does-not-work-on-safari)).
  160. The defaults need no `.env` file. If you create one, change `POSTGRES_PASSWORD`
  161. only together with `DATABASE_URL` (the dev default hardcodes
  162. `archivist:archivist`), and do it before the first start: the `pgdata` volume
  163. keeps the password it was created with.
  164. Stop and remove:
  165. ```bash
  166. docker compose down # stop; your data stays in the pgdata volume
  167. docker compose down -v # stop and DELETE all data
  168. ```
  169. ---
  170. ## Self-hosting
  171. Archivist runs as a Docker Compose stack — proxy (TLS) → api (FastAPI + MCP) →
  172. PostgreSQL — that stands up with a single command on a VPS.
  173. ```bash
  174. cp .env.example .env # set POSTGRES_PASSWORD, ADMIN_SESSION_SECRET, ARCHIVIST_DOMAIN
  175. docker compose -f docker-compose.prod.yml up -d --build
  176. ```
  177. Then create a team and issue a key:
  178. ```bash
  179. docker compose -f docker-compose.prod.yml exec api \
  180. python scripts/create_api_key.py team-create <team-name>
  181. docker compose -f docker-compose.prod.yml exec api \
  182. python scripts/create_api_key.py key-issue --team <team-name> --label "<member/laptop>"
  183. ```
  184. The full guide — dedicated-host vs. shared-proxy TLS, configuration, key
  185. management, the admin console, backups and restore — is in
  186. **[docs/self-hosting.md](docs/self-hosting.md)**. For incidents, see the
  187. **[operations runbook](RUNBOOK.md)**.
  188. ### Local development
  189. ```bash
  190. make up # build + start db + api (docker compose)
  191. make test # api test suite (needs Docker for testcontainers)
  192. make test-companion # companion tests (node --test)
  193. make test-benchmark # benchmark tests
  194. make test-all # all three
  195. make lint # ruff check + format check
  196. make help # list all targets
  197. ```
  198. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full dev setup.
  199. ---
  200. ## What Archivist writes to your disk
  201. Memories live in Postgres on the server. On a **client** machine, the only
  202. thing installed locally is the optional companion, and everything it persists
  203. sits under a single directory:
  204. | Platform | Root | Cache |
  205. |---|---|---|
  206. | Windows | `%LOCALAPPDATA%\Archivist` | `%LOCALAPPDATA%\Archivist\Cache` |
  207. | macOS | `~/Library/Application Support/Archivist` | `~/Library/Caches/Archivist` |
  208. | Linux | `$XDG_DATA_HOME/archivist` | `$XDG_CACHE_HOME/archivist` |
  209. `ARCHIVIST_HOME` relocates that root; it is the only override. Nothing is
  210. written to the working directory, to the root of your home, or next to the
  211. sources — and no log file exists unless you ask for one
  212. (`ARCHIVIST_LOG_FILE=1`; diagnostics otherwise go to stderr, as the MCP spec
  213. requires). Temporary directories are cleaned up when a run ends, and a startup
  214. sweep reclaims whatever an abrupt kill left behind.
  215. ```bash
  216. npx --package archivist-connect archivist paths # what is written, where, how big
  217. npx --package archivist-connect archivist gc # run the cleanup sweep now
  218. npx --package archivist-connect archivist purge # remove all of it
  219. ```
  220. The `archivist` commands (`paths`, `gc`, `purge`) are available from companion
  221. **1.1.0**.
  222. **After uninstalling**, `archivist purge` leaves nothing of its own behind. What
  223. stays are the entries Archivist added to *other tools'* files — the plugin under
  224. `~/.claude/plugins/`, the MCP registration in Claude Code / `~/.codex/config.toml`
  225. / `~/.cursor/mcp.json`, and the `archivist:begin…end` rule block in
  226. `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`. `archivist paths` prints the exact
  227. list; removal instructions are in
  228. [companion/README.md](companion/README.md#uninstalling).
  229. On a **server**, `python -m app.paths` prints the same inventory for the API
  230. process (its only local footprint is the pinned fastembed/tiktoken cache; in
  231. Docker both live inside the image).
  232. ---
  233. ## Documentation
  234. | Guide | What's inside |
  235. |---|---|
  236. | **[Core concepts](docs/concepts.md)** | The memory cycle, namespacing, caps |
  237. | **[MCP tools](docs/mcp-tools.md)** | The seven tools + error codes |
  238. | **[Architecture](docs/architecture.md)** | Components, schema, design decisions |
  239. | **[Self-hosting](docs/self-hosting.md)** | Deploy, configure, administer, back up |
  240. | **[Troubleshooting](docs/troubleshooting.md)** | Fixes for the common first-run problems |
  241. | **[Agent commands](docs/agent-commands.md)** | Everything you invoke on your agent |
  242. | **[Runbook](RUNBOOK.md)** | Incident response |
  243. | **[Security](SECURITY.md)** | Threat model, controls, vulnerability reporting |
  244. ## Contributing
  245. Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the
  246. [Code of Conduct](CODE_OF_CONDUCT.md).
  247. ## License
  248. [MIT](LICENSE) © 2026 Codepress S.r.l. and contributors

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.