The memory your LLM pretends to have.
ctx is a knowledge store for LLM agents that you run yourself. Your agents save what they learn as small blocks: a decision with its reason, a fix with the error it fixed. Weeks later a fresh session asks "why did we pin pgvector?" and gets a short answer written from those blocks, with their ids. ctx finds a block by its meaning, by its exact words and by time. Claude Code, claude.ai, Hermes and any other MCP client can share one memory, and your scripts reach it through a CLI and plain HTTP. When your agents save and look up is up to the instructions you give them: ctx is the store, not the habit.
ctx query "why did we pin pgvector?" ask: a short answer from your blocks, with sources
ctx save decisions "pgvector pin" - "0.8.7, because …" remember: a new block, or replace the one with that title
ctx search decisions query:pgvector look around: matching blocks, no model call
ctx get <block-id> read one block in full
- Answers, not a list of hits.
querysearches four ways at once: by meaning, by English and German full text, and by similar titles. It merges the rankings and lets your chat model write a short answer from the blocks it found, with their ids.searchgives you the blocks without the model call. - Time counts. Every block keeps the day it was written and the full dates it names (2026-03-29, 29.03.2026, March 2026). A question that names a time, such as "every Tuesday", "at Christmas" or "immer dienstags", ranks the matching blocks higher.
- Duplicates caught, links on request. Guard compares each new block with the closest ones and, depending on the block type, archives a duplicate or flags it for you. Dream Mode, once you switch it on, reads blocks in the background, links related ones and marks what a newer block replaces.
- One store for every agent. 16 MCP tools for Claude Code, claude.ai or any MCP client, a CLI for scripts, cron and hooks, and a plain HTTP API. In Claude Code, two hooks give each subagent the project's briefing when it starts and save the findings it marks when it ends.
- Several teams on one server. Tenants hold scopes, scopes hold blocks. A key reads only the scopes it was given, and another tenant's data only through a grant you make, for one scope or one block. Quotas and key limits per tenant.
- Your models, wherever they run. Ollama, any OpenAI-compatible server or hosted API; chat also on the Anthropic Messages API. Each role (answers, embeddings, reranking, Dream Mode and a few more) has its own list of backends in priority order, so a CPU backend can stand in for a GPU one.
- Your models for other programs, if you want. An OpenAI-compatible API under
/v1(chat, embeddings, rerank) lets other programs use those models, with keys, limits and quotas of their own. ctx's own questions are served first. Off until you switch it on. - A web UI inside the server. Settings, model backends, the link graph, a block browser, live status, a chat that searches the store for you, project issues with a board. You sign in with an API key, or with a sign-in provider you set up.
One Go server (ctxd) on PostgreSQL 18 with pgvector and TimescaleDB. The models run wherever its backend pool
points. Dream Mode, shown in the picture, runs only when you switch it on. A block takes this path:
| Step | What happens |
|---|---|
| 1. Store | A block arrives over MCP, the CLI or HTTP and is saved at once. A block with the same category and title in the same scope is replaced. ctx records the full dates the text names and the time it was written. |
| 2. Embed and check | In the background the embedding model turns the block into a vector. Guard compares it with the closest blocks and archives or flags a duplicate. |
| 3. Ask | ctx reads the question for time words, embeds it, and searches four ways: by meaning (pgvector), English full text, German full text and title similarity. It fuses the four rankings into one. |
| 4. Weigh | Blocks near the times the question names rank higher. Once Dream Mode has written links, blocks linked to the best hits join in, and blocks that a newer one replaced drop out. A reranker and a boost for the strongest topics can be switched on. |
| 5. Answer | The chat model is told to answer from the retrieved blocks only. It cites them, and ctx lists their ids. |
| 6. Consolidate | With Dream Mode on, a background loop picks one block at a time, finds candidates and asks the chat model how they relate. It writes at most five links per round, including "this block replaces that one". |
search takes a lighter path: full-text matching only, without embedding and without a model call.
There are four ways in:
| Way | Use it for |
|---|---|
MCP (/mcp) |
agents in Claude Code, claude.ai, Hermes or any MCP client; API key, or OAuth 2.1 for remote clients |
CLI (ctx) |
the shell, scripts, cron, Claude Code hooks and the statusline; administration |
HTTP (/api/…) |
your own programs |
Web UI (/) |
settings, backends, graph, blocks, status, chat, issues |
- A Linux host with Docker Compose for the server, and
opensslfor its keys. ctx runs as a Linux container image; that is the only supported runtime. The compose file builds it, and a database image with PostgreSQL 18, pgvector 0.8.7 and TimescaleDB 2.31.0. - A chat model and an embedding model that ctx can reach over HTTP: Ollama, an OpenAI-compatible server or a hosted API. Chat also works through the Anthropic Messages API, which serves no embeddings. The embedding model must return at least 1024 dimensions. ctx keeps the first 1024, so pick a model whose first 1024 dimensions work on their own, such as the reference Qwen3-Embedding-8B. The tested reference for chat is qwen3.6:27b, with an optional bge-reranker-v2-m3 reranker. None of them is required.
- For the CLI: Linux or macOS on amd64 or arm64, or Windows on amd64. To check the download, the GitHub CLI
(
gh), signed in withgh auth login, or the provenance file of the release (below). Building from source needs Go 1.27.
What does not work, or only partly:
- ctx does not make an agent remember by itself. Beyond a short default hint it sends every connecting agent (when to look up, when to save; an operator setting), it brings no rules for when to look up or save. An agent that has ctx only as one more tool behaves as if it had no memory; see Bring your own workflow.
- Nothing answers before the models do, and CPU alone is slow. Until the backend pool has a chat and an
embedding backend,
/healthanswersunhealthy(HTTP 503) and questions fail at the embedding step. On CPU alone, the 27B reference model needs about 4.5 to 5.5 minutes per answer; on a GPU, up to a minute. - Full text in German and English only. The full-text search knows the word forms of these two languages; content in other languages is found by meaning and by its title. A question with umlauts or common German words is translated to English before the search, and no setting turns that off.
- New text is found by meaning a little later. Embeddings are computed in the background. A block you just saved or changed is found by its words and its title at once, and by meaning once its new vector exists.
- No earlier versions. Saving under the same category and title replaces the whole block, tags and metadata
included, and ctx keeps no revision of the old one. Deleting a block archives it;
ctx get --include-archivedstill reads it by its full id. - Changing the embedding model is a migration. Every stored vector has to be computed again in a supervised
re-embedding run (
ctx admin embed-migration); it is not a setting you flip.
The CLI (Linux and macOS). The download goes to a temporary folder, gh attestation verify checks that this
repository's release workflow built the file, and only then is it installed. Writing to /usr/local/bin needs
root; any other folder on your PATH works too.
f=ctx-$(uname -s | tr A-Z a-z)-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
tmp=$(mktemp -d)
curl -fsSL "https://github.com/GottZ/ctx/releases/latest/download/$f" -o "$tmp/$f" \
&& gh attestation verify "$tmp/$f" -R GottZ/ctx \
&& install -m 0755 "$tmp/$f" /usr/local/bin/ctxOn Windows, download ctx-windows-amd64.exe from the latest release
and check it the same way. Each release also carries SHA256SUMS and ctx.intoto.jsonl, the signed provenance as
a file: gh attestation verify <file> --bundle ctx.intoto.jsonl -R GottZ/ctx checks against it without signing in.
To build the CLI yourself instead, clone the repository and build with go -C go, which builds in the go
folder while your shell stays in the root folder. Then install the binary the same way:
git clone https://github.com/GottZ/ctx && cd ctx
go -C go build -o ctx ./cmd/ctx && install -m 0755 go/ctx /usr/local/bin/ctxThe server. Everything below runs in the root folder of a clone (git clone https://github.com/GottZ/ctx && cd ctx, or the clone from the build above). First the .env file. It will hold secrets, so it is created
readable by you only, and a .env you already have is kept and gets the same rights. Only then does the second
command add your first key, which ctx makes at its first start:
[ -e .env ] || (umask 077 && cp .env.example .env)
chmod 600 .env && { grep -q '^CTX_BOOTSTRAP_ADMIN_KEY=' .env \
|| { k=$(openssl rand -hex 32) && printf '\nCTX_BOOTSTRAP_ADMIN_KEY=%s\n' "$k" >> .env; }; }If a command fails, stop there; chmod fails, for example, when .env belongs to another user. Put no secret
into .env until ls -l .env shows -rw------- and you as its owner. Then set the passwords and CTX_SECRETS_KEY in .env, each a value from openssl rand -hex 32, and start
ctx. Compose builds ctxd and the database image and starts both:
[ -e docker-compose.override.yml ] || cp docker-compose.override.yml.example docker-compose.override.yml
docker compose up -d ctxThe ctx service publishes no port of its own; it carries labels for a reverse proxy. The first line above is
optional: it gives ctx the port 127.0.0.1:8080 and never replaces a docker-compose.override.yml you already
have. In that case, add the ports: entry of the example under services: ctx: in your file yourself. With a
proxy of your own in front, skip the line. Without a proxy, compose's warnings that CTX_HOSTNAME and
CTX_SSL_DOMAIN are not set do no harm.
Copy CTX_SECRETS_KEY from .env into your password manager. It seals the provider keys in the database, and
backups do not contain it: without it, those keys are gone. Every setting and environment variable is in
Operations.
Upgrading from v4? Reach v4.38.0 first. v5.0.0 no longer reads the backend connection variables such as
CTX_CHAT_HOST or CTX_EMBED_MODEL; backends live in the pool (ctx backends) and nowhere else. One boot on
v4.38.0 carries such a .env configuration into the pool and names every variable and settings row that is left.
From v4.19.0 on, skipping that release is not fatal, but you enter your backends again with ctx backends seed.
Below v4.19.0, v5 refuses the database. Path and rollback:
Operations.
-
Point the CLI at the server and give it models. Run
ctx initwith the server's address (with the override above:http://127.0.0.1:8080) and the key fromCTX_BOOTSTRAP_ADMIN_KEY. If the key is mistyped or the server rejects it, init says so and asks again; it never saves such a key. Then it asks for your model host, its protocol, a chat model and an embedding model, seeds the backend pool and tests what it wrote. Give the host as the ctx container reaches it:localhostthere is the container itself.ctx initalso offers two Claude Code hooks for subagents and the statusline;ctx init --removetakes them out again.ctx init ctx health
ctx healthshows the database and the model backends. For scripts, the backend step alone runs without questions:ctx backends seed --host http://gpu-host:11434 --model qwen3 --embed-model qwen3-embedding. -
Make keys. The bootstrap key is a server-admin key. Keep it in your password manager, remove its line from
.env, and give the CLI an everyday key in its config file afterwards. The first line below makes an everyday key that writes to the scopeprivate; the second makes a tenant with its own scope and an owner key, shown once:ctx keys create laptop --home private ctx tenant create friend "Friend Corp" -
Connect your agents. Claude Code and other MCP clients that send a header:
{ "mcpServers": { "ctx": { "type": "http", "url": "https://your-ctx-host.example/mcp", "headers": { "X-Context-Key": "your-api-key-here" } } } }claude.ai and other remote clients sign in with OAuth 2.1: register one with
ctx mcp add "Claude AI"and addhttps://your-ctx-host.example/mcpas a connector. For Hermes, see Hermes plugins. -
Optional. Dream Mode: set
CTX_DREAM_ENABLED=truein.envand rundocker compose up -d ctxagain. It keeps calling your chat model in the background;ctx dream throttleadds a pause between its calls. The OpenAI-compatible API: enabling it.
The full walk-through, with every option, is in Operations.
ctx is a skeleton. After the install it stores, finds and links what your agents give it, over MCP, the CLI and HTTP. It does not decide when your agent looks something up or writes something down, and it does not make a session start or end well on its own. By default ctx sends every client that connects over MCP a short hint: ctx is the agent's memory, look things up before answering or starting work, save what should last with its source. Whether the agent reads it is the client's choice: Claude Code passes it on, Hermes does not. An operator can switch that hint off or replace it with the team's own text (operations). Beyond that ctx brings no working style of its own and no ready-made skills, because every team works differently. Below is a suggested way of working. Adapt it to your team and write it into your own skill, rule file, hook or prompt. Suggestions for ready-made skills will come later. The tool names are the MCP tools an agent uses; the CLI commands in parentheses do the same.
Session start. Before its first answer, your agent:
- loads the conventions it works under into its context;
- lists the open items the last close left:
searchwithtags: ["open"]and alimit(ctx search tags:open limit:50). That returns every live block with the tag that the key can read, newest first, as a short preview. Several tags widen the match, so keep projects apart by category instead (ctx search <category> tags:open); - asks
querywhole questions about the task ("why did we pin pgvector?", not "pgvector pin"), and reads a block in full withgetonly when it holds its id, such as one an open item names; - says in two or three sentences what it loaded, then starts.
During the work. Your agent looks up before it decides, and checks live state before it acts on a block: a
block says where to look, not what is true now. It saves each finding when it happens, with store: one concept
per block, a precise title, a category, tags, the source and the date. It searches first and changes an existing
block with update instead of adding a second one (ctx manage update <block-id> '<json>'); tags and metadata
sent there replace the whole set. A store with the same category and title replaces the whole block (ctx save
does the same).
Session close. A session is closed when every "done" in its report rests on the output of a command, not on what the session remembers. Each step has a check, and what was not checked is reported as not checked. If a step is red, your agent reports the red state instead of closing.
| Step | Check |
|---|---|
| 0. Who asks | A person, or an automation such as a timer, a loop or a hook? An automation continues the task; it does not end it. |
| 1. Working tree | git status --porcelain is empty, or every change left is a decision you can name. Nothing is unpushed without a reason: git log --oneline HEAD --not --remotes lists what no remote has, also on a branch that was never pushed. |
| 2. Checks | The project's own tests and checks ran in this session. Green means "nothing known is broken", not "everything works". |
| 3. Deployment | If something was deployed: the commit in the repository, the deployed commit, the running service and its health check agree. The deploy tool's success message is not that state. |
| 4. Store | Every finding a later session needs is in ctx, one concept per block, an existing block updated rather than copied. Each fact lives in one place: git holds the diff, ctx each decision or finding as it happened, with source and date. A finding still missing goes in now in that form, not as a summary of the session. The check: search with words of the finding (ctx search query:<words>) returns its block. |
| 5. Open items | One block each, with the tag open: neutral, with its source (file and line, or a quote with its date), what it unblocks and the ids of the blocks it rests on, without an urgency nobody gave it. A done item is archived with archive (ctx delete <block-id>). |
| 6. Report | To the person, in the session, not as a block: per step what was checked and with what result, what was not checked or stays open, and the ids of the open items. |
This is not a handover note that retells the session. The findings should already be in the store, per topic; the close checks that they are, and leaves only the open items and the pointers to them.
What there is to start from:
- ctx as agent memory: the loop for a session and for a subagent, and what goes wrong when an agent treats the store as a tool, including why a retelling handover note is one of those ways.
- Using ctx effectively: rules to put into your agent's instructions, and how to keep stored memory from drifting.
ctx initinstalls, if you agree, two Claude Code hooks for subagents.ctx brief --hookhands each new subagent the blocks of the categoryagent-briefingthat are tagged with the project.ctx persist --hookstores each finding the subagent marks with a[PERSIST:category:title]line in its last message (Claude Code integration). Nothing covers the start or the end of your own session.- The Hermes plugin
ctx_checkpointshows what a finished integration looks like: it archives the transcript in ctx before Hermes compacts a conversation, and withmemory: trueit adds recall before each turn and the skillctx-memory, which tells Hermes how to query and store during the work.
| You want to | Command |
|---|---|
| Ask a question of your stored knowledge | ctx query "question" |
| Save a finding | ctx save <category> <title> - <content> |
| Replace a block | ctx save with the same category and title |
| Change one field of a block | ctx manage update <block-id> '{"tags":["a","b"]}', or the MCP tool update |
| Browse without a model call | ctx search [category] [query:text] [tags:a,b] |
| Read one block | ctx get <block-id> |
| Archive a block | ctx delete <block-id> |
| See the store and its health | ctx stats, ctx health |
| Review flagged duplicates | ctx guard list, ctx guard resolve <id> keep|archive |
| Import an Obsidian vault | ctx ingest <path> --dry-run, then without --dry-run |
| Call any HTTP route with your key | ctx api GET /api/whoami |
Agents do the same over MCP: query, store, search, get, recent and eleven more tools for updates,
archiving, confirmed writes, issues, duplicate review and binary blobs (MCP reference).
Three plugins for Hermes live in this repository:
| Plugin | What it does | Install |
|---|---|---|
ctx_checkpoint |
The ctx memory provider. Before Hermes shortens (compacts) a long conversation, it archives the direct transcript in ctx; on request, no compaction runs without that copy. Afterwards the agent's system prompt names that copy and how to read it. With memory: true also recall before each turn, ctx_* agent tools, a mirror of Hermes' memory files, fact extraction, session digests and the skill ctx-memory. Talks to ctx through Hermes' own MCP connection. Its memory engine was contributed by derLonius (W4-NERF) as hermes-ctx-plugin. |
hermes plugins install ctx_checkpoint, then hermes memory setup ctx_checkpoint or the forms in Hermes Desktop (Settings → Memory and Settings → Plugins); hermes memory status shows whether checkpoints work |
ctx_handover |
Moves a running Hermes session, with its conversation and project folder, from one of your machines to another and back. Works without ctx. | hermes plugins install ctx_handover and hermes plugins enable ctx_handover, on both machines |
ctx_discord_policy |
Lets a Hermes bot talk on your Discord servers while its tools stay with the operators in your Hermes configuration; each server is set up inside Discord with /policy. Works without ctx. |
hermes plugins install GottZ/ctx/integrations/hermes/plugin/ctx_discord_policy --enable, then restart the gateway |
ctx_checkpoint (catalog page) and
ctx_handover are listed in the Hermes plugin catalog; ctx_discord_policy is installed from this repository.
- A key reads only what it was given. Every key writes to its own scope and reads the scopes it was allowed;
keys of the default tenant get its
sharedscope by default. Another tenant's data needs a grant. A key whose tenant cannot be resolved is refused. - Admin work needs an admin key. Keys, MCP clients, settings, secrets and the backend pool need a server-admin key, or a tenant-admin key for its own tenant.
- Provider keys are sealed. API keys of model providers are stored encrypted (AES-256-GCM) under
CTX_SECRETS_KEY, written through a write-only API that never returns them. - Sensitive blocks stay on trusted models. Every block has a sensitivity, and an unclassified block counts as
credentials. Every backend has a trust level, and a block reaches only backends trusted for it. A scanner raises blocks that contain credentials. - Agent writes can wait for a yes. A key with
confirm_writesgets its MCP writes staged; they run only whenconfirmis called with the exact hash. - Text from outside is marked. Blocks that hold tool output or transcripts carry an
untrustedflag in results, so an agent reads them as data.
- Network, server: the model backends in its pool. Only when you set them up:
- GitHub, for project issue sync;
- your sign-in providers;
- with the image proxy switched on, the images that chat answers show.
- Network, CLI: your ctx server, plus one release check against
api.github.cominctx init(--no-update-checkorCTX_NO_UPDATE_CHECK=1skips it). - Stored by the server: your blocks and blobs. A log of ctx's own model calls with their prompts and answers,
except for content classed as credentials; the text is cleared after 90 days (
CTX_LLMLOG_RETENTION_DAYS). Calls through/v1keep no text unless you switch that on. Web chat sessions, kept until you setCTX_WEBCHAT_SESSION_RETENTION. A log of block reads. - Background work, server: embeddings and duplicate checks for new blocks; on days with new activity, a daily report at 03:00 per tenant, written by the chat model and saved as a block; Dream Mode, once you switch it on.
- Stored by the CLI: a config file with the server address and your key, in
$XDG_CONFIG_HOME/ctx,%APPDATA%\ctxon Windows, else~/.config/ctx. Withctx init, the hooks and the statusline in Claude Code'ssettings.json, with a backup copy before each change. Withctx project init, a repository key inprojects/of that folder and a.ctx-projectfile without secrets in the repository.ctx persist --hookadds session id, host name, project and agent to the metadata of each block it saves. - Commands, CLI:
git, read-only, whenctx projectdetects a repository. - Inbound: HTTP on port 8080 inside the container:
/api/…,/mcp, the sign-in and OAuth routes,/health, the web UI,/v1and/v2once the OpenAI-compatible API is on, and a signed webhook route for GitHub sync.
The full picture is in Security; reporting a vulnerability is in SECURITY.md.
| Document | What is in it |
|---|---|
| Architecture | Retrieval pipeline, cyclic time model, Dream Mode, Guard, block types, backend pool |
| Multi-tenancy | Tenants, scopes and blocks, grants, admin tiers, per-tenant settings, secrets and quotas, onboarding |
| HTTP API | Endpoints, manage actions, graph, settings, backend pool, web chat, the OpenAI-compatible API |
| MCP reference | All 16 MCP tools with parameters, answers, error codes and staged writes |
| CLI reference | The ctx commands, exit codes, tenants, quotas, keys, block grants, model consumers |
| Security | Admin tier, sealed secrets and break-glass, trust and sensitivity, audit trail |
| Operations | Setup, environment variables, backends, models and hardware, backups, deploy and migrations |
| Development | Building, platforms, the web UI, tests, gates, git hooks |
| ctx as agent memory | How an agent should treat the store, and what goes wrong when it treats it as a tool |
| Using ctx effectively | Why stored memory drifts, agent discipline, calibration |
| Contributing · Governance | Pull requests, coding standards, roles, how root changes, releases |
ctx is built by AI agents working against a published calibration: a map of 22 ways LLMs fail at long-running work (memory drift, certainty without a source, caution tuned for an average user), each with real examples. It is the method behind this project: gottz.de/warnings.md. Background in Using ctx effectively.
ctx makes its retrieval decisions on measurements from its own corpus, not on vendor benchmarks. The question of the vector index engine (pgvector against pgvectorscale, VectorChord, pgContext, or a binary-quantization path of its own in Go) only moves on evidence. The current engine is measured at 100k vectors. Testing the alternatives takes benchmark runs at 1M to 10M vectors: index builds in the tens of gigabytes, hours of exact ground-truth computation per run, dedicated hardware. Those benchmarks depend on funding.
If you want those numbers to exist: GitHub Sponsors · Ko-fi · ETH via ENS gottz.eth