Cognex

Your AI forgets everything. Cognex doesn't.

Give your AI coding assistant persistent memory, decision tracking, trust management, and now — structured cognitive state that survives across sessions and agents.

Why Use It?

You: "Remember I prefer pytest over unittest"

Next session:
AI: "Got it — I'll use pytest as we discussed."

Your AI forgets everything between sessions. Cognex fixes that — and in v0.1.7, it does it with full structured cognitive state tracking, concurrent session support, and audit logging.

What's New in v0.1.7

• Concurrent Sessions: Support multiple active sessions per context with thread-safe _sessions dict
• Audit Logging: Structured append-only event log with checksums (created audit_log table in v9 migration)
• Audit Tools: New MCP tools audit_get_recent() and audit_verify() for retrieving and verifying audit events
• Wired Audit Calls: All 6 core MCP tools now log events: session_start, session_end, unit_commit, unit_overridden, bundle_created, bundle_rehydrated
• DB Path Centralization: Changed default DB path from .substrate/ to ~/.cognex.db/ in user home directory
• Graceful Error Handling: Non-blocking audit logging with graceful database lock handling

What Was New in v0.1.6

• Cognitive Units: First-class structured state with content, rationale, scope, and confidence
• Delta Tracking: Append-only change log per unit — full audit trail of how cognition evolved
• Staleness Scoring: Computed on read from override count, last verified age, and confidence
• Selective Retrieval: get_relevant_units() scores by BM25 + confidence + recency + scope match
• Cognitive Snapshot: export_snapshot() returns full structured CHP handoff bundle with delta trail
• 8 New MCP Tools: unit_commit, unit_checkout, unit_search, unit_mark_overridden, unit_verify, unit_get_relevant, unit_export_snapshot, unit_decay_stale
• TeleportBundle Enhancement: Now carries cognitive_units for full cross-machine cognitive state transfer
• CLI Fix: cognex --status now working (was reported done in 0.1.5 but not implemented until now)

Features

Quick Install

Option A — Auto-installer (Recommended)

uvx cognex --install

Detects your AI tool (Claude Code, OpenCode, Cursor, VS Code, etc.) and writes the correct config automatically.

Option B — One command (Terminal)

Mac/Linux:

curl -fsSL https://raw.githubusercontent.com/Gaurav7974/cognex/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/Gaurav7974/cognex/main/install.ps1 | iex

Option C — Paste this into your AI agent

Install and configure the cognex MCP server on my system.

Steps:
1. Run: pip install cognex
2. Detect which AI tool I am using (Claude Code / OpenCode / Cursor / Codex / VS Code)
3. Find the correct MCP config file for this tool
4. Add cognex to the config:
   - command: "cognex"
   - no extra args needed
5. Tell me to restart my AI tool
6. After I restart, call cognex_start_session with session_id "setup-verify" to confirm it works

Option D — Manual

See the Configuration section below.

Check Your Status

New in v0.1.5 — inspect your memory bank without starting the server:

cognex --status

Output:

Cognex v0.2.0
─────────────────────────
Memories:       142
Decisions:       38
Trust records:   21
DB path:        ~/.cognex.db/cognex.db

Configured tools:
  ✓ Claude Code
  ✓ OpenCode

Supported AI Tools

Installation

Option 1: uvx (Recommended — no install needed)

uvx cognex

Option 2: pipx (isolated environment)

pipx install cognex

Option 3: pip

pip install cognex

Option 4: From source

git clone https://github.com/Gaurav7974/cognex
cd cognex
pip install -e .

Verify

cognex --help
cognex --status

Configuration by AI Tool

Claude Code

claude mcp add cognex -- uvx cognex

Or manually in ~/.claude.json or .mcp.json:

{
  "mcpServers": {
    "cognex": {
      "command": "uvx",
      "args": ["cognex"]
    }
  }
}

Claude Desktop

Config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "cognex": {
      "command": "uvx",
      "args": ["cognex"]
    }
  }
}

OpenCode

Config file: ~/.config/opencode/opencode.json or opencode.json in project root

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cognex": {
      "type": "local",
      "command": ["uvx", "cognex"],
      "enabled": true
    }
  }
}

Note: OpenCode uses "mcp" not "mcpServers", and requires "type": "local".

Cursor

Config: ~/.cursor/mcp.json

{
  "mcpServers": {
    "cognex": {
      "command": "uvx",
      "args": ["cognex"]
    }
  }
}

Note: Cursor caps at 40 tools. Cognex uses 20, well within limit.

VS Code (GitHub Copilot Agent Mode)

Config: .vscode/mcp.json in workspace, or Command Palette → MCP: Open User Configuration

{
  "servers": {
    "cognex": {
      "command": "uvx",
      "args": ["cognex"]
    }
  }
}

Note: VS Code uses "servers" not "mcpServers".

Cline

Open Cline → MCP Servers → Configure tab → Edit Config:

{
  "mcpServers": {
    "cognex": {
      "command": "uvx",
      "args": ["cognex"],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Windsurf

Config: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "cognex": {
      "command": "uvx",
      "args": ["cognex"]
    }
  }
}

Zed

Config: ~/.config/zed/settings.json

{
  "context_servers": {
    "cognex": {
      "command": {
        "path": "uvx",
        "args": ["cognex"]
      }
    }
  }
}

Config Format Reference

After Adding Config

Completely close and reopen your AI tool. You should see 20 new Cognex tools available.

Verify in Claude Code:

/mcp
→ cognex: connected

Verify in OpenCode:

/mcp
→ cognex: Connected

The 20 Tools

Session Management

Memory

Trust Engine

Decision Ledger

Teleportation

Swarm

Pattern Intelligence

MCP Prompts

Example Usage

Remember a Preference

You: "I prefer using type hints everywhere"
AI:  (calls memory_add)
→   Saved to your memory bank

Pick Up Where You Left Off

You: (start new session)
AI:  (calls memory_get_context with "current project")
→   Returns decisions, preferences, and progress from last session
AI:  "Continuing from where we left off — you were building the auth module."

Track a Decision

You: "FastAPI or Flask?"
AI:  "FastAPI has better type safety for your use case."
AI:  (calls ledger_record)

Later...
You: "Did that work out?"
AI:  (calls ledger_outcome — success: true)

Teleport Your Brain to Another Machine

# On machine A
cognex teleport export → generates bundle.json (Ed25519 signed)

# On machine B
cognex teleport import bundle.json → full state restored, signature verified

Where Data Lives

All data stays local in SQLite under the centralized ~/.cognex.db/ directory in your user home folder:

~/.cognex.db/
├── cognex.db     — unified database (memories, sessions, cognitive units, trust records, decision ledger, audit logs)
└── keys/
    ├── signing_key.pem  — Ed25519 private key (generated on first run, never leaves your machine)
    └── signing_key.pub  — Ed25519 public key

Troubleshooting

"command not found"

pip install cognex
# or use uvx in your config — no install needed

Tools not appearing

1. Completely close and reopen your AI tool (not just reload)
2. Check developer console for JSON parse errors
3. Validate your config JSON at jsonlint.com
4. Run cognex --status to confirm the DB is accessible

Stale uvx cache

uvx cognex@latest  # force fetch latest version

Development

git clone https://github.com/Gaurav7974/cognex
cd cognex
pip install -e ".[dev]"
pytest tests/ -v

Roadmap

• v0.1.6 — Cognitive Units: structured decisions with rationale, scope, and confidence
• v0.1.7 — Selective retrieval: load only what matters for the current task
• v0.1.8 — Audited handoff protocol: full CHP compliance for multi-agent workflows
• v0.2.0 — Persistent agent identity: agents that resume instantly with full cognitive context

License

MIT — free to use, modify, and distribute.

Need Help?

• Issues: https://github.com/Gaurav7974/cognex/issues
• PyPI: https://pypi.org/project/cognex/
• Docs: see docs/ folder