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.
What you get
- 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.
How it works
One Go server (ctxd) on PostgreSQL 18 with pgvector and TimescaleDB; the models run wherever its backend pool points. Four ways in: MCP for agents in Claude Code, claude.ai, Hermes or any MCP client; the ctx CLI for the shell, scripts, cron and hooks; HTTP for your own programs; and the web UI. A block takes this path:
- 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.
- 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.
- 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.
- 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.
- Answer. The chat model is told to answer from the retrieved blocks only. It cites them, and ctx lists their ids.
- 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.
Bring your own workflow
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. Today ctx is deliberately neutral: it brings no working style of its own and no ready-made skills, because every team works differently. Below, in short, 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;
- lists the open items the last close left (step 5 below):
searchwithtags: ["open"]and alimit(ctx search tags:open limit:50); - 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; - 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 withupdateinstead of adding a second one (ctx manage update <block-id> '<json>').- 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.
- 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.
- Working tree: clean, or every change left is a decision you can name; nothing unpushed without a reason.
- Checks: the project’s own tests and checks ran in this session.
- Deployment: if something was deployed, the commit in the repository, the deployed commit, the running service and its health check agree.
- Store: every finding a later session needs is in ctx, one concept per block, with source and date, an existing block updated rather than copied; not a summary of the session.
- Open items: one block each, with the tag
open: neutral, with its source and what it unblocks. - Report: to the person, in the session, not as a block: 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. The check for each step is in Bring your own workflow in the README.
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.
What does not work, or only partly
- ctx does not make an agent remember by itself. 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.
Install
What you need:
- 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.
The CLI
On 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/ctx
On 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 from source instead, with Go 1.27, follow Install in the README.
The server
The server runs with Docker Compose from the root folder of a clone of the repository. You create .env from .env.example, readable by you only before any secret goes in, with your passwords, the key CTX_SECRETS_KEY and a first admin key, and docker compose up -d ctx builds ctxd and the database and starts both. The ctx service publishes no port of its own; it carries labels for a reverse proxy. Without a proxy of your own, the example file docker-compose.override.yml.example gives ctx the port 127.0.0.1:8080; the README shows how to use it without replacing an override file you already have. The steps, command by command, are in Install in the README.
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.
Set up once
-
Point the CLI at the server and give it models. Run
ctx initwith the server’s address (with the override file: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 healthctx 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.
How an agent uses it
From a shell, a script or a hook:
| 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).
Hermes plugins
Three plugins for Hermes live in the ctx repository.
ctx_checkpoint- The ctx memory provider: before Hermes shortens (compacts) a long conversation, it archives the direct transcript in ctx, and with
memory: trueit adds recall before each turn and the skillctx-memory. Its memory engine was contributed by derLonius (W4-NERF) as hermes-ctx-plugin. Listed in the Hermes plugin catalog. README · catalog page 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. Listed in the Hermes plugin catalog. README · 90-second explainer (MP4, 52 MB)
ctx_discord_policy- Lets a Hermes bot talk on your Discord servers while its tools stay with the operators in your Hermes configuration. Works without ctx. Not in the Hermes plugin catalog; you install it from the ctx repository. README
Safety in short
- 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.
What the server and the CLI send over the network, store and run in the background is listed under Disclosure in the README. The full picture is in Security; reporting a vulnerability is in SECURITY.md.
Documentation
- Architecture retrieval pipeline, cyclic time model, Dream Mode, Guard, block types, backend pool
- Operations setup, environment variables, backends, models and hardware, backups, deploy and migrations
- 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
ctxcommands, exit codes, tenants, quotas, keys, block grants, model consumers - Multi-tenancy tenants, scopes and blocks, grants, admin tiers, per-tenant settings, secrets and quotas, onboarding
- Security admin tier, sealed secrets and break-glass, trust and sensitivity, audit trail
- 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
Get involved
- Ask or give feedback
- Questions go to Q&A, feature ideas and design feedback to Ideas, everything else to Discussions.
- Report a bug
- Open an issue with the version (
ctx version), how ctx runs, and the exact commands and output. Open bugs are listed under the bug label. - Report a vulnerability
- Privately, through a GitHub security advisory — never in a public issue. The security policy says what to include and what happens next.
- Contribute code
- The contributing guide covers forking, the git hooks, tests, commit messages, the coding standards CI enforces and how review works; build and test details are in the development docs. How
rootchanges and who decides is in the governance document. Issues labelled good first issue are a place to start.
Built with AI agents
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. Read the warnings, or the long history of the project in the ctx compendium.