ctx

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.

Install ctx Read the source

Cyclic temporal gravity Seven concentric rings, one per time cycle: time of day, weekday, day of month, week, month, quarter, season. The query “every Tuesday” raises a Gaussian peak on the weekday ring at Tuesday; the other rings stay flat. “every Tuesday” weekday · Tue time of day weekday day of month week month quarter season
Time is not one axis. Each cycle — time of day, weekday, day of month, week, month, quarter, season — is scored as its own Gaussian field, so a question about “every Tuesday” ranks blocks dated to a Tuesday higher, in any year.

What you get

Answers, not a list of hits
query searches 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. search gives 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:

  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.

How ctx works: four ways in (MCP, CLI, HTTP, web UI) lead to one Go server on PostgreSQL. Storing a block records its dates, computes an embedding and checks for duplicates. A question is searched four ways, weighted by time and by links, and answered by the chat model. A topic map groups the blocks, and the optional Dream Mode links them in the background.
Dream Mode, in the lower part of the picture, runs only when you switch it on. Open the diagram at full size (on GitHub).

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:

  1. loads the conventions it works under;
  2. lists the open items the last close left (step 5 below): search with tags: ["open"] and a limit (ctx search tags:open limit:50);
  3. asks query whole questions about the task (“why did we pin pgvector?”, not “pgvector pin”), and reads a block in full with get only when it holds its id;
  4. 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>').

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.

  1. 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.
  2. Working tree: clean, or every change left is a decision you can name; nothing unpushed without a reason.
  3. Checks: the project’s own tests and checks ran in this session.
  4. Deployment: if something was deployed, the commit in the repository, the deployed commit, the running service and its health check agree.
  5. 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.
  6. Open items: one block each, with the tag open: neutral, with its source and what it unblocks.
  7. 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:

What does not work, or only partly

Install

What you need:

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

  1. Point the CLI at the server and give it models. Run ctx init with the server’s address (with the override file: http://127.0.0.1:8080) and the key from CTX_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: localhost there is the container itself. ctx init also offers two Claude Code hooks for subagents and the statusline; ctx init --remove takes them out again.

    ctx init
    ctx health

    ctx health shows 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.

  2. 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 scope private; 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"
  3. 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 add https://your-ctx-host.example/mcp as a connector. For Hermes, see Hermes plugins.

  4. Optional. Dream Mode: set CTX_DREAM_ENABLED=true in .env and run docker compose up -d ctx again. It keeps calling your chat model in the background; ctx dream throttle adds 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 toCommand
Ask a question of your stored knowledgectx query "question"
Save a findingctx save <category> <title> - <content>
Replace a blockctx save with the same category and title
Change one field of a blockctx manage update <block-id> '{"tags":["a","b"]}', or the MCP tool update
Browse without a model callctx search [category] [query:text] [tags:a,b]
Read one blockctx get <block-id>
Archive a blockctx delete <block-id>
See the store and its healthctx stats, ctx health
Review flagged duplicatesctx guard list, ctx guard resolve <id> keep|archive
Import an Obsidian vaultctx ingest <path> --dry-run, then without --dry-run
Call any HTTP route with your keyctx 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: true it adds recall before each turn and the skill ctx-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
ctx_handover: watch the 90-second explainer “Close the lid” (MP4, 52 MB)
ctx_handover: close the lid, the session goes on.
ctx discord policy: everyone may talk, only you hold the keys. Opens the plugin’s README.
ctx_discord_policy: everyone may talk, only you hold the keys.

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 shared scope 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_writes gets its MCP writes staged; they run only when confirm is called with the exact hash.
Text from outside is marked
Blocks that hold tool output or transcripts carry an untrusted flag 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

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 root changes 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.