Cognix

Structured cognitive architecture for LLMs via the Model Context Protocol.

Cognix is a Rust MCP server that gives LLMs a persistent, structured thinking space. It replaces a 95-line Python "think" scratchpad with production infrastructure: persistent storage, thought graphs, compression, reasoning analysis, semantic search, and multi-agent coordination -- all delivered as a single binary with zero external dependencies.

Key features:

• Persistent thought storage across sessions (SQLite, WAL mode, FTS5)
• 7-stage compression pipeline (rule-based + LLM) with read-time decompression
• Directed thought graphs with PageRank importance scoring
• Semantic search via HNSW embeddings
• Privacy-first: auto-strips API keys, JWTs, passwords; <private> tag support
• Multi-agent session sharing with role-based access
• Fail-open design: MCP tools never return protocol errors for internal failures

Status: Phase 8 (production hardening) | Version: 0.1.0 | License: MIT

---

Architecture

┌──────────────────────────────────────────────────────┐
│                   cognix-server                      │
│              (MCP server binary)                     │
├────────┬────────┬─────────┬────────┬─────────────────┤
│  mcp   │ compr- │ storage │ graph  │    analysis     │
│        │ ession │         │        │ (core + graph)  │
├────────┴────────┴─────────┴────────┴─────────────────┤
│                    cognix-core                       │
│             (types, errors, privacy)                 │
└──────────────────────────────────────────────────────┘

cognix-cli (separate binary: diagnostics, maintenance)

8 crates total (6 libraries + 2 binaries). Dependencies flow strictly downward -- no cycles.

---

Tech Stack

Component	Choice	Why
Language	Rust (2021 edition)	Sub-ms latency, memory safety, single binary
Async runtime	tokio	Industry standard for async Rust
Database	SQLite (rusqlite, WAL, FTS5)	Zero external deps, embedded, concurrent reads
Serialization	serde / serde_json	De facto Rust standard
Errors	thiserror (libs) / anyhow (bins)	Typed errors in libraries, ergonomic propagation in binaries
Logging	tracing	Structured, async-aware instrumentation
Graph	petgraph (StableGraph)	Safe node removal, traversal, PageRank
Vector search	instant-distance (HNSW)	In-process, no external service
Testing	built-in + criterion + cargo-llvm-cov	Fast unit tests, statistical benchmarks, coverage
CI	Forgejo Actions	Self-hosted, GitHub Actions compatible

---

Getting Started

Prerequisites

• Rust toolchain: install via rustup (stable channel)
• Optional dev tools: cargo-deny, cargo-audit, cargo-llvm-cov
• Optional: Ollama for LLM-powered compression

Install from crates.io

Not yet published. See docs/PUBLISHING.md for the publish checklist. Once live, installation will be:

Current release scope: prebuilt binaries are Linux-only, and macOS and Windows remain source-install only.

cargo install cognix-think    # MCP server
cargo install cognix-cli      # maintenance CLI (binary name: cognix)

Install from source

Prebuilt binaries are Linux-only. macOS and Windows remain source-install only.

There are three ways to get the binaries. Choose based on your situation:

Option A — Local build (recommended for development)

Compiles binaries into ./target/release/ inside the project folder. After any code change, just re-run cargo build — binaries update automatically, no reinstall needed:

git clone https://git.yuantech.uk/jesse/cognix.git
cd cognix
cargo build --release --workspace
./target/release/cognix-think    # MCP server
./target/release/cognix          # CLI

Uninstall: delete the project folder. No files are placed outside of it.

rm -rf /path/to/cognix

Option B — Permanent install (recommended for stable use)

Compiles and copies both binaries into ~/.cargo/bin (which is in your PATH), so you can run them as commands from any directory. Downside: you must re-run cargo install after every code change:

cargo install --path crates/cognix-server --locked    # → cognix-think
cargo install --path crates/cognix-cli --locked       # → cognix

# or as a one-liner:
cargo install --path crates/cognix-server --locked && cargo install --path crates/cognix-cli --locked

Uninstall: remove both binaries from ~/.cargo/bin:

cargo uninstall cognix-think
cargo uninstall cognix-cli

Option C — Run directly (recommended for trying it out)

No binary is kept on disk; cargo compiles and runs in one step:

cargo run --release -p cognix-server    # MCP server
cargo run --release -p cognix-cli -- diagnose --path ./cognix.db    # CLI

Uninstall: nothing to uninstall. Delete the project folder if no longer needed.

---

When to use which:

Situation	Use	Uninstall
Actively changing code	Option A — cargo build, binary updates automatically	rm -rf /path/to/cognix
Stable code, want a system-wide command	Option B — cargo install, works from any directory	cargo uninstall cognix-think && cargo uninstall cognix-cli
Just trying it out	Option C — cargo run, nothing installed	Delete project folder

---

Which option for Claude Desktop / Claude Code?

Claude needs a command path it can find. Both of these work:

