CogZ

CI License: MIT Rust Version Buy Me A Coffee

Local-first, code-aware engineering cognition for AI coding agents.

CogZ gives a coding agent persistent memory, contextual retrieval, and continuous cognition about a software repository — all running locally on your machine, no cloud services required.

Works with Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, Devin, and any MCP-compatible agent.

What it looks like

Real output from CogZ running on its own codebase:

$ cogz context --mode task "token budget estimation and context pack compression"

Context pack (mode: task)
Search mode: hybrid
Sections: 50
Token estimate: 5545

---

## 1. [function] get_context (relevance: 0.5000)

pub async fn get_context(
    server: &CogzServer,
    Parameters(params): Parameters<GetContextParams>,
) -> Result<CallToolResult, McpError> {
    let mode = parse_context_mode(mode_str, params.query.as_deref())?;
    ...
}

## 2. [observation] Token budget truncation must account for title token cost (relevance: 0.5000)

The initial `fit_budget` implementation truncated content to
the remaining token budget without accounting for the title's
token cost. A section with a long title could exceed the budget
by `title_tokens` tokens.

Fix: subtract `estimate_tokens(&section.title)` from the
remaining budget before calculating the content truncation.

## 3. [knowledge] Context assembly pipeline (relevance: 0.4633)

The context assembly layer sits on top of search and produces
ContextPack — the primary output of CogZ for agent consumption.

Modules: context/mod.rs (types), context/modes.rs (cold_start,
task, escalation), context/assemble.rs (orchestrator),
context/compress.rs (token estimation, priority sorting, budget).

… 47 more sections …

That's not a text chunk from a vector search. It's the actual function, a bug that was found and fixed during development, and the architecture that ties them together — ranked, traceable through the code graph.

This repository already contains real dogfooding knowledge — CogZ has been used on its own codebase throughout development. You can clone it, install CogZ, and try the commands above against it directly.

What it does

CogZ maintains a project-specific knowledge layer that connects what an agent learns to the code it is working with.

Memory

CogZ stores three kinds of project knowledge:

• Observations — things an agent has learned or noticed. Raw, unvalidated experience: bugs found, decisions made, patterns noticed.
• Rules — validated knowledge that should influence future work. Coding standards, design decisions, confirmed patterns.
• Knowledge — structured information about the codebase. Architecture explanations, module responsibilities, trade-off rationale.

These are stored as Markdown files with YAML frontmatter, linked to each other and to code entities in the repository. The files are the canonical source of truth — SQLite is a derived index, disposable and rebuildable. Your knowledge is portable, version-controlled, and editable by hand.

Context

Instead of giving an agent everything it knows, CogZ builds scoped context packs for the current situation. A context pack combines relevant rules, observations, knowledge, and code structures — ranked by relevance, traceable through the code graph, and limited by a token budget so the agent gets what matters for the task rather than the entire project history.

Cognition

CogZ periodically consolidates what has been learned: deduplicates entries, detects contradictions, promotes well-supported observations to rules, merges superseded entries, and flags knowledge as stale when the code it references changes.

Quick start

Linux / macOS / Windows (Git Bash):

# Install
curl -fsSL https://raw.githubusercontent.com/balaianu/CogZ/master/install.sh | bash

# Initialize in a repo
cd ~/your-project
cogz init

# Index (downloads models on first run, or use --no-download for FTS-only)
cogz index

# Verify it's working — entity counts, model status, DB stats
cogz status

Windows (PowerShell):

# Install
irm https://raw.githubusercontent.com/balaianu/CogZ/master/install.ps1 | iex

# Initialize in a repo
cd your-project
cogz init
cogz index

See Getting Started for the mental model and a complete walkthrough.

MCP integration

CogZ runs as a stateless MCP server over stdio. Every tool call specifies which repo it targets via a required repo parameter — no Roots, no session state, no fallbacks.

{
  "mcpServers": {
    "cogz": {
      "command": "cogz",
      "args": ["mcp-stdio"]
    }
  }
}

The server exposes 13 tools: record_observation, query_observations, create_rule, query_rules, create_knowledge, update_knowledge, query_knowledge, search, get_context, get_status, list_entities, consolidate, capture_event.

See MCP Tools for full parameter reference and example responses. See Agent Setup for configuration examples for Claude Code, Cursor, Devin, and other agents.

Hook integration

Hooks capture lifecycle events and inject context packs into agent sessions. CogZ's binary is the hook handler — no wrapper scripts needed.

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "cogz capture-event session_start --hook-json --fts-only",
        "timeout": 10
      }]
    }]
  }
}

See Hooks for all 7 event types and per-agent wiring guides.

CLI commands

Normal operation is automatic: hooks fire on lifecycle events, the agent drives CogZ through MCP. The CLI is not needed for day-to-day use — it's available for setup, manual exploration, and automation if you want or need it.

Command	Description
cogz init	Initialize .cogz/ in a repository
cogz index [--no-download]	Sync files to DB + index source code
cogz reindex	Incremental reindex (changed files only)
cogz search <query>	Hybrid FTS + vector search
cogz context --mode <mode> [query]	Assemble context pack
cogz status	DB stats, entity counts, model status
cogz consolidate [--dry-run]	Run promotion and merge
cogz capture-event <type>	Capture lifecycle event from hooks
cogz models <download|list|clean>	Model management
cogz doctor [--prune-observations]	Health check + policy violations
cogz update [--check]	Self-update from GitHub releases
cogz reset [--purge]	Drop DB (optionally purge observations)
cogz mcp-stdio	Run MCP server over stdio

See CLI Reference for all flags and options.

Requirements

Minimum (FTS-only mode)

Resource	Requirement
RAM	256 MB free
Disk	50 MB (binary + DB, no models)
CPU	any x86_64 or ARM64

Works without ONNX Runtime or model downloads. All hooks, FTS search, context packs, consolidation, doctor, and prune are functional. Vector search, embedding-based dedup, and contradiction detection are not available.

Recommended (hybrid search mode)

Resource	Requirement
RAM	2 GB free
Disk	550 MB (binary + ONNX Runtime + 3 models + DB)
CPU	any x86_64 or ARM64, 4+ cores speeds up batch embedding

Full functionality including vector search, semantic dedup, and NLI contradiction detection. Models auto-download on first use and auto-unload after 5 min idle (RAM drops back to ~11 MB). See Evaluations for the full resource consumption profile.

Architecture

• Single Rust binary — no runtime dependencies except optional ONNX models for vector search.
• Files are canonical — all entities are Markdown files. The SQLite DB is a derived index, disposable and rebuildable.
• Code-aware — tree-sitter indexes source code as first-class graph entities. Supported languages: Rust, Python, Go, JavaScript, TypeScript, TSX, Bash.
• Graceful degradation — works without ML models in FTS-only mode.
• Local-first — no cloud, no telemetry, no accounts. The only network access is optional model downloads.

See Architecture for the full system design.

Compatibility

Platform	Support	Embeddings	FTS-only	Install
Linux x86_64	Full	Auto-download	Yes	install.sh
Linux aarch64	Full	Auto-download	Yes	install.sh
macOS arm64 (Apple Silicon)	Full	Auto-download	Yes	install.sh
macOS x86_64 (Intel)	Not supported	—	—	—
Windows x86_64	Full	Auto-download	Yes	install.ps1 or install.sh (Git Bash)

macOS Intel is not supported because Microsoft dropped ONNX Runtime macOS Intel binaries after v1.22. Intel Mac users can run the arm64 binary under Rosetta 2 (with a compatible ORT build) or use cargo install cogz for FTS-only mode.

Windows 10+ is required (bsdtar is bundled since build 17063, needed for ONNX Runtime auto-extraction).

Cross-platform team collaboration is supported: code entity UUIDs use forward-slash path normalization so the same source file produces the same entity ID on all platforms.

Documentation

User guides:

• Getting Started — mental model and walkthrough
• Configuration — full config.toml reference
• CLI Reference — every command and flag

Integration:

• MCP Tools — 13 tool parameters and responses
• Hooks — lifecycle events and output format
• Agent Setup — Claude Code, Cursor, Devin, generic MCP

Design:

• Architecture — system overview and module map
• Entity Model — entity types, frontmatter, state machine
• Search — hybrid FTS + vector, RRF, graph expansion
• Consolidation — dedup, contradiction, promotion, merge
• Degradation — FTS-only mode and fallback behavior

Contributing:

• Building — build, release, cross-compile
• Testing — test categories and mock models
• Conventions — code patterns and invariants
• Dependencies — pinned versions and supply-chain policy
• Schema — DB schema and migrations

Contributing

See CONTRIBUTING.md for build, test, and PR guidelines.

License

MIT — see LICENSE.

Support

If you find this tool useful, consider buying me a coffee:

Buy Me A Coffee