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 — development
MCP / CLI / HTTP	Three access paths to the same store, OAuth 2.1 for remote MCP — api

Quick install

# Binary (Linux/macOS/Windows)
curl -fsSL https://github.com/GottZ/ctx/releases/latest/download/ctx-$(uname -s | tr A-Z a-z)-$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') -o /usr/local/bin/ctx && chmod +x /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 check, backend pool, Claude Code hooks, statusline

ctx init asks for base URL and API key, writes ~/.config/ctx/config, 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.

Or configure it by hand

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, models are per-backend configuration. CPU-only setups work; a GPU shortens chat latency. Details: Models & hardware.

How LLMs use ctx

ctx is designed to be the persistent memory layer for LLM agents. Five primitives, composable:

Use case	Tool	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):

1. 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.
2. CLI — /usr/local/bin/ctx — shell pipelines, cron, scripts. Config in ~/.config/ctx/config.
3. HTTP — POST /api/{query,store,search,manage} direct — fallback when MCP/CLI unavailable.

Using a shared memory well takes discipline against drift — see 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
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
Using ctx effectively	Memory drift, agent discipline, RLHF calibration
Hermes integration	ctx_checkpoint memory provider for NousResearch/hermes-agent — durable, fail-closed pre-compaction checkpoints; the checkpoint contract version is negotiated at runtime against the loading host and recorded in every block's metadata

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