// After Option A (cargo build) — requires the full absolute path
{ "command": "/path/to/cognix/target/release/cognix-think" }

// After Option B (cargo install) — clean, works from anywhere
{ "command": "cognix-think" }

Option B is simpler in config. Option A always reflects your latest build without a reinstall step.

Optional dashboard UI

The dashboard requires the ui feature at build/install time — it is not in the default feature set. Without it, --enable-ui / --transport sse fail with "SSE transport not compiled in".

# Local build (Option A): add the ui feature
cargo build --release -p cognix-server --features ui
./target/release/cognix-think --transport sse --enable-ui
open http://127.0.0.1:3000/ui
# Override host/port with --host <addr> --sse-port <port>
# (or set [server] host / sse_port in cognix.toml). Default: 127.0.0.1:3000.
# Non-loopback binds require a non-blank bearer_token, but dashboard browser
# access remains loopback/Host-guarded; prefer loopback or a trusted local proxy.
# Disable by removing --enable-ui or setting dashboard_enabled = false.

# Permanent install (Option B): add the ui feature here too
cargo install --path crates/cognix-server --locked --features ui   # → cognix-think
cargo install --path crates/cognix-cli --locked                    # → cognix

A PATH-installed cognix-think runs from whatever directory the dashboard or client launches it in, which usually has no cognix.toml. Pin storage with the COGNIX_STORAGE_* env vars (see storage caveat below) so the dashboard reads the same database your thoughts are written to.

Configure MCP client

For automatic Claude Desktop or Claude Code registration, see docs/SETUP.md:

cognix setup --client claude-code --dry-run
cognix setup --client claude-code

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cognix": {
      "command": "cognix-think",
      "env": {
        "COGNIX_STORAGE_BACKEND": "sqlite",
        "COGNIX_STORAGE_PATH": "/abs/path/to/cognix.db"
      }
    }
  }
}

Claude Code (.mcp.json):

{
  "mcpServers": {
    "cognix": {
      "type": "stdio",
      "command": "cognix-think",
      "env": {
        "COGNIX_STORAGE_BACKEND": "sqlite",
        "COGNIX_STORAGE_PATH": "/abs/path/to/cognix.db"
      }
    }
  }
}

Storage config — pin it

The in-memory default trap. Cognix resolves its storage backend from built-in defaults → a cognix.toml in the current working directory → COGNIX_* env vars (highest precedence). The built-in default backend is in-memory, not SQLite. An MCP server launched from a directory with no cognix.toml (a PATH-installed binary, or a global MCP server spawned in some other project's directory) therefore silently uses in-memory storage: think returns an ID, but nothing is persisted to disk and it is lost on exit and invisible to the dashboard.

Always pin the backend and an absolute DB path via the env block above (COGNIX_STORAGE_BACKEND="sqlite", COGNIX_STORAGE_PATH=/abs/path/to/cognix.db). Point every cognix-think instance — project config, any global MCP config, and the dashboard — at the one canonical cognix.db so thoughts land where the dashboard reads them. See docs/RUNNING.md → Troubleshooting.

Restarting the MCP Server

After rebuilding the binary (cargo build --release), you must restart the MCP server to pick up the changes. The server runs as a subprocess of Claude Desktop/Code and persists across tool calls.

Claude Code:

# Option 1: Restart Claude Code entirely (cleanest)
# Close and reopen the Claude Code session

# Option 2: Kill the server process (it auto-restarts on next tool call)
pkill -f cognix-think

# Option 3: Use Claude Code's /mcp command to check server status
# Then restart if needed

Claude Desktop:

# Restart the Claude Desktop app, or:
pkill -f cognix-think
# The server auto-restarts when you next use a Cognix tool

Verify the restart worked:

# Check which binary is running
pgrep -fl cognix-think

# Check binary modification time vs process start time
stat -f "%Sm" ./target/release/cognix-think  # macOS
stat -c "%y" ./target/release/cognix-think   # Linux
ps -p $(pgrep -f cognix-think) -o lstart=

If the process start time is before the binary modification time, the server is still running old code.

---

Project Structure

cognix/
├── crates/
│   ├── cognix-core/          # Domain types, errors, privacy, tokenizer
│   ├── cognix-compression/   # 7-stage pipeline, LLM compressor, cache
│   ├── cognix-storage/       # ThoughtStorage trait, Memory + SQLite backends
│   ├── cognix-mcp/           # JSON-RPC protocol, tool registry, tool definitions
│   ├── cognix-graph/         # Thought graph, PageRank, traversal, visualization
│   ├── cognix-analysis/      # Quality scoring, bias detection, pattern analysis
│   ├── cognix-server/        # MCP server binary, transports, embedding providers
│   └── cognix-cli/           # Diagnostics and maintenance CLI
├── tests/integration/        # Cross-crate integration tests
├── benches/                  # Criterion benchmarks
├── testdata/                 # Golden files, test corpus, benchmark data
├── docs/                     # Architecture docs, phase plans, standards
└── .forgejo/workflows/       # CI/CD pipeline definitions

See docs/pre-work/directory-structure.md for full crate internals.

---

Development Workflow

Setup

git clone https://git.yuantech.uk/jesse/cognix.git
cd cognix
cargo run -p xtask -- setup-hooks      # Enable tracked git hooks safely
cargo build --workspace                # Verify everything compiles
cargo test --workspace                 # Run all tests

Branching and commits

• Branch naming: phase-N/description, fix/description, hotfix/description
• Commit format: <type>: <description> (imperative mood, lowercase, no period)
• Types: feat, fix, refactor, docs, test, chore, perf, ci
• Merge strategy: squash merge, auto-delete branch

Because Cognix uses squash merges, CI treats the PR title as the release-facing conventional-commit check. Keep main and release/** branch-protected; the push-path validation job is fallback detection for bypasses and any failure there must be remediated before the branch is considered releasable.

Key conventions

• Immutable by default -- create new values, don't mutate
• No unwrap() in library code -- use ? or explicit error handling
• tracing for all logging -- never println! or eprintln!
• Sensitive<T> wrapper for thought content -- errors must never contain content
• Fail-open: MCP tools return degraded results, never JSON-RPC errors for internal failures
• Functions < 50 lines, files < 400 lines (800 hard max)

---

Testing

cargo test --workspace                    # All tests
cargo test -p cognix-core                 # Single crate
cargo llvm-cov --workspace               # Coverage report (80% minimum)
cargo bench                              # Criterion benchmarks

Layer	Location	What it covers
Unit	#[cfg(test)] mod tests in each module	Functions and types in isolation
Integration	tests/integration/	Cross-crate behavior, MCP protocol, golden files
Benchmarks	benches/	Latency targets (store, query, compress, traverse)

• TDD workflow: write test first (RED), implement (GREEN), refactor (IMPROVE)
• Golden files: testdata/golden/ for Python parity verification
• Coverage gate: 80% global; per-crate minimums (core 85%, graph/analysis 75%)
• Test naming: test_[function]_[scenario]_[expected]

---

CI/CD

All CI runs on self-hosted Forgejo Actions (.forgejo/workflows/).

PR pipeline (all must pass to merge)

Gate	Command	Threshold
Conventional PR title	cargo run -p xtask -- validate-conventional --kind pr-title --message "<title>"	Required on PRs; push fallback covers main and release/**
Format	cargo fmt --all -- --check	Zero violations
Lint	cargo clippy --workspace --all-targets -- -D warnings	Zero warnings
Test	cargo test --workspace	All pass
Coverage	cargo llvm-cov --fail-under-lines 80	>= 80% line coverage
Audit	cargo audit	Zero CRITICAL/HIGH CVEs
Deny	cargo deny check	Zero license/advisory violations
Doc	cargo doc --workspace --no-deps	Zero warnings
Build	cargo build --release --workspace	Compiles cleanly

Release pipeline (on v* tags)

Builds Linux release artifacts, generates changelog metadata from conventional commits, creates Forgejo releases, and leaves macOS/Windows in source-install-only status until native release automation is added. Native source-install smoke remains covered separately by .github/workflows/source-smoke.yml on macos-13, macos-14, and windows-2022.

Target	Binary
x86_64-unknown-linux-gnu	cognix-think-linux-x86_64
aarch64-unknown-linux-gnu	cognix-think-linux-aarch64

---

Contributing

1. Read CLAUDE.md for project conventions
2. Read docs/STANDARDIZATION/STANDARDIZATION.md for full standards
3. Follow TDD: write test first, then implementation
4. Run the full check before opening a PR:

cargo fmt --check \
  && cargo clippy --workspace --all-targets -- -D warnings \
  && cargo test --workspace

5. Never log thought content or include it in error messages -- use Sensitive<T>
6. Never commit secrets -- use cognix.secrets.toml (gitignored, 0600 permissions)

---

Documentation

Document	Description
docs/RUNNING.md	Operations guide: running, configuration, maintenance
docs/PUBLISHING.md	Publishing guide: crates.io publish order, CI setup, version bumping
CLAUDE.md	Project conventions, tech stack, build commands
docs/pre-work/analysis.md	Full analysis: phases, decisions, risks
docs/pre-work/directory-structure.md	Workspace layout, crate internals
docs/pre-work/data-flow.md	Request flows, schema, API contracts
docs/pre-work/success-criteria.md	30 CRITICAL criteria for MVP
docs/STANDARDIZATION/	Naming, style, errors, git workflow
docs/BLUEPRINT/cicd-pipeline.md	CI/CD pipeline details
docs/BLUEPRINT/testing-strategy.md	Testing approach and conventions
docs/BLUEPRINT/design-patterns.md	Design patterns used in Cognix
docs/BLUEPRINT/code-review-standards.md	Code review process

---

License

MIT License. See Cargo.toml for details.