slipbox
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.
slipbox
A shared memory for your agents. Every agent connects over MCP, and what they know is kept as plain Markdown files in a folder, with every change committed to git: who wrote it, when, and why. You can read it all with cat and grep.
Search finds notes by their words and by their meaning, using a small embedding model that runs inside the program. There is no LLM in it and your notes never leave your machine. A read-only dashboard lets you watch what agents read and write.
Install
curl -fsSL https://raw.githubusercontent.com/unlaboredlabs/slipbox/main/install.sh | sh
slipbox service installThe first line puts one slipbox program in ~/.local/bin (Linux and macOS, x64 and arm64; no sudo). It needs git (on macOS, the Command Line Tools). The second runs it in the background and at login, with a systemd user unit on Linux or a launchd agent on macOS. The dashboard is then at http://127.0.0.1:7323; sign in with the ADMIN_TOKEN from ~/.config/slipbox/config.env, which the first run creates.
If slipbox is not found, ~/.local/bin is not on your PATH yet (the installer prints the line to add). Meanwhile run it by its full path: ~/.local/bin/slipbox service install.
slipbox service start | stop | status | logs
slipbox service uninstall # removes the service; your notes and config stay
slipbox update # installs the latest build and restarts the service
slipbox status # where it runs, where the data is, search healthTo run it in the foreground instead: slipbox serve.
What it downloads
install.shandslipbox updatedownload the program andchecksums.txtfrom this repository'sedgerelease on github.com, and check the checksum.The first start downloads the embedding model (about 130 MB) once from huggingface.co into
models/, and unpacks the embedding runtime (about 45 MB) from the program into the same folder. Until the model is there, search works by words.Nothing else. Notes, searches and keys stay on your machine.
Verify a download
Each release build carries a signed build provenance from GitHub Actions. With the GitHub CLI:
gh attestation verify ~/.local/bin/slipbox -R unlaboredlabs/slipboxThis checks that the file was built by this repository's release workflow on GitHub Actions, and has not been changed since.
Related MCP server: Cortex
Connect an agent
Create a key for each agent, with the folders it may read or write (/ means everything):
slipbox key create claude --write /
slipbox key create reviewer --read shared --read projects/shop --write agents/reviewer
slipbox key list
slipbox key revoke reviewerThe key is shown once. For Claude Code:
claude mcp add --transport http slipbox http://127.0.0.1:7323/mcp --header "Authorization: Bearer <key>"For other MCP clients that speak Streamable HTTP:
{
"mcpServers": {
"slipbox": {
"type": "http",
"url": "http://127.0.0.1:7323/mcp",
"headers": { "Authorization": "Bearer <key>" }
}
}
}Agents get eight tools: start, list, search, read, write, edit, delete and history, and instructions to call start first, search before writing, and correct facts in place rather than add duplicates.
The agent skill
The tools say how the memory works. The slipbox skill says when to use it: load context at the start of work, search before deciding or asking, what is worth writing down and where, and how to leave a handover note. Install it with the skills CLI (Node.js 22.20 or later):
npx skills add unlaboredlabs/slipbox -g # -g for every project; without it, the current oneOr copy it by hand into your agent's skills folder, for Claude Code ~/.claude/skills/slipbox/SKILL.md:
mkdir -p ~/.claude/skills/slipbox
curl -fsSL https://raw.githubusercontent.com/unlaboredlabs/slipbox/main/skills/slipbox/SKILL.md -o ~/.claude/skills/slipbox/SKILL.mdHow notes are kept
~/.local/share/slipbox/
data/ the notes: a git repository
shared/ what every agent should know
projects/<name>/ one folder per project
agents/<name>/ an agent's own notes
data.db the search index, agent keys and activity log
models/ the embedding model and runtime, fetched on first startA note's title is its first
# heading, and its summary is the first paragraph under it.profile.mdin any folder holds the short, always-current facts for that folder.starttells the agent its name and own folder, and returns the root profile,shared/profile.mdand every profile down to where the agent works.Notes are capped at 32 KB (profiles at 4 KB), so agents split big topics instead of growing one file forever.
Replacing a note needs the version the agent read; if someone changed it since, the write is refused and the current text comes back to merge.
Changes made outside slipbox (a
git pull, a manual fix) are picked up on start and while it runs.
The notes can always be rebuilt into a new index from the files (on the next start, or with slipbox reindex). Agent keys and the activity log live only in data.db, though: deleting it rebuilds the search index from the files, but every agent key must be created again.
How search works
Each note is split into sections at its headings. A search runs two ways at once:
Words: a full-text index (SQLite FTS5, or Postgres
tsvector) that ranks sections by how well they match, with titles and headings counting more.Meaning: each section has an embedding from a local model (
Xenova/bge-small-en-v1.5by default), which runs on its own thread so it never holds up the agents. The query is compared with every section the key may read, and a section counts as a match only if it is close enough: above a fixed similarity floor, and near the best match. A query that nothing answers gets no meaning matches rather than the least bad ones.
The two ranked lists are merged with reciprocal rank fusion. Agents get one entry per matching note, with its last change, the line ranges that matched (and whether by words, meaning or both) and a snippet that keeps the note's lines.
What it guarantees:
Words never depend on the model. If the model is missing, still downloading or fails, search answers from the word index and says meaning search is unavailable.
Exact, not approximate. Meaning search compares the query with every permitted section, so no close match is missed.
Never stale. An embedding is tied to the exact text of its section and the model's name. An edited section is found by words until its new embedding is ready; an old one is never used.
Writes never wait on the model. A write is committed and searchable by words at once; its embedding follows in the background, and pending work resumes after a restart.
Visible.
slipbox status,/api/healthand the dashboard show whether the model is loaded, how many sections are embedded, the queue, and the last error.Rebuildable.
slipbox reindexrebuilds both indexes from the files.
The macOS build for Intel Macs has no embedding runtime, because onnxruntime no longer ships one for that platform; there, search uses words only.
Configuration
Set these in ~/.config/slipbox/config.env. To override one for a single run, set it in the environment with a SLIPBOX_ prefix, such as SLIPBOX_PORT=7400 slipbox serve. Plain names in the environment are ignored, so a DATABASE_URL meant for another app never reaches slipbox.
Name | Default | |
| generated on first run | The dashboard's login, sent as a bearer token |
|
| The notes folder; the database and model sit next to it |
|
| A |
|
| The address to listen on; see Other machines |
|
| |
|
| Size cap per note |
|
| Any feature-extraction model on Hugging Face with ONNX weights; |
|
| The service's name, to run a second instance |
SLIPBOX_CONFIG_FILE points to another config file. The service reads only its config file, so a second instance gets its own file with its own DATA_DIR, PORT and SERVICE_NAME, installed with SLIPBOX_CONFIG_FILE=<that file> slipbox service install. After changing the file, restart the service with slipbox service stop and slipbox service start.
Changing EMBED_MODEL re-embeds every section on the next start. The meaning floor (MEANING_FLOOR in server/index/embed.ts) is measured for the default model; another model may need it measured again.
Postgres
Create an empty database and a user that owns it, then set the URL in the config file:
createdb slipbox
echo 'DATABASE_URL=postgres://user:password@localhost:5432/slipbox' >> ~/.config/slipbox/config.envslipbox creates its tables on the next start. The notes stay files on disk either way.
Other machines
slipbox speaks plain HTTP, so agent keys and the admin token cross the network unencrypted. Never expose the port to the open internet. Two safe ways to reach it from other machines:
A reverse proxy with TLS (Caddy, nginx) on the same machine. slipbox stays on
127.0.0.1; agents usehttps://<name>/mcp.A private network (Tailscale, WireGuard). Set
HOSTto the machine's address on that network; agents usehttp://<address>:7323/mcp.
Backup and moving machines
Everything lives in two places: ~/.local/share/slipbox (notes, database, model) and ~/.config/slipbox/config.env (the admin token). The notes alone are not enough: the agent keys and activity log exist only in data.db.
To back up or move, stop the service first, because a SQLite file copied while it is being written can be inconsistent:
slipbox service stop
tar czf slipbox-backup.tgz -C ~ .local/share/slipbox .config/slipbox
slipbox service startTo restore, or to move to another machine: install slipbox there, stop its service, unpack the archive into the home folder (tar xzf slipbox-backup.tgz -C ~) and start it again. The models/ folder can be left out; it downloads again.
For a backup without stopping: sqlite3 ~/.local/share/slipbox/data.db ".backup backup.db" copies the database safely, and data/ is a git repository you can push to a private remote. With Postgres, use pg_dump.
Troubleshooting
The service does not start.
slipbox service logsshows why. A port in use says so there; set anotherPORTin the config file.It stops when you log out (Linux). Run
loginctl enable-linger $USERonce.Search says meaning search is unavailable. The model is still downloading, or huggingface.co could not be reached.
slipbox statusshows the model's state and last error; word search works meanwhile. Intel Macs always search by words only.An agent gets 401. The key is wrong or revoked;
slipbox key listshows which keys exist.
Uninstall
slipbox service uninstall
rm ~/.local/bin/slipbox
rm -rf ~/.local/share/slipbox ~/.config/slipbox # your notes, keys and config: back them up firstOn macOS, the service's log is ~/Library/Logs/slipbox.log.
Development
You need Bun (the version in .bun-version) and git.
bun install
bun run serve # the server from source
bun test # the tests on SQLite
TEST_DATABASE_URL=postgres://postgres@localhost:5432/postgres bun test # and on Postgres
bun run typecheck
bun run build # dist/slipbox, with web/ built and embedded when presentEach Postgres test run creates and drops its own databases, so the URL only needs a user that may create them. The tests that use the real model download it once into your temp folder.
The server is in server/, the dashboard in web/, and DESIGN.md describes both. See CONTRIBUTING.md to send a change, and SECURITY.md to report a vulnerability.
License
MIT. The program bundles third-party code under its own licenses, listed in THIRD_PARTY_LICENSES and shipped with every release.
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
A shared team wiki your coding agents read and write — across every repo and every MCP client.
Notes your team and their agents build on together: write, share, comment and edit.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Shared project wiki for AI agents: read and write pages, next actions, and activity logs over MCP.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceA self-hosted Markdown knowledge base and Agent Harness with an MCP server that enables AI agents to read and write notes, providing persistent memory and a shared workspace for multi-agent collaboration.2MIT
- AlicenseNot gradedqualityCmaintenanceA dynamic, governed memory layer for Markdown notes that serves knowledge to AI clients and humans through a secure MCP server, with scoped access, git-audited changes, and optional LLM-powered semantic search.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceIt gives AI agents a self-hosted shared memory infrastructure: versioned Markdown knowledge, encrypted article bodies, routing and semantic retrieval, and conflict-safe staged writes coordinated over MCP.2AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceEnables multiple AI agents to share a locally controlled long-term knowledge base of Markdown notes, allowing them to retrieve, add, update, and remove preferences, decisions, and experiences. It supports cross-agent recall and version-aware changes while keeping the notes readable and editable outside the agent.MIT