README.md

One binary. Your whole memory.

Crux is a local-first memory daemon for AI agents — a versioned fact store, token-budgeted BM25 + graph retrieval, and an Ed25519-signed receipt for every write. 100+ MCP tools, agent passports, portable .cruxpack export. No account. No API keys. Nothing leaves your machine.

Up and running in 60 seconds · The console · How it works · MCP tools · Platform · Docs

_{Overwatch — the gates that need you, the live fleet, every action receipted. Ships inside the daemon at localhost:14800 — no account, no cloud dashboard.}

Why Crux

• Memory that ages honestly. Facts carry confidence, provenance and a freshness horizon (volatile ~24 h · medium ~35 d · stable ~1 y). A deterministic decay engine downranks stale claims instead of serving them as truth — reversible via memory_reverify, with scoped forget + dry-run for GDPR Art. 17.
• Retrieval on a token budget. token_budget is a first-class parameter, not a hope. BM25 + graph fusion returns metadata and token counts first, content only inside budget — 60–80% fewer tokens than naive top-K context stuffing. Dense lanes are bring-your-own and never required.
• Receipts, not vibes. Every mutation emits a CROWN receipt: Ed25519-signed, hash-bound, independently verifiable offline. Store integrity is checked separately with corecruxctl verify-store --strict.
• Identity agents earn. Every agent carries a passport with a five-tier reputation ladder; verified receipts accrue as track record, and capability tokens expire instead of leaking.
• Policy over memory. Declare organisational constraints once; proposed actions are checked against them — pass, warn, or block — before they execute.
• Your memory follows you. Export everything as a self-certifying .cruxpack — signed, offline-verifiable, importable into any other daemon. Leaving is a command, not a ticket.
• Know what every session cost. corecruxctl session cost and the console's token-burn page show how much context every model call re-read, where it went, and what to change.

Up and running in 60 seconds

The lowest-friction install is to just ask your agent. Paste this into any coding agent — it reviews the source, installs and runs the daemon, then Crux's setup wizard wires it into your session: the MCP surface connected, a passport minted, a first fact round-tripped.

Review and install the Crux Daemon from github.com/CueCrux/Crux — read the README and
LICENCE first, run it locally, then use its setup wizard to connect the daemon to this
session and confirm the console is up at http://localhost:14800.

Prefer to do it yourself? Bring the daemon up on any of three rails:

# Docker (recommended)
git clone https://github.com/CueCrux/Crux.git && cd Crux
docker compose up -d

curl -sSL https://github.com/CueCrux/Crux/releases/latest/download/crux-linux-amd64 -o crux
chmod +x crux
CORECRUXD_AUTH_MODE=dev_scopes CORECRUXD_DATA_DIR=./data ./crux

git clone https://github.com/CueCrux/Crux.git && cd Crux
cargo build --release
CORECRUXD_AUTH_MODE=dev_scopes CORECRUXD_DATA_DIR=./data ./target/release/corecruxd

HTTP binds 127.0.0.1:14800, MCP binds 127.0.0.1:14801. Open http://127.0.0.1:14800 — the embedded console walks you through one-time setup — then get live with one command:

corecruxctl start

start is the canonical on-ramp: it detects the daemon, authenticates on the lowest-friction secure rail, wires the MCP endpoint + Claude Code hooks, round-trips a first fact, and prints a single "you're live" summary.

Using Codex or Cursor? One command each — --agent wires that client's own config too:

Every write is a merge, not an overwrite — your other MCP servers and settings survive — and re-running is safe. No bearer token is ever written into an agent config; it stays in ~/.config/cuecrux/env (0600) and is resolved at runtime. Codex gets the stdio bridge rather than the HTTP endpoint because Codex CLI fails the daemon's streamable-HTTP handshake (details).

Longer install path: docs/getting-started.md · guided rails: corecruxctl login, corecruxctl quickstart · ready-made MCP connector configs for Claude Code, Claude Desktop and Cursor: examples/mcp-configs/.

The console

Every daemon ships a local operator console at localhost:14800 — watch your fleet, your plans, and your memory, every action receipted.

Canvas — your whole operation as a size-adaptive board	the relation graph — sessions, work, gates and passports, flow-traced
plans as living documents — milestones, gates, risk, progress	sessions that survive restarts — resume, audit, attribute token spend

Don't believe this README

Every claim about integrity is checkable on your own machine, offline, in about 60 seconds:

git clone https://github.com/CueCrux/Crux.git && cd Crux
cargo build --release --bin corecruxctl
bash scripts/demo-receipt-tamper.sh

