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 0 (workspace bootstrap) | Version: pre-release | License: TBD

---

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

cargo install cognix-think

Build from source

git clone https://git.yuantech.uk/jesse/cognix.git
cd cognix
cargo build --workspace

Run

# Start MCP server (stdio transport)
cargo run -p cognix-server

# Or after install
cognix-think

Configure MCP client

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cognix": {
      "command": "cognix-think"
    }
  }
}

Claude Code (.mcp.json):

{
  "mcpServers": {
    "cognix": {
      "command": "cognix-think",
      "type": "stdio"
    }
  }
}

---

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
git config core.hooksPath .githooks    # Enable pre-commit and commit-msg hooks
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

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
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	Compiles cleanly

Release pipeline (on v* tags)

Cross-compiles for 5 platforms, strips binaries, generates changelog from conventional commits, creates Forgejo release with artifacts, and publishes to crates.io.

Target	Binary
x86_64-unknown-linux-gnu	cognix-think-linux-x86_64
aarch64-unknown-linux-gnu	cognix-think-linux-aarch64
aarch64-apple-darwin	cognix-think-macos-arm64
x86_64-apple-darwin	cognix-think-macos-x86_64
x86_64-pc-windows-msvc	cognix-think-windows-x86_64.exe

---

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
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

License TBD.