Cogni Layer

🧠 CogniLayer v4

停止向AI重新解释你的代码库。

无限速度记忆·代码图·节省200K+代币

如果没有CogniLayer，您的AI代理将盲目启动每个会话。它重新读取文件，重新发现架构，重新学习您上周解释的决策。在一个50个文件的项目中，在真正的工作开始之前，要烧掉80-100K个代币。

有了CogniLayer，它已经知道了。你的经纪人今天没有三样东西：

🔗 跨代理的持久知识 -事实、决策、错误修复、陷阱在会话、崩溃和代理中都存在。从Claude Code开始，在Codex CLI中继续-零上下文丢失

🔍 代码智能 -如果你重命名一个函数，谁调用什么，什么取决于什么，什么会中断。跨10多种语言的树型AST解析，而不是grep

🤖 子代理上下文压缩 -研究子代理将研究结果写入数据库，而不是将40000多个令牌转储到父上下文中。家长获得500代币摘要+按需 memory_search 检索

⚡ 每次会话可节省80-200K+代币 -语义搜索取代了文件读取，子代理的发现进入数据库而不是上下文。与子代理进行更长时间的会话可以节省更多

](#)     

______________________________________________________________________

看出差异

无认知层

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

使用CogniLayer

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

这不是一个小的改进。这就是猜测的代理和知道的代理之间的区别。

______________________________________________________________________

真实世界的例子

调试：“为什么结账失败？”

如果没有CogniLayer，Claude会读取15个文件来了解您的电子商务流程。有了它：

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"

克劳德已经知道架构，过去的错误， 和 如果碰到错误的东西，什么会坏。它使用的不是15次文件读取（约60K令牌），而是 3个目标查询（约800个令牌）.

代码智能：“如果我更改processOrder会发生什么？”

如果没有CogniLayer，Claude会寻找函数名，并希望一切顺利。有了它：

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"

在触摸一条线之前，克劳德知道 全爆炸半径 -哪些文件会中断，哪些需要测试，哪些调用者取决于当前的行为。重构后不再出现意外失败。

重构：“将UserService重命名为AccountService”

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

克劳德不仅仅是寻找和替换。它知道有一个 计划分裂 并且可以建议同时进行这两项更改，从而为您节省未来的重构会话。

崩溃后的新会话：“我在做什么？”

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

无需重新解释。克劳德从刚才的地方继续， 包括你还没有提到的阻断器.

子代理研究：“存在哪些MCP框架？”

如果没有CogniLayer，子代理将向父上下文返回一个40K的令牌转储：

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

使用CogniLayer的子代理内存协议：

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代币压缩到500。这些发现在DB的各个会话中都持续存在——不仅是为了这次对话，而且是永远的。

______________________________________________________________________

杀手级功能

______________________________________________________________________

运作原理

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

安装后无需费力。 无需学习命令，无需更改工作流程。CogniLayer通过钩子和MCP工具在后台运行。克劳德知道如何自动使用它。

______________________________________________________________________

快速开始

1.安装（30秒）

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

就是这样。下次启动Claude Code时，CogniLayer将处于活动状态。

2.可选：涡轮增压搜索

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

3.可选：添加Codex CLI支持

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

Codex在以下位置安装静态AGENTS指令和可重用的工作流文件：

~/.cognilayer/codex/onboard.md
~/.cognilayer/codex/harvest.md
~/.cognilayer/codex/checkpoint.md
~/.cognilayer/codex/multi_agent_safe.md

4.验证

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

故障排除

MCP服务器未连接？运行诊断工具：

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

需求

• Python 3.11+
• 克劳德代码和/或Codex CLI
• pip包： mcp, pyyaml, textual （自动安装）， fastembed, sqlite-vec （可选）， tree-sitter-language-pack （可选，用于代码智能）

______________________________________________________________________

Slash命令（仅限Claude代码）

安装后，在Claude Code中使用这些：

Codex CLI用户： Codex中没有Slash命令。相反，CogniLayer直接使用AGENTS.md指令+MCP工具。看 Codex CLI集成 在......下面

______________________________________________________________________

TUI仪表板

终端中的视觉记忆浏览器。8个选项卡，键盘导航，适用于Windows、Mac和Linux。

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

概述-统计数据概览

Overview

事实-可搜索、可过滤、按热量进行颜色编码

Facts

热图-查看哪些知识是热的、热的或冷的

Heatmap

集群-将相关事实组织成组

Clusters

时间表-完整的会议历史记录和结果

Timeline

*屏幕截图显示演示模式(cognilayer --demo)使用样本数据。*

______________________________________________________________________

升级

升级是安全和非破坏性的。你的记忆永远不会丢失：

git pull
python install.py

引擎盖下发生了什么：

• 代码文件被替换为最新版本
• config.yaml 是 从未覆盖 （您的设置是安全的）
• memory.db 是 自动备份 在任何迁移之前
• 架构迁移是 纯添加剂 （新建列/表，从不删除）
• CLAUDE.md在下次会话启动时自动阻止更新

回滚

如果出了什么问题：

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

______________________________________________________________________

配置

编辑 ~/.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

______________________________________________________________________

已知限制

• 并发CLIs：在同一项目上同时运行Claude Code和Codex CLI可能会导致会话跟踪冲突。每个项目一次使用一个CLI。
• Codex挂钩：Codex CLI仍然没有本机挂钩系统，因此基于挂钩的会话/文件更改日志记录在那里不可用。代码智能查询仍然可以根据需要进行增量自刷新。
• 代码智能：需要 tree-sitter-language-pack （约20MB）。没有它，内存、会话、安全和编排层仍然正常工作。
• 文本用户界面：需要 textual 包裹。只读，除了解决矛盾。

______________________________________________________________________

建筑（为好奇的人）

*下面的一切都是为那些想了解CogniLayer底层工作原理的开发人员准备的。*

系统概述

Claude Code / Codex CLI Session
    │
    ├── SessionStart hook (Claude Code) / session_init tool (Codex)
    │   └── Injects Project DNA + last session bridge into CLAUDE.md
    │
    ├── MCP Server (memory + code intelligence + safe Codex orchestration)
    │   ├── 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)
    │   ├── file_index       - Index project docs (README, configs, PRD) into file_chunks
    │   ├── 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)
    │   └── Safe Codex orchestration
    │       ├── agent_policy_read / agent_delegate_plan / agent_context_brief
    │       ├── agent_run_start / agent_run_finish / agent_run_heartbeat / agent_run_list
    │       ├── claim_scope / release_scope / list_claims
    │       ├── agent_event_write / register_handoff / agent_handoff_inbox / agent_handoff_resolve
    │       ├── agent_memory_stage / agent_memory_promote / agent_run_digest
    │       └── agent_writer_run_start / agent_review_run_start / agent_research_wave_*
    │
    ├── 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, code graph + orchestration tables)
├── config.yaml            # Configuration (never overwritten by installer)
├── active_session.json    # Current session state (runtime)
├── mcp-server/
│   ├── server.py          # MCP entry point (memory, code intelligence, orchestration)
│   ├── 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/             # 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 (8 tabs, keyboard nav)
│   ├── data.py                # Read-only SQLite data access layer
│   ├── styles.tcss            # CSS stylesheet
│   ├── screens/               # 8 tab screen modules
│   └── widgets/               # Heat cell, stats card widgets
└── logs/
    └── cognilayer.log

数据库架构（选定的核心表）

混合搜索

两个搜索引擎结合在一起以获得最大的召回率：

1. FTS5 -SQLite全文搜索以精确匹配关键字
2. 混合排名 -40%的FTS5+60%的向量相似性，热分数提高

矢量搜索是可选的-FTS5可以独立工作，没有任何额外的依赖关系。

热衰变

事实有一个“温度”，可以随着时间的推移模拟相关性：

衰变率因事实类型而异- error_fix 和 gotcha 事实的衰减速度（它们保持相关性的时间更长）比 task 事实。每次搜索命中都会提高一个事实的热度分数。

代码智能

由...驱动 树保姆 AST解析，支持10多种语言的语言包：

索引以可配置的时间预算运行（默认30秒）。部分结果可立即使用。未解析的引用将在下一次增量运行时重新解析。

当前实施中最近的准确性/新鲜度改进：

• 增量索引修剪已删除的文件，而不是留下死符号
• code_search, code_context，以及 code_impact 在应答之前触发安全的增量刷新，即使没有钩子，也能保持Codex CLI流可用
• 当项目包含重复的符号名称时，引用解析更稳定，特别是对于Python相对导入

子代理内存协议

当克劳德培育出研究子代理时，原始发现可能是40000多个代币。如果没有协议，所有这些都会进入父级的上下文窗口。子代理内存协议使用CogniLayer数据库作为侧通道：

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

关键设计决策：

• 粒度合成 -子代理将相关发现分组为有凝聚力的事实，而不是每个发现一个
• 任务特定标签 -每个子代理都有一个唯一的标签（例如。 tags="subagent,auth-review")用于过滤 memory_search(tags="auth-review")
• 事实中的关键词 -每个事实都以 Search: keyword1, keyword2 因此，即使在上下文压缩之后，检索仍然有效
• 写入最后一个模式 -全部 memory_write 调用是返回前的最后一步，保存子代理回合和令牌
• 前景优先 -子代理作为前台启动（可靠的MCP访问），用户可以Ctrl+B切换到后台
• 优雅的回退 -如果MCP工具不可用，结果将直接显示在返回文本中

该协议自动注入CLAUDE.md，不需要用户配置。

Codex CLI集成

Codex CLI没有挂钩系统，因此CogniLayer进行了调整：

两个CLI共享同一内存数据库。

Codex入职工作流程

AGENTS.md故意保持静态，并告诉Codex通过 session_init(). 对于首次入职培训，Codex应开放 ~/.cognilayer/codex/onboard.md 并遵循它：

1. session_init() -注册项目，加载DNA+桥梁
2. file_index() -索引文档文件 file_search 作品
3. code_index() -索引源代码 code_search/context/impact 工作
4. 通过以下方式读取关键文件并保存结果 memory_write() （人工智能进行智能分析）

为了获取会议结束时的知识，食品法典委员会应使用 ~/.cognilayer/codex/harvest.md. 对于上下文丢失前的轻量级切换，请使用 ~/.cognilayer/codex/checkpoint.md.

Codex也提供安全的多代理编排，但默认情况下是选择加入和关闭的：

codex:
  multi_agent:
    enabled: false
    mode: "off"  # off | research_only | safe

启用后 ~/.cognilayer/config.yaml，食品法典委员会应检查 agent_policy_read() 然后跟随 ~/.cognilayer/codex/multi_agent_safe.md 用于主管驱动的委托、分阶段记忆和编写索赔规则。

当前安全的多代理助手界面包括：

• 运行生命周期： agent_run_start, agent_run_finish, agent_run_heartbeat, agent_run_list
• 安全和所有权： claim_scope, release_scope, list_claims, agent_delegate_plan
• 上下文+证据包： agent_context_brief, agent_run_digest
• 明确协调： register_handoff, agent_handoff_inbox, agent_handoff_resolve
• 分阶段内存流： agent_memory_stage, agent_memory_promote
• 固执己见的工作流程： agent_writer_run_start, agent_review_run_start, agent_research_wave_start, agent_research_wave_collect, agent_research_wave_finalize

这符合什么 /onboard 和 /harvest 在Claude Code中执行，但通过Codex工作流文件而不是斜线命令。

项目身份证

部署安全系统，防止“哎呀，服务器错误”事件：

• 安全锁定 -锁定的字段需要显式更新+审核日志条目
• 哈希验证 -SHA-256检测安全关键字段的篡改
• 必需的现场检查 - verify_identity 如果缺少关键字段，则部署块
• 审计跟踪 -每个安全字段更改都会记录时间戳和原因

______________________________________________________________________

贡献

欢迎投稿！请先打开一个问题，讨论您想更改的内容。

许可证

弹性许可证2.0 -免费使用、修改和分发。您不能将其作为托管/托管服务提供。