ctx — The memory your LLM pretends to have.
Knowledge store with weighted 4-way RRF retrieval, multi-tenant scope isolation, multi-dimensional cyclic temporal gravity, and autonomous cross-referencing. Built for AI workflows that need to remember.
What it does
ctx gives your LLM a persistent, searchable memory. Store knowledge blocks, query them with hybrid retrieval (semantic + bilingual fulltext + trigram), then rerank with multi-dimensional cyclic gravity — each temporal cycle (weekday, month, quarter, week, monthday, seasonal, daily) scored as its own Gaussian field. Queries like "immer dienstags" or "Weihnachten" activate specific dimensions.
Every block carries anchors from both its content (dates mentioned in text) AND its created_at timestamp, so a note about "Meeting am Dienstag" is findable by the day it discusses and the day it was written. Dream Mode runs as a continuous background loop — autonomously discovering relationships between blocks, marking outdated information, and promoting high-quality content. Your knowledge base grows, self-organizes, and stays current.
It speaks MCP, a CLI, and a plain HTTP API, ships an embedded web UI, and isolates multiple tenants down to the individual block.
Features
| Capability | What it is |
|---|
| 4-way RRF retrieval | Reciprocal-rank fusion of semantic + EN/DE fulltext + trigram, type-policy-parameterised — architecture |
| Cyclic temporal gravity | 7 cyclic dimensions with per-dimension Gaussian decay + forward telescoping — architecture |
| Dream Mode | Continuous autonomous cross-referencing, supersedes detection, parallel race-safe workers — architecture |
| Block-type registry | Declarative per-type behaviour (retrieval, guard, dream, digest), hot-reloadable — architecture |
| Multi-tenancy | Three-level tenant/scope/block isolation, grants, quotas, self-service onboarding — multi-tenancy |
| Issues & forge sync | Per-project issue/comment corpus (own scope = own repo), kanban board, policy-validated workflow-status transitions, and GitHub pull/push sync — api · cli |
| Sealed secrets | AES-256-GCM provider credentials + trust×sensitivity egress gating — security |
| Web UI | Embedded Svelte 5 admin SPA: settings, graph, corpus, status, chat, issues, type-registry admin, model API consumers (create with a reveal-once key, revoke) — development |
Quick install
# Binary (Linux/macOS/Windows): download to a temp dir, verify the signed build
# provenance (GitHub CLI — fails unless this repo's release workflow built the
# file), and only then install
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
# Or with Go
go install github.com/GottZ/ctx/cmd/ctx@latest
Point the CLI at your ctx host:
ctx init # config, server + key check, backend pool, Claude Code hooks, statusline
ctx init asks for base URL and API key, writes ~/.config/ctx/config — a mistyped key or one the server rejects is named and asked again, never saved — and checks the server. With a server-admin key it also seeds the backend pool — the chat and embedding backend ctx serves from — when no backend serves those roles yet, and probes the ones it finds; with any other key it skips that step and says so. Re-running it changes only what is missing.
mkdir -p ~/.config/ctx
cat > ~/.config/ctx/config << 'EOF'
CTX_BASE_URL=https://your-ctx-host.example
CTX_KEY=your-api-key-here
EOF
ctx health # DB + backend connectivity
ctx backends seed --host http://gpu:11434 \
--model qwen3 --embed-model qwen3-embedding # first backends, non-interactive
Running the server (Go daemon + PostgreSQL 18 + pgvector) is docker compose up -d ctx. Full setup, env vars and Claude Code integration are in operations; building from source in development.
Upgrading from v4? Reach v4.38.0 first. v5.0.0 removes the CTX_{CHAT,CHAT_FALLBACK,EMBED,DREAM,DREAM_EMBED,RERANK}_* connection variables: backends are configured in the pool (ctx backends) and nowhere else. v4.38.0 is the last release that still reads those variables, and one boot on it carries a .env-only configuration into the pool for you, then names every variable and leftover settings row you still have. Going straight from an older v4 to v5 is not fatal down to v4.19.0 — the env bridge is gone by then and you re-enter your topology by hand with ctx backends seed — but below v4.19.0 it is a hard stop: v5 folds migrations 001–113 into a single baseline and refuses a database that never applied 113. Migration path and rollback notes: operations.
Models: the tested reference stack is qwen3.6:27b for chat/synthesis/dream/digest, Qwen3-Embedding-8B (1024-dim, CPU-sized) for embeddings, and a bge-reranker-v2-m3 cross-encoder sidecar for rerank — but ctx is engine-agnostic: any OpenAI-compatible or Ollama API works, and the chat-class roles can run on the native Anthropic Messages API (protocol: "anthropic"); models are per-backend configuration. CPU-only setups work; a GPU shortens chat latency. Details: Models & hardware.
How LLMs use ctx
ctx is not a tool an agent picks up beside its work — it is the agent's persistent memory. "LLM" here means every agent that works against the store: the interactive session, and each subagent or workflow agent it starts, alike. Each one retrieves before it works and persists its own findings after: retrieve before, persist after. Five primitives, composable:
| Use case | Call | When |
|---|
| Retrieve prior knowledge before answering | ctx query "question" | Whenever the answer might depend on past sessions, project state, or stored decisions |
| Persist a new finding | ctx save <category> <title> - <content> | After non-obvious discoveries, architecture decisions, resolved bugs, config changes |
| Update an existing block | ctx save with same <category> <title> | category+title is the upsert key — re-saving replaces |
| Browse without LLM cost | ctx search [category] [query:text] | Listing, sanity-checking, lightweight lookups |
| Inspect a specific block | ctx get <block-id> | Following an id from query sources or another block |
Categories (semantic, not enforced): infrastructure, decisions, projects, reference, learnings, agent-briefing, index. Pick by intent: one fact per block, precise title, tags for cross-cutting. ~1–1.5k chars max — split, don't grow.
Access paths (in order of preference for LLM agents):
- MCP —
claude.ai ctx server (Streamable HTTP transport). Tools: query, store, search, get, recent. JSON-schemas, no shell-quoting. Use this in Claude Code / claude.ai sessions.
- CLI —
/usr/local/bin/ctx — shell pipelines, cron, scripts. Config in ~/.config/ctx/config.
- HTTP —
POST /api/{query,store,search,manage} direct — fallback when MCP/CLI unavailable.
Hooks are for agents without a conversation of their own. A subagent starts with nothing but its prompt and ends with a single final message. ctx brief --hook (Claude Code SubagentStart) injects the project's most recently updated agent-briefing blocks (up to --limit, default 20) into its context — and, when the project-tagged lookup returns nothing or fails (a transport error, a malformed or unsuccessful response), the most recently updated agent-briefing blocks the key can read, whatever their tags (#58); ctx persist --hook (SubagentStop) sends each [PERSIST:category:title] marker line in its last message, with the non-empty content that follows it, to store — an upsert on category and title, so a title that already exists in the key's scope replaces that block. A write the store never receives or rejects is dropped silently and not counted as saved. They give such an agent the same loop a session runs by hand — they are not tools for the session. Setup in operations.
How an agent should regard ctx, and what goes wrong when it treats the store as a tool: ctx as agent memory. Keeping that memory from drifting is a separate discipline: using ctx effectively.
Documentation
| Doc | Contents |
|---|
| Architecture | Retrieval pipeline, cyclic temporal model, Dream Mode, Guard, block-type registry, backend pool |
| Multi-tenancy | Model C (tenant/scope/block), grants, admin tiers, per-tenant settings/secrets/quotas, self-service onboarding |
| HTTP API | Endpoints, manage actions, graph API, settings API, backend pool, web-chat sessions |
| MCP reference | All 15 MCP tools with parameters, answers, error codes and staged writes |
| CLI reference | Every ctx subcommand, incl. tenant / quota / keys / block-grant |
| Security | Admin tier, sealed secrets & break-glass, trust×sensitivity gating, sensitivity classification |
| Operations | Setup, environment variables, boot validation, backups, deploy & migrations |
| Development | Building, the Svelte web UI, tests, visual baseline governance, git hooks |
| ctx as agent memory | ctx is the agent's memory, not a tool beside it: the loop for sessions and subagents, and the failure modes of treating it as a tool |
| Using ctx effectively |
Built with AI agents
ctx is built by AI agents working against a published RLHF-warnings calibration — a 22-axis map of LLM failure modes (memory drift, unattributed certainty, median-user caution) with concrete exemplars. It is the methodology reference behind this project's way of working: gottz.de/warnings.md. Background in using ctx effectively.
Sponsoring
ctx runs its retrieval decisions on measurements, not vendor benchmarks: the ANN engine question (pgvector vs. pgvectorscale, VectorChord, pgContext, or a sovereign Go binary-quantization path) sits behind a trigger framework that only escalates on evidence from the project's own corpus. The current engine is measured at 100k vectors; validating the alternatives honestly means fanning out wide benchmark runs at 1M–10M vectors — index builds in the tens-of-GB range, hours of exact ground-truth computation per lane, dedicated hardware. Empirical benchmarks of alternative engines are gated on funding, not on curiosity.
If you want those numbers to exist: GitHub Sponsors · Ko-fi · ETH via ENS gottz.eth
Star History
License
MPL-2.0 — By GottZ