The script seeds a CROWN receipt into a tmp data dir, runs corecruxctl verify-store --mode full --strict (expects ok: true), flips one byte on disk, re-runs verification, and asserts the failure is detected. Read the script first — it's ~150 lines of bash using only documented subcommands.

The verifier is ~1,250 lines of Rust at crates/corecrux-receipts/src/verify_v1.rs: ed25519-dalek::verify_strict (rejects malleable signatures and small-order keys), with the signature bound to both receipt ID and payload hash so it can't be transplanted. Tamper tests live in crates/corecrux-receipts/src/tests.rs.

And you can run the same exit test we run in CI — export everything the daemon knows (facts + sessions) and everything it did (signed journal + receipt refs) into one passport-signed bundle, verify that bundle offline, and watch the verifier reject a tampered byte:

corecruxctl context export --data-dir <dir> --out ./bundle   # signed=true
corecruxctl context verify ./bundle --json                   # ok=true, offline, no network

Those checks verify the bundle against the key the bundle carries, which proves it is internally consistent, not who produced it — an unpinned pass is reported as UNPINNED — trust unproven. Add --expect-pubkey-hex <64 hex> (or set CRUX_CONTEXT_VERIFY_PASSPORT_HEX) to also require the signer to be the passport you expected; a bundle re-signed by anyone else then fails.

There is no lock-in: the answer to "can you export it?" and "can you prove what it saw and did?" is a command, not a support ticket. This export → offline-verify → tamper-rejection cycle is a release-blocking CI gate, so every published build has passed its own exit test. Release artifacts are signed and attested end-to-end — cosign keyless signatures, CycloneDX SBOMs, SLSA provenance (docs/verify-release.md). Found something? Report it privately per the security policy.

_{receipts as a literal chain — click any block in the console, inspect the proof}

Testing & coverage: 6,000+ tests and ~90% CI-gated region coverage, with per-crate floors on the trust core (corecrux-receipts / -segment / -storage) and the ungated total reported alongside so exclusions can't hide low-coverage code. How it's measured and exactly what's excluded: docs/testing-and-coverage.md.

Your context window is the scarce resource

Most memory layers measure recall. Crux also measures what recall costs: every retrieval call takes a hard token_budget, and the daemon trims to fit — metadata first, content only when it earns its tokens.

All daemon numbers are reproducible from docs/benchmarks.md with pinned baselines, regression-gated in CI. ScoreCrux methodology, negative controls and per-model runs: scorecrux.com/context · scorecrux.com/scale. Early hosted-retrieval evals via the CoreCrux substrate score ~91% under strict scoring¹.

_{¹ Internal runs via the CoreCrux retrieval substrate (paid tier; see the platform section), not the bare local daemon. Strict scoring, no partial credit. Treat this as preliminary until a public evidence pack with corpus, run ID, lane flags, and commit SHA is published.}

How it works

One daemon, three planes — memory, retrieval, receipts — on an append-only spine. The colours are the console's own: violet for memory, amber for retrieval, mint for receipts. No cloud in this picture; that's the point.

More detail: docs/architecture.md.

Passports, and how the line is drawn

API keys say something with this string called us. A passport says this agent, at this trust tier, with these grants, made this call — identity and constraint, receipted as a verifiable record. What a receipt proves (and what it deliberately does not) is spelled out per event class in the assurance & coverage matrix; forgery-resistant evidence of model traffic comes from the mediated witness path, whose key the agent never holds.

1. Bind — the session handshake binds every connection to a passport. No anonymous writes; unattributed calls are operator-tagged, never silently allowed.
2. Carry — every tool call rides the passport. RCX mints short-lived capability tokens against it — scoped to tools, tenant and tier — so access expires instead of leaking.
3. Earn — verified receipts accrue to the passport as reputation; five tiers climb the capability ladder and unlock more autonomy. Trust is a ledger, not a checkbox.
4. Answer — any receipt, any time later, resolves back to the passport that produced it: who acted, at what tier, under which grants.

The same daemon binary runs on every tier. What changes is a signed RCX capability token — the policy layer that says which backends the daemon may call and what data may cross the wire. Enforcement is a property of the wire, not a crippled binary. Tokens are self-issued locally, verifiable offline with the same machinery as everything else, and refusals are fail-closed with a signed RefusalReceipt carrying a reason code — never a bare 403 or a silent downgrade.

What you get

yes·flag = ships in this repo behind a default-off feature flag — your traces and attestations are opt-in, like everything else. /v1/version reports which features are active.

Standalone by design, platform by choice

Crux is complete on its own. When you want more, it's the memory spine of the CueCrux platform — same receipts, same passports, every hop attributable.

Free forever — the full local daemon: receipts, retrieval, passports, console. Pro (£19/user·mo) adds hosted sync, multi-device passports, and better-dense rerank. Governance (£49/user·mo) adds fleet-wide attribution, policy gates, and revocation that propagates with proof. Metered credits (~£0.01/Cr) buy the heavy lifts — dense rerank, extraction, attestations. The local dense lane is never metered: credits buy the step-up, not your own machine. Every credit spend mints a signed receipt (crux.credit_spend_receipt.v1) — even the meter is auditable. The local daemon is the acquisition, not the upsell. Full ladder: memorycrux.com/pricing.

You cannot pay us to hold your data — there is no such product. Paid frontier ingest and extraction is processed in flight, never parked: enrichment lands back in your store — process, return, delete. Every hop carries a receipt. Local-first isn't a pricing tier; it's the architecture. The promises are written down in the Trust Contract.

The lane stack (each lane is a different way of remembering):

AMR — Adaptive Manifest Routing reads the lane manifest and routes each query automatically — fusing the lanes that earn their tokens, skipping the ones that don't, learning from per-request outcomes. No knobs. It switches on with a subscription and stays off otherwise. Without one you still run the full local daemon — lexical lane, graph fusion, token budgets, receipts. That's not a demo; it's the same engine the paid lanes plug into.

EU AI Act

The Act asks for risk management, logging, transparency and human oversight. Most stacks will answer with PDFs. Crux answers with receipts — the compliance machinery is the same machinery everything else runs on.

These are engineering controls aligned with the Act — not a legal opinion, and conformity assessment for your deployment remains your responsibility. What Crux gives you is the evidence layer: when the auditor asks, you answer with receipts, not screenshots.

Engrams — memory that compiles

Retrieval answers questions. Engrams skip them. When the same lesson keeps getting re-learned from raw history, it's distilled into a named, versioned procedure that arrives before the agent acts — instinct, not search. Engrams carry provenance hashes back to the source chunks they were learned from (you can always audit why the instinct exists), resolve by declared intent at session start, and are gated by passport tier. Local-first: a built-in catalog plus fact-backed overlays serve the same contract with zero cloud dependency.

100+ MCP tools, memory-first

Built MCP-first, not MCP-wrapped: every retrieval tool takes a token budget, every mutation emits a receipt, identity rides a passport. The server lives at http://localhost:14801/mcp.

…and more across substrate entities & edges, work & coordination, and orchestration — 100+ tools today, and counting. The catalogue is token-filtered: a local token sees local tools; hosted-authorised tokens also see hosted-gated tools (descriptions are marked [local] / [hosted]).

Recommended first calls: cuecrux_session → get_bootstrap(topic="patterns") → store_fact(...) → query_facts(...). Full guidance: docs/agent-guide.md · API surface: docs/developer-portal.md.

Operations reference

curl -s -X PUT http://localhost:14800/v1/facts \
  -H "Content-Type: application/json" \
  -H "X-Corecrux-Scopes: facts:write,facts:read,admin:read" \
  -d '{"entity":"project","key":"status","value":"Crux Daemon is running locally","confidence":0.95}' | jq .

curl -s "http://localhost:14800/v1/facts?query=Crux+Daemon&token_budget=500" \
  -H "X-Corecrux-Scopes: facts:read,admin:read" | jq .

docker exec crux-crux-1 corecruxctl verify-store --data-dir /data --scope recent
docker exec crux-crux-1 corecruxctl verify-store --data-dir /data --scope all --mode full --strict

CORECRUXD_EMBEDDING_URL=http://localhost:11434
CORECRUXD_EMBEDDING_MODEL=nomic-embed-text

Community

Built in the open, verified in the open. If Crux is useful to you, a star helps others find it.

Contributing · Security policy · Code of conduct · Changelog · Trust Contract

• Before running a release artifact, verify its signature, SBOM and provenance with docs/verify-release.md.
• Report vulnerabilities privately through SECURITY.md; do not open a public issue for security bugs.
• For non-security bugs or feature requests, use the GitHub issue templates: bug report or feature request.

Licence

Crux Daemon is open source under the Apache License, Version 2.0.

• Commercial use, modification, distribution, and private use are permitted.
• Running Crux as a managed, hosted, or cloud service is permitted.
• Apache-2.0 includes an express patent grant (section 3).
• Redistribution must retain the copyright, licence, and NOTICE attribution (sections 4(a)–4(d)); it grants no trademark rights (section 6).
• Curated content is covered separately by content/LICENCE-CONTENT.md.
• Plain-English answers: docs/LICENCE-FAQ.md.

Copyright (c) 2026 CueCrux Ltd.