Infinite speed memory · Code graph · 200K+ tokens saved
Without CogniLayer, your AI agent starts every session blind. It re-reads files, re-discovers architecture, re-learns decisions you explained last week. On a 50-file project, that's 80-100K tokens burned before real work begins.
With CogniLayer, it already knows. Three things your agent doesn't have today:
🔗 Persistent knowledge across agents - facts, decisions, error fixes, gotchas survive across sessions, crashes, and agents. Start in Claude Code, continue in Codex CLI - zero context loss
🔍 Code intelligence - who calls what, what depends on what, what breaks if you rename a function. Tree-sitter AST parsing across 10+ languages, not grep
🤖 Subagent context compression - research subagents write findings to DB instead of dumping 40K+ tokens into parent context. Parent gets a 500-token summary + on-demand memory_search retrieval
⚡ 80-200K+ tokens saved per session - semantic search replaces file reads, subagent findings go to DB instead of context. Longer sessions with subagents save more
You: "Fix the login bug"
Claude: Let me read the project structure...
Let me read src/auth/login.ts...
Let me read src/auth/middleware.ts...
Let me read src/config/database.ts...
Let me understand your auth flow...
(8 files read, 45K tokens burned, 2 minutes spent on orientation)
Claude: "Ok, I see the issue..."
You: "Fix the login bug"
Claude: [memory_search → "login auth flow"] → 3 facts loaded (200 tokens)
[code_context → "handleLogin"] → caller/callee map in 0.2s
Already knows: Express + Passport, JWT in httpOnly cookies,
last login bug was a race condition in session refresh (fixed 2 weeks ago)
Claude: "This looks like the same pattern as the session refresh issue
from March 1st. The fix is..."
That's not a small improvement. That's the difference between an agent that guesses and one that knows.
Without CogniLayer, Claude reads 15 files to understand your e-commerce flow. With it:
memory_search("checkout payment flow")
→ fact: "Stripe webhook hits /api/webhooks/stripe, validates signature
with STRIPE_WEBHOOK_SECRET, then calls processOrder()"
→ gotcha: "Stripe sends webhooks with 5s timeout - processOrder must
complete within 5s or webhook retries cause duplicate orders"
→ error_fix: "Fixed duplicate orders on 2026-02-20 by adding
idempotency key check in processOrder()"
code_impact("processOrder")
→ depth 1: createOrderRecord, sendConfirmationEmail, updateInventory
→ depth 2: InventoryService.reserve, EmailQueue.push
→ "Changing processOrder will affect 6 functions across 4 files"
Claude already knows the architecture, the past bugs, and what will break if it touches the wrong thing. Instead of 15 file reads (~60K tokens), it uses 3 targeted queries (~800 tokens).
Without CogniLayer, Claude greps for the function name and hopes for the best. With it:
code_context("processOrder")
→ definition: src/services/order.ts:42
→ incoming (who calls it): StripeWebhookHandler.handle, OrderController.retry,
AdminPanel.reprocessOrder
→ outgoing (what it calls): createOrderRecord, sendConfirmationEmail,
updateInventory, PaymentLog.write
code_impact("processOrder")
→ depth 1 (WILL BREAK): StripeWebhookHandler, OrderController, AdminPanel
→ depth 2 (LIKELY AFFECTED): WebhookRouter, RetryQueue, AdminRoutes
→ depth 3 (NEED TESTING): 3 test files, 1 integration test
→ "Changing processOrder will affect 9 symbols across 7 files"
Before touching a single line, Claude knows the full blast radius - which files will break, which need testing, and which callers depend on the current behavior. No more surprise failures after a refactor.
code_search("UserService")
→ class UserService in src/services/user.ts (line 14)
→ 12 references across 8 files
code_impact("UserService")
→ depth 1: AuthController, ProfileController, AdminPanel (WILL BREAK)
→ depth 2: LoginRoute, RegisterRoute, middleware/auth (LIKELY AFFECTED)
→ depth 3: 4 test files (NEED UPDATING)
memory_search("UserService")
→ decision: "UserService handles both auth and profile - planned split
into AuthService + ProfileService (decided 2026-02-15, not yet done)"
Claude doesn't just find-and-replace. It knows there's a planned split and can suggest doing both changes at once - saving you a future refactoring session.
[SessionStart hook fires automatically]
→ bridge loaded: "Progress: Migrated 3/5 API endpoints to v2 format.
Done: /users, /products, /orders. Open: /payments, /shipping.
Blocker: /payments needs Stripe SDK v12 upgrade first."
memory_search("stripe sdk upgrade")
→ gotcha: "Stripe SDK v12 changed webhook signature verification -
verify() is now async, breaks all sync handlers"
Zero re-explanation. Claude picks up exactly where it left off, including the blocker you hadn't mentioned yet.
Without CogniLayer, the subagent returns a 40K-token dump into parent context:
Parent (200K context):
→ spawn subagent: "Research community MCP servers"
← subagent returns: 40K tokens about 15 projects
→ all 40K crammed into parent context
→ remaining: 160K → next subagent → 120K → next → 80K...
With CogniLayer's Subagent Memory Protocol:
Parent (200K context):
→ spawn subagent: "Research MCP servers, save to memory"
← subagent writes details to DB, returns: "Saved 3 facts,
search 'MCP server ecosystem'. Summary: Python dominates,
FastMCP most popular, 3 architectural patterns."
→ parent context: ~500 tokens
→ need details? memory_search("MCP server ecosystem") → targeted pull
40K tokens compressed to 500. The findings persist in DB across sessions - not just for this conversation, but forever.
| Feature | What it means |
|---|---|
| Code Intelligence | code_context shows who calls what. code_impact maps blast radius before you touch anything. Powered by tree-sitter AST parsing |
| Semantic Search | Hybrid FTS5 + vector search finds the right fact even with different wording. Sub-millisecond response |
| 17 MCP Tools | Memory, code analysis, safety, project context - Claude uses them automatically, no commands needed |
| Token Savings | 3 targeted queries (~800 tokens) replace 15 file reads (~60K tokens). Typical session saves 80-200K+ tokens |
| Subagent Protocol | Research subagents save findings to DB instead of flooding parent context. 40K → 500 tokens per subagent task |
| Crash Recovery | Session dies? Next one auto-recovers from the change log. Works across both agents |
| Cross-Project Knowledge | Solved a CORS issue in project A? Search it from project B. Your experience compounds |
| 14 Fact Types | Not dumb notes - error_fix, gotcha, api_contract, decision, pattern, procedure, and more |
| Heat Decay | Hot facts surface first, cold facts fade. Each search hit boosts relevance |
| Safety Gates | Identity Card system blocks deploy to wrong server. Audit trail on every safety change |
| Agent Interop | Claude Code and Codex CLI share the same brain. Switch agents mid-task, zero context loss |
| Session Bridges | Every session starts with a summary of what happened last time |
| TUI Dashboard | Visual memory browser with 7 tabs - see everything at a glance |
You start a session
↓
SessionStart hook fires → injects project DNA, last session bridge, crash recovery
↓
You work normally - Claude saves facts, decisions, gotchas automatically via MCP tools
↓
You ask about code → code_context / code_impact answer in milliseconds from AST index
↓
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 MCP tools. Claude knows how to use it automatically.
git clone https://github.com/LakyFx/CogniLayer.git
cd CogniLayer
python install.pyThat'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-vecpython install.py --codex # Codex CLI only
python install.py --both # Claude Code + Codex CLIpython ~/.cognilayer/mcp-server/server.py --test
# → "OK: All 17 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),tree-sitter-language-pack(optional, for code intelligence)
Once installed, use these in Claude Code:
| Command | What it does |
|---|---|
/status |
Show memory stats and project health |
/recall [query] |
Search memory for specific knowledge |
/harvest |
Extract and save knowledge from current session |
/onboard |
Scan your project and build initial memory |
/onboard-all |
Batch onboard all projects in your workspace |
/forget [query] |
Delete specific facts from memory |
/identity |
Manage deployment Identity Card |
/consolidate |
Organize memory - cluster, detect contradictions, assign tiers |
/tui |
Launch the visual dashboard |
/cognihelp |
Show all available commands |
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.pyWhat happens under the hood:
- Code files are replaced with the latest versions
config.yamlis never overwritten (your settings are safe)memory.dbis 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.pyEdit ~/.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.
- Code intelligence: Requires
tree-sitter-language-pack(~20MB). Without it, all other 13 tools work normally. - TUI: Requires
textualpackage. 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 (17 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
│ ├── code_index - Index codebase via tree-sitter AST parsing
│ ├── code_search - Find symbols (functions, classes, methods) by name
│ ├── code_context - 360° view: callers, callees, child methods
│ └── code_impact - Blast radius analysis (BFS traversal of references)
│
├── PostToolUse hook (Claude Code only)
│ └── Logs every file Write/Edit to changes table (<1ms overhead)
│
├── PreCompact hook (Claude Code only)
│ └── Saves comprehensive bridge before context compaction
│
└── 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 (17 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
│ ├── code/ # Code Intelligence (tree-sitter parsers, indexer, resolver)
│ └── tools/ # 17 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 + context monitoring
│ ├── on_pre_compact.py # PreCompact bridge preservation
│ ├── 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
| Table | Purpose |
|---|---|
projects |
Registered projects with auto-generated DNA |
facts |
14 types of atomic knowledge units with heat scores |
facts_fts |
FTS5 fulltext index on facts |
file_chunks |
Indexed project documentation (PRDs, READMEs, configs) |
chunks_fts |
FTS5 fulltext index on chunks |
decisions |
Append-only decision log |
sessions |
Session records with bridges, episodes, and outcomes |
changes |
Automatic file change log (PostToolUse) |
project_identity |
Identity Card (SSH, ports, domains, safety locks) |
identity_audit_log |
Safety field change audit trail |
tech_templates |
Reusable tech stack templates |
fact_links |
Zettelkasten bidirectional links between facts |
knowledge_gaps |
Tracked weak/failed searches |
fact_clusters |
Memory consolidation output clusters |
contradictions |
Detected conflicting facts |
causal_chains |
Cause → effect relationship tracking |
retrieval_log |
Search quality tracking (queries, hit counts, latency) |
code_files |
Indexed source files with hash-based change detection |
code_symbols |
AST-parsed symbols (functions, classes, methods, interfaces) |
code_references |
Symbol cross-references (calls, imports, inheritance) |
facts_vec / chunks_vec |
Vector embeddings (sqlite-vec, optional) |
Two search engines combined for maximum recall:
- FTS5 - SQLite fulltext search for exact keyword matching
- Vector embeddings - fastembed (BAAI/bge-small-en-v1.5, 384-dim, CPU-only ONNX) with sqlite-vec for cosine similarity
- 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:
| Range | Label | Meaning |
|---|---|---|
| 0.7 - 1.0 | Hot | Recently accessed, high relevance |
| 0.3 - 0.7 | Warm | Moderately recent |
| 0.05 - 0.3 | Cold | Old, rarely accessed |
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.
Powered by tree-sitter AST parsing with language-pack support for 10+ languages:
| Tool | What it does |
|---|---|
code_index |
Scans project files, parses AST, extracts symbols and references into SQLite. Incremental - only re-indexes changed files |
code_search |
FTS5 search over symbol names. Find any function, class, or method by name or partial match |
code_context |
360° view of a symbol: definition, who calls it (incoming), what it calls (outgoing), child methods |
code_impact |
Blast radius analysis - BFS traversal of incoming references. Shows what breaks at depth 1/2/3 |
Indexing runs with a configurable time budget (default 30s). Partial results are usable immediately. Unresolved references are re-resolved on the next incremental run.
When Claude spawns research subagents, the raw findings can be 40K+ tokens. Without the protocol, all of that goes into the parent's context window. The Subagent Memory Protocol uses the CogniLayer database as a side channel:
Subagent Parent
│ │
├── research (WebSearch, Read...) │
├── synthesize findings │
├── memory_write(consolidated facts) │ ← data goes to DB, not context
└── return: 500-token summary ────────┤ ← only summary enters context
│
memory_search() ──┤ ← parent pulls details on demand
Key design decisions:
- Synthesis over granularity - subagents group related findings into cohesive facts, not one-per-discovery
- Task-specific tags - each subagent gets a unique tag (e.g.
tags="subagent,auth-review") for filtering viamemory_search(tags="auth-review") - Keywords inside facts - each fact ends with
Search: keyword1, keyword2so retrieval works even after context compaction - Write-last pattern - all
memory_writecalls happen as the last step before return, saving subagent turns and tokens - Foreground-first - subagents launch as foreground (reliable MCP access), user can Ctrl+B to background
- Graceful fallback - if MCP tools are unavailable, findings go directly in return text
The protocol is injected into CLAUDE.md automatically and requires no user configuration.
Codex CLI has no hook system, so CogniLayer adapts:
| Aspect | Claude Code | Codex CLI |
|---|---|---|
| Config | ~/.claude/settings.json |
~/.codex/config.toml |
| Hooks | SessionStart/End/PreCompact/PostToolUse | None - uses MCP tools + AGENTS.md instructions |
| Instructions | CLAUDE.md |
AGENTS.md (generated by generate_agents_md.py) |
| Session init | Automatic via hook | session_init MCP tool called per AGENTS.md instructions |
| File tracking | Automatic via PostToolUse | Not available (acceptable limitation) |
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_identityblocks 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.
Elastic License 2.0 - Free to use, modify, and distribute. You may not provide it as a managed/hosted service.
