🛑 The Context Compaction Problem
You tell Claude: "Use REST not GraphQL — our team only knows REST."
Forty turns later, Claude suggests GraphQL.
It remembered the decision. It forgot the reason. It ignored the constraint.
Every other memory tool — CLAUDE.md, claude-mem, Cursor memory — stores flat facts. "Use REST."
Claude sees "Use REST" and thinks: that's a suggestion I can override if something better comes along. And it does. Because nothing tells it why REST is non-negotiable.
⚡ How Crux Solves It (The Causal Graph)
Crux stores decisions as a causal dependency graph:
CONSTRAINT ⛔ Team only knows REST — GraphQL is not an option
↓
RATIONALE 💡 REST is the only viable choice given team skills
↓
DECISION ▸ Use REST not GraphQL
↑ These are welded together.
Compaction cannot drop one without dropping all.
Claude sees the WHY every single time.
This is the co-inclusion guarantee. The reason travels with the decision. Always.
The pipeline runs on every prompt:
User message
│
▼
┌──────────┐ ┌─────────────┐ ┌──────────┐ ┌─────────┐ ┌────────┐
│ Decompose│──▶│ Deduplicate │──▶│ Select │──▶│ Compile │──▶│ Verify │
│ (extract │ │ (Jaccard │──▶│ (budget │ │ (format │ │(orphan │
│ atoms) │ │ similarity)│ │ + co- │ │ block) │ │ check) │
└──────────┘ └─────────────┘ │ include) │ └─────────┘ └────────┘
└──────────┘
│
▼
additionalContext
injected alongside
the user's prompt
🚀 Quick Install
Crux runs as a native plugin for Claude Code.
No npm install. No config files. Works immediately.
# 1. Add the marketplace
/plugin marketplace add akashp1712/claude-marketplace
# 2. Install the plugin
/plugin install crux@akashp1712
(Requires Node.js 18+ and Claude Code)
✨ Features at a Glance
- Causal Memory Graph: 12 atom types linked in a directed acyclic graph. Decisions carry their rationale and constraints.
- Auto-Extraction: Understands decisions from natural conversation — no manual tagging.
- Smart Selection: Scores atoms by relevance × type weight × PageRank importance × recency. Only the most relevant atoms are injected, respecting a token budget.
- Co-Inclusion Guarantee: A decision is never injected without all its ancestor atoms. If the budget can't fit the chain, the whole group is skipped — no orphans.
- Compaction Immunity: On
PreCompact, injects group instructions forbidding Claude from separating a decision from its rationale. On resume, the full graph is reloaded from disk.
- Session-Scoped Storage: Each Claude session gets its own graph at
.claude/.crux/sessions/<session_id>.json. Sessions don't interfere. Promote to permanent CLAUDE.md only when you want.
- Smart Deduplication: Rephrase the same decision — Crux recognizes semantic similarity (Jaccard) and merges instead of duplicating.
- Multi-Mode Extraction:
local (default): 100% offline, zero-cost, regex-based — extracts CONSTRAINT, RATIONALE, DECISION, GOAL.api: Full semantic extraction via Anthropic or AWS Bedrock. All 12 atom types.hybrid: Local first, falls back to API for substance-dense messages with low local confidence.
🔬 The 12 Atom Types
