用途 CogniRepo 是面向 AI 编程代理的本地认知基础设施，用来为任何 AI 工具提供持久记忆与上下文，减少 token 使用。它不属于聊天机器人，而是位于代码库与 AI 工具之间的中间层。每段 AI 对话默认从零开始，Claude、Cursor、Gemini 都不会记住昨天修复了什么、哪些文件与哪些功能相关、上一冲刺做了哪些决策。CogniRepo 用来解决这一问题。
主要能力
- 语义记忆：FAISS 向量存储结合 sentence-transformer 嵌入，可存储决策、文档、架构笔记，并用自然语言检索。
- 事件日志：追加式事件日志，可了解某次错误之前发生了什么。
- 知识图谱：NetworkX DiGraph，连接函数、类、文件、导入、继承链、调用关系和概念，均可查询。
- AST 反向索引：支持的语言中，对整个代码库进行 O(1) 符号查找。
- 用户行为画像：跟踪用户的提示方式，让 Claude 无需每会话重新解释偏好即可调整响应风格。
- 错误跟踪：记录错误及预防提示，帮助 Claude 跨会话避免重复同一错误。
- 会话历史：持久化对话交换，使任意会话可从上一次结束处继续。
- 架构摘要：首次初始化时自动生成，完全基于本地 AST 索引（无需 API 密钥），生成文件→目录→仓库的三级摘要树，并嵌入 FAISS 用于语义搜索。
- 多模型编排：分类查询复杂度→构建上下文→路由到合适模型，例如 Claude 用于深度推理、Gemini Flash 用于快速查找，全部自动完成。 所有连接该基础设施的 AI 工具都能获得相同的累积项目知识，记忆跨会话、跨工具、跨时间持久存在。
使用方式 建议使用 pipx 安装以创建隔离虚拟环境。首次使用需先运行 cognirepo init 与 cognirepo index-repo .，完成索引后 MCP 工具（context_pack、lookup_symbol、who_calls 等）才会返回数据。运行 cognirepo init 时，若选择配置 Claude，会自动写入 .claude/CLAUDE.md 与 .claude/settings.json。--project-dir 标志会把 MCP 服务器锁定到该项目的 .cognirepo/ 目录，多项目同时打开时各连接器只读取各自记忆，不会跨项目或团队混合数据。MCP 工具共 36 个，可供 Claude、Cursor 及任何 MCP 兼容客户端使用。默认使用 CPU 嵌入（fastembed/ONNX，无需 PyTorch/CUDA）；GPU 需额外操作。索引、记忆、摘要和全部 MCP 工具可完全离线；仅 cognirepo ask 需要可选的 API 密钥（ANTHROPIC_API_KEY、GEMINI_API_KEY、OPENAI_API_KEY 或 GROK_API_KEY）。
适用场景 最适合代码库规模 ≥ 15K LOC 的场景。官方基准测试覆盖 Flask、FastAPI、Celery、Ansible 等仓库（5,900+ 文件），显示相比定向 grep+read 基线可减少约 30%–78% 的 token 用量；在中等规模仓库上盈亏平衡约为 4 次工具调用。在小型仓库（<10K LOC）上，原生文件读取足够快，而 36 个 MCP 工具的模式开销（约 3,700 token）可能导致得不偿失。它适合重视跨会话机构记忆的场景，而简单工具更适合小型代码库上的一次性代码检索。使用 cognirepo benchmark 可在自己的代码库上复现。
限制 在具有清晰静态结构的 Python 仓库上价值最大。动态分发模式（如 Celery beat、插件注册表）、深度 Go 代码库以及 Ansible 的 22 级变量优先级链会降低检索置信度；工具会报告不确定性，而不是编造调用链。部分平台能力（如单用户守护进程、本地控制 API /api/v1、cognirepo ui、SQLite（WAL）图存储）标记为计划用于 3.0。Kubernetes / 2M-LOC 规模验证尚未完成。cognirepo ask 的流式 REPL 模式尚未构建。CLAUDE.md 强制调用放宽（--fast 模式）尚未实现。BM25 在符号名部分匹配召回上尚未成为正常（嵌入可用）检索路径中的主排序信号。跨会话记忆预热 cognirepo prime 已存在，但不会在 init 时自动运行。
