Use Claude Code in the morning, switch to Codex CLI in the afternoon — they share the same memory. Debug a tricky auth issue with Claude, open Codex later — it already knows what happened. No re-explaining, no re-reading files. That's not just persistent memory, that's agent interoperability.

Shared memory between Claude Code & Codex CLI | Save ~80-100K tokens/session | Crash recovery | Cross-project intelligence

CogniLayer gives your AI coding agents a shared brain — a local SQLite database with 13 MCP tools, hybrid search, and automatic session tracking. Every fact, decision, gotcha, and debugging session survives across sessions, agents, projects, and crashes.

Claude Code and Codex CLI share the same memory database. Start a task with one, finish with the other. No other tool does this.

Without CogniLayer, your agent re-reads the codebase from scratch every session. With it — a few KB of compact context injected via MCP. Pays for itself on day one.

Session killed? Terminal closed? Computer died? CogniLayer auto-recovers from the change log. Next session picks up where you left off — in either agent.

Solved a CORS issue in project A three weeks ago? Search that knowledge from project B. Your experience compounds across all your projects.

Managing multiple servers? The Identity Card system blocks you from deploying to the wrong one. verify_identity("deploy") before every push to prod.

You start a Claude Code session
    ↓
CogniLayer injects what it knows about your project
(architecture, last session's progress, key decisions)
    ↓
You work normally — Claude saves important things to memory automatically
    ↓
Session ends (or crashes)
    ↓
Next session starts with full context — no re-reading, no re-explaining

Zero effort after install. No commands to learn, no workflow changes. CogniLayer runs in the background via hooks and an MCP server. Claude knows how to use it automatically.

git clone https://github.com/LakyFx/CogniLayer.git
cd CogniLayer
python install.py

That's it. Next time you start Claude Code, CogniLayer is active.

# AI-powered vector search (recommended — finds facts even with different wording)
pip install fastembed sqlite-vec

python install.py --codex    # Codex CLI only
python install.py --both     # Claude Code + Codex CLI

python ~/.cognilayer/mcp-server/server.py --test
# → "OK: All 13 tools registered."

MCP server not connecting? Run the diagnostic tool:

python diagnose.py          # Check everything
python diagnose.py --fix    # Check + auto-fix missing dependencies

• Python 3.11+
• Claude Code and/or Codex CLI
• pip packages: mcp, pyyaml, textual (installed automatically), fastembed, sqlite-vec (optional)

Once installed, use these in Claude Code:

A visual memory browser right in your terminal. 7 tabs, keyboard navigation, works on Windows, Mac, and Linux.

cognilayer                    # All projects
cognilayer --project my-app   # Specific project
cognilayer --demo             # Demo mode with sample data (try it!)

Screenshots show demo mode (cognilayer --demo) with sample data.

The upgrade is safe and non-destructive. Your memory is never lost:

git pull
python install.py

What happens under the hood:

• Code files are replaced with the latest versions
• config.yaml is never overwritten (your settings are safe)
• memory.db is backed up automatically before any migration
• Schema migration is purely additive (new columns/tables, never deletions)
• CLAUDE.md blocks update automatically on next session start

If something goes wrong:

# Your backup is timestamped
cp ~/.cognilayer/memory.db.backup-YYYYMMDD-HHMMSS ~/.cognilayer/memory.db
# Restore old code
git checkout <previous-commit> && python install.py

Edit ~/.cognilayer/config.yaml:

# Language — "en" (default) or "cs" (Czech)
language: "en"

# Your projects directory
projects:
  base_path: "~/projects"

# Indexer settings
indexer:
  scan_depth: 3
  chunk_max_chars: 2000

# Search defaults
search:
  default_limit: 5
  max_limit: 10

• Concurrent CLIs: Running Claude Code and Codex CLI simultaneously on the same project may cause session tracking conflicts. Use one CLI at a time per project.
• Codex file tracking: Codex CLI has no hooks, so automatic file change tracking is not available for Codex sessions.
• TUI: Requires textual package. Read-only except for resolving contradictions.

Everything below is for developers who want to understand how CogniLayer works under the hood.

Claude Code / Codex CLI Session
    │
    ├── SessionStart hook (Claude Code) / session_init tool (Codex)
    │   └── Injects Project DNA + last session bridge into CLAUDE.md
    │
    ├── MCP Server (13 tools)
    │   ├── memory_search    — Hybrid FTS5 + vector search with staleness detection
    │   ├── memory_write     — Store facts (14 types, deduplication, auto-embedding)
    │   ├── memory_delete    — Remove outdated facts by ID
    │   ├── memory_link      — Bidirectional Zettelkasten-style fact linking
    │   ├── memory_chain     — Causal chains (caused, led_to, blocked, fixed, broke)
    │   ├── file_search      — Search indexed project docs (chunked, not full files)
    │   ├── project_context  — Get project DNA + health metrics
    │   ├── session_bridge   — Save/load session continuity summaries
    │   ├── session_init     — Initialize session for Codex CLI (replaces hooks)
    │   ├── decision_log     — Query append-only decision history
    │   ├── verify_identity  — Safety gate before deploy/SSH/push
    │   ├── identity_set     — Configure project Identity Card
    │   └── recommend_tech   — Suggest tech stacks from similar projects
    │
    ├── PostToolUse hook (Claude Code only)
    │   └── Logs every file Write/Edit to changes table (<1ms overhead)
    │
    └── SessionEnd hook / session_bridge(save)
        └── Closes session, builds emergency bridge if needed

~/.cognilayer/
├── memory.db              # SQLite (WAL mode, FTS5, 17 tables)
├── config.yaml            # Configuration (never overwritten by installer)
├── active_session.json    # Current session state (runtime)
├── mcp-server/
│   ├── server.py          # MCP entry point (13 tools)
│   ├── db.py              # Shared DB helper (WAL, busy_timeout, lazy vec loading)
│   ├── i18n.py            # Translations (EN + CS)
│   ├── init_db.py         # Schema creation + migration
│   ├── embedder.py        # fastembed wrapper (BAAI/bge-small-en-v1.5, 384-dim)
│   ├── register_codex.py  # Codex CLI config.toml registration
│   ├── indexer/           # File scanning and chunking
│   ├── search/            # FTS5 + vector hybrid search
│   └── tools/             # 13 MCP tool implementations
├── hooks/
│   ├── on_session_start.py    # Project detection, DNA injection, crash recovery
│   ├── on_session_end.py      # Session close, emergency bridge, episode building
│   ├── on_file_change.py      # PostToolUse file change logger
│   ├── generate_agents_md.py  # Codex AGENTS.md generator
│   └── register.py            # Claude Code settings.json registration
├── tui/                       # TUI Dashboard (Textual)
│   ├── app.py                 # Main application (7 tabs, keyboard nav)
│   ├── data.py                # Read-only SQLite data access layer
│   ├── styles.tcss            # CSS stylesheet
│   ├── screens/               # 7 tab screen modules
│   └── widgets/               # Heat cell, stats card widgets
└── logs/
    └── cognilayer.log

Two search engines combined for maximum recall:

1. FTS5 — SQLite fulltext search for exact keyword matching
2. Vector embeddings — fastembed (BAAI/bge-small-en-v1.5, 384-dim, CPU-only ONNX) with sqlite-vec for cosine similarity
3. Hybrid ranker — 40% FTS5 + 60% vector similarity, with heat score boosting

Vector search is optional — FTS5 works standalone without any extra dependencies.

Facts have a "temperature" that models relevance over time:

Decay rates vary by fact type — error_fix and gotcha facts decay slower (they stay relevant longer) than task facts. Each search hit boosts a fact's heat score.

Codex CLI has no hook system, so CogniLayer adapts:

Same memory database shared between both CLIs.

Deployment safety system that prevents "oops, wrong server" incidents:

• Safety locking — locked fields require explicit update + audit log entry
• Hash verification — SHA-256 detects tampering of safety-critical fields
• Required field checks — verify_identity blocks deploy if critical fields are missing
• Audit trail — every safety field change is logged with timestamp and reason

Contributions are welcome! Please open an issue first to discuss what you'd like to change.

GPL-3.0