mcpField
C
CogniRepo

CogniRepo

本地服务
github.com/ashlesh-t开发工具153 周前更新
代码仓库

关于 CogniRepo

CogniRepo 是面向 AI 编码 Agent 的离线代码上下文与持久记忆服务，尤其适用于较大的代码库。它结合符号索引、代码和记忆搜索、项目历史及架构上下文，工具无需 API 密钥即可使用。

主要功能

  1. 01索引符号及代码关系
  2. 02语义搜索代码和记忆
  3. 03检索受 token 预算约束的上下文包
  4. 04跟踪会话、错误和决策
  5. 05生成项目架构摘要
  6. 06无需 API 密钥即可离线运行

适用场景

  1. 01重构前查找符号及其调用方
  2. 02利用过往会话上下文继续工作
  3. 03在 token 预算内检索相关代码上下文
  4. 04回顾过往错误和架构决策

MCP 相关

CogniRepo 提供 36 种 MCP 工具，用于代码检索、图关系查询、记忆、会话历史、用户偏好和错误跟踪。Claude、Cursor 和 Gemini CLI 等 MCP 兼容客户端可使用已索引的项目上下文。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "ashlesh-t-cognirepo": {
      "command": "uvx",
      "args": [
        "cognirepo"
      ]
    }
  }
}
启动命令uvx cognirepo

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
pypicognirepo1.1.1

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

CogniRepo

mcp-name: io.github.ashlesh-t/cognirepo

为任意 AI 工具提供持久记忆和上下文。它不是聊天机器人，而是基础设施。

CI Security PyPI version GitHub Stars License: MIT Python 3.11+ Discord

alt text

lookup_symbol 能非常快速地返回文件:行号，而 grep 需要 2–8 秒。 在代码量 ≥ 15K 行的 Python 仓库中，与定向 grep+read 基准相比，CogniRepo 可减少 AI 编码 Agent 约 30–78% 的 token 用量（与朴素地读取所有匹配文件相比，最多可减少 96–99%）——已在 Flask、FastAPI、Celery 和 Ansible 上进行基准测试（5,900+ 个文件）。支持 Claude Code、Cursor 和 Gemini CLI。完全离线。索引或使用 36 个 MCP 工具中的任何一个都不需要 API 密钥。

功能介绍

每次 AI 对话都从零开始。Claude、Cursor、Gemini——它们都不会记得你昨天修复了什么、哪些文件与哪些功能相关，或上个冲刺周期做了哪些决定。CogniRepo 可以解决这个问题。

它位于代码库与任意 AI 工具之间，提供：

  • 语义记忆 — 基于 sentence-transformer 嵌入的 FAISS 向量存储。保存决策、文档和架构说明，并通过自然语言检索。
  • 事件日志 — 仅追加的事件日志。了解错误发生前发生了什么。
  • 知识图谱 — NetworkX DiGraph，关联函数、类、文件、导入、继承链、调用关系和概念。所有内容均可查询。
  • AST 反向索引 — 在任何受支持的语言中，以 O(1) 时间复杂度查找整个代码库中的符号。
  • 用户行为分析 — 跟踪你的提示词习惯，让 Claude 调整回复风格，无需你每次会话都重新说明偏好。
  • 错误跟踪 — 记录错误及预防提示，帮助 Claude 避免在不同会话中重复犯错。
  • 会话历史 — 持久保存对话内容，让任意会话都能从上次结束的位置继续。
  • 架构摘要 — 首次初始化时自动生成；完全基于本地 AST 索引构建（无需 API 密钥）。生成文件 → 目录 → 仓库的摘要树，并嵌入 FAISS 以支持语义搜索。
  • 多模型编排 — 对查询复杂度进行分类 → 构建上下文 → 将查询路由到合适的模型。复杂推理交给 Claude，快速查询交给 Gemini Flash。全程自动完成。

每个连接的 AI 工具都能获取相同的累积项目知识。记忆会跨会话、跨工具、跨时间持久保存。

何时使用 CogniRepo

在 ≥ 15K LOC 的代码库中效果最佳。 对于小型仓库（< 10K LOC），原生文件读取速度足够快，MCP 工具架构的开销（36 个工具约 3,700 个 token）超过了节省的 token。对于中型仓库，盈亏平衡点大约是调用工具 4 次。

CogniRepo 与 claude-context / 类似工具的对比：

功能CogniRepoclaude-context / 类似工具
纯代码检索✓（FAISS + 图 + AST）✓ 首次使用时通常更快
情景记忆（上一轮冲刺中发生了什么）✓ 持久化 BM25 + 向量✗
跨 Agent 交接（Claude → Gemini → Cursor）✓ 共享 last_context.json✗
用户行为画像（自适应深度 / 风格）✓ get_user_profile()✗
避免错误模式（从过往失败中学习）✓ record_error()✗
架构决策记录✓ record_decision()✗
多仓库组织图（微服务）✓ CHILD_OF / CALLS_API 边✗

结论： 如果你看重跨会话的组织记忆，请优先选择 CogniRepo。如果你只需要在小型代码库中进行一次性代码检索，则使用更简单的工具。

它为何有用 — 实测数据

在 6 个真实开源仓库（FastAPI、Flask、Celery、Ansible、Moby/Docker、Kubernetes）上进行基准测试，使用 30 个结构化提示词，分别针对 Claude、Gemini 和 Cursor/Codex 进行测试。

指标数值备注
Token 减少量 — Python 仓库50–84%FastAPI FA-2：12 000 → 2 500 · FA-4：2 000 → 450 · FL-4：8 000 → 1 250
Token 减少量 — 平均值（所有测试）~60%统计 FA/FL/CE/AN 中同时记录了两种基线的测试
Token 减少量 — 复杂动态代码库20–35%Celery CE-4/CE-5；深层异步 / 动态分发模式会降低收益
符号查找延迟< 1 ms大型仓库中 grep 需要 2–8 s
相对基线的准确率100% 的测试中持平或更高未观察到退化；FA-2 的准确率从中等提升至高
跨 Agent 上下文交接✅ 已验证CE-4：Claude 预热索引，Gemini CLI 使用索引 — 节省 35% token，准确率相同
动态分发覆盖率存在明确缺口CE-3（APScheduler beat 分发）两者均返回 NA；CogniRepo 不会捏造调用链
Go / 多语言覆盖率现已包含语法支持Moby MO-2 显示节省 67%；自 Go tree-sitter 语法合并后，MO-3-5 / K8-* 尚未重新运行（COGNIREPO-500，2026-09）

明确的局限： CogniRepo 在静态结构清晰的 Python 仓库中价值最大。 动态分发模式（Celery beat、插件注册表）、深层 Go 代码库，以及 Ansible 的 22 层变量优先级链，都会降低检索置信度。该工具会报告不确定性， 而不是臆造调用链。

已测量：查询延迟和 Token 减少量（4 个外部代码仓库）

使用 cognirepo index-repo + cognirepo benchmark --json，在 v2.4.0+（2026-09-17）上对 4 个真实代码仓库进行索引和测量。 仅使用 CPU，不使用 GPU。

代码仓库文件数查询延迟Token 减少量（朴素方式）Token 减少量（定向方式）context_relevance
flask920.002 ms97.3%29.5%80.5%
fastapi1,1780.003 ms97.6%63.5%97.1%
celery4440.003 ms99.7%77.7%100.0%
ansible4,1960.008 ms96.1%28.6%56.6%

测量日期：2026-09-17。所有代码仓库的查询延迟均低于 0.1 ms。“定向方式”是更贴近实际的基准（grep + 读取匹配度最高的 2 个文件，模拟 Agent 实际会采用的方式）；“朴素方式”会完整读取每个匹配文件，只代表上限，并非现实的对比方式。moby 和 kubernetes 已可索引（已确认支持 Go，COGNIREPO-500），但尚未列入此表——索引需要数小时，将另行安排。完整数据和方法（包括 precision@k、符号命中率和记忆召回率）：docs/METRICS.md。

运行 cognirepo benchmark，即可在自己的代码库上复现。请参阅 docs/METRICS.md。

工作原理

替代文本

快速开始

要求
  • Python 3.11+
  • API 密钥（可选——仅 cognirepo ask 需要）： ANTHROPIC_API_KEY、GEMINI_API_KEY、OPENAI_API_KEY 或 GROK_API_KEY。 索引、记忆、摘要和所有 MCP 工具均可完全离线运行。
安装
推荐 — pipx（全局安装，一条命令，适用于所有发行版）
pipx install cognirepo

就是这样。cognirepo setup 会处理其余事项——在向导中启用可选扩展（语言、安全、提供商）时，它会自动通过 pipx inject 安装。

为什么使用 pipx？ 它会自动为 cognirepo 创建隔离的 venv，因此 fastembed 和所有依赖项都能顺利安装。之后，cognirepo 命令在每个目录中均可全局使用——无需为每个代码仓库单独创建 venv。

Arch Linux / Debian 12+ / Ubuntu 24.04+： 请勿将 pip install 安装到系统 Python 中。 这些发行版强制执行 PEP 668，并会阻止系统范围的 pip 安装。请使用 pipx。

首先安装 pipx（如有需要）
# Arch Linux
sudo pacman -S python-pipx

# Debian / Ubuntu
sudo apt install pipx

# macOS
brew install pipx

# Any platform (fallback)
pip install pipx --user
在虚拟环境中安装（替代方案）
python -m venv .venv && source .venv/bin/activate
pip install cognirepo
# extras are installed by the setup wizard automatically
开发安装（从源代码安装）
pipx install -e '.[dev,security,languages]'
# or inside a venv: pip install -e '.[dev,security,languages]'

注意： 默认使用仅 CPU 的嵌入模型（fastembed/ONNX，无需 PyTorch/CUDA）。 使用 GPU：先运行 pipx inject cognirepo 'cognirepo[gpu]'，然后单独安装 torch。

运行
# One-command onboarding (init + index + auto-configure MCP for Claude/Cursor/VS Code):
cognirepo setup

# Or step by step:
cognirepo init --no-index     # scaffold .cognirepo/
cognirepo index-repo .        # index your codebase (required before MCP tools work)
cognirepo index-repo . --daemon  # index and run watcher in background

# Keep the index fresh after every commit (indexes just the changed files, in the background):
cognirepo install-hooks

# Check everything is working:
cognirepo status                        # shows symbol count, graph nodes, signal warmth
cognirepo doctor                        # full health check (exit 0 healthy / 1 warnings / 2 errors)
cognirepo doctor --resources            # where memory and disk go: processes, store sizes, leftovers

# Query through multi-model orchestrator:
cognirepo ask "why is auth slow?"

# Manage background watchers (one per repo, however many sessions run):
cognirepo watch --ensure-running        # start it if it is not running
cognirepo list                          # show all running watcher daemons
cognirepo list -n <PID> --view          # tail the log of a specific watcher
cognirepo list -n <PID> --stop          # stop a watcher

首次设置： 必须先完成 cognirepo init + cognirepo index-repo .， MCP 工具（context_pack、lookup_symbol、who_calls 等）才能返回数据。

连接你的 AI 工具

Claude Code / Claude Desktop（推荐 — 按项目配置）

在项目中运行 cognirepo init——它会询问你是否要配置 Claude，并自动写入 .claude/CLAUDE.md 和 .claude/settings.json，其中包含正确的项目锁定连接器。

每个项目都会有一个独立的连接器，名称为 cognirepo-<project>：

{
  "mcpServers": {
    "cognirepo-myproject": {
      "command": "cognirepo",
      "args": ["serve", "--project-dir", "/abs/path/to/myproject"],
      "env": {}
    }
  }
}

--project-dir 标志会将 MCP 服务锁定到该项目的 .cognirepo/ 目录。 当 Claude 同时打开多个项目时，每个连接器只会读取自己的记忆——绝不会混用不同项目或团队的数据。

Cursor / Copilot
cognirepo export-spec
cp adapters/cursor_mcp_config.json .cursor/mcp.json
# Restart Cursor — CogniRepo tools appear in the tool selector
Docker
cp .env.example .env          # add your API keys
docker compose up mcp         # MCP stdio server

MCP 工具 — 完整参考

Claude、Cursor 及任何兼容 MCP 的客户端均可使用全部 36 个工具。

核心检索
工具描述使用场景
context_pack(query, max_tokens=2000)在令牌预算内提供代码和记忆上下文每次会话——读取任何文件前的首次调用
lookup_symbol(name)O(1) 符号查找 → 文件 + 行号搜索函数前
who_calls(function_name)追踪调用方 + 动态分派回退影响分析、重构
search_token(word)跨名称、文档和注释的词级反向索引查找某个概念所在位置
retrieve_memory(query, top_k=5)对已存记忆进行语义相似度搜索回答前——提取过往上下文
search_docs(query)在所有 .md 文件中进行全文搜索查找文档
semantic_search_code(query, language=None)仅针对代码符号的向量搜索代码相关的语义查询
subgraph(entity, depth=2)局部知识图谱邻域了解符号关系
graph_stats()节点/边数量及图谱健康状况检查图谱是否有数据
episodic_search(query, limit=10)在事件历史中进行 BM25 关键词搜索查找过往决策或事件
dependency_graph(module, direction="both")导入/依赖关系模块耦合分析
explain_change(target, since="7d")文件/函数中的变更内容 + Git 交叉引用了解近期变更
architecture_overview(scope="root")预先计算的大模型架构摘要宏观问题
用户与会话智能
工具描述使用场景
get_user_profile()用户的交互风格：偏好深度、问题类型、词汇在会话开始时调用——校准 Claude 的响应风格
get_session_history(limit=10)跨会话的近期对话交流恢复之前会话的上下文
record_user_preference(key, value, context="")存储风格或格式偏好用户纠正理解或表达偏好时
错误追踪与预防
工具描述使用场景
get_error_patterns(min_count=1)重复出现的错误及预防提示提出修复方案前——检查此前是否失败过
record_error(error_type, message, file_path, query_context)记录错误以便日后避免Claude 或用户遇到任何错误后
会话开始
工具描述使用场景
get_agent_bootstrap()单次调用启动会话：简介 + 最近上下文 + 用户档案 + 错误（约 300 个令牌，而非约 900 个）优先作为首次调用——替代 4 次调用的流程
get_session_brief()架构 + 热门符号 + 索引健康状况需要分别获取细节时的首次调用
get_last_context()上一会话最近的 context_pack 快照从上一位 Agent 中断处继续
记忆与存储
工具描述使用场景
store_memory(text, source="")将记忆持久化到 FAISS 索引修复 bug、记录决策后
log_episode(event, metadata={})将事件追加到情节日志跟踪里程碑、事件、部署
record_decision(summary, rationale="")将架构决策记录到情节记忆中做出不明显的设计选择时
supersede_learning(old_memory_id, new_text)一次调用即可弃用并替换过时记忆过往决策或事实发生变化时
报告
工具返回内容使用场景
generate_insights(since="90d", repo_path=None)独立的 HTML 仓库历史报告（时间线、决策、挑战、活动、索引健康状况），仅基于实际存储的记录生成“这个仓库发生过什么”/仓库历史相关请求——见下文的 仓库洞察
有依据的反驳
工具返回内容使用时机
check_precedent(instruction){conflicts: [...], advisory: true} — 标记与已记录决策或 CLAUDE.md 不变量相矛盾的指令，并提供引用和具体替代方案。绝不会阻止操作；始终仅提供建议。对于普通请求，conflicts 为空——不会误报实施重要指令之前，先检查其是否符合已记录的先例
跨仓库（组织）
工具描述使用时机
org_search(query)搜索组织所有仓库中的记忆查询涉及多个仓库的上下文
org_wide_search(query)搜索组织中的所有项目最广泛的跨仓库搜索
org_dependencies(depth=2)双向的仓库间依赖关系图“此服务依赖什么？”
cross_repo_search(query, scope="project")搜索项目范围或组织范围的内容查找共享组件
cross_repo_traverse(symbol, direction="both")从某个仓库或符号出发遍历组织图追踪跨服务边界的错误
find_symbol_path(from_symbol, to_symbol)跨服务查找两个符号之间最短的调用图路径端到端追踪请求流
get_service_endpoints(repo_path)服务的 HTTP 端点注册表列出微服务的 API 范围
list_org_context()组织元数据及关联仓库了解仓库之间的关系
link_repos(src_repo, dst_repo, relationship)记录跨仓库依赖关系发现一个仓库导入另一个仓库时

知识图谱 — 索引内容

知识图谱比简单的调用图丰富得多。

节点类型
类型描述
FILE每个已索引的源文件
FUNCTION带有文档字符串的函数和方法定义
CLASS带有基类的类定义
CONCEPT从文档字符串和标识符中提取的语义概念
QUERY已记录的查询节点（用于检索评分）
SESSION对话会话节点
ERROR循环出现的错误模式节点
MEMORY跨 Agent 记忆节点（从 Claude/Gemini 同步）
边类型
类型方向描述
DEFINED_IN符号 → 文件符号位于此文件中
CALLS / CALLED_BY双向带有用途标签的函数调用关系
IMPORTS文件 → 文件Python 导入依赖关系
INHERITS类 → 父类继承层级
CO_OCCURS文件 ↔ 文件一同编辑的文件（行为上的协同编辑信号）
RELATES_TO概念 → 符号语义概念关联
QUERIED_WITH查询 → 符号用于评分的检索跟踪

IMPORTS 和 INHERITS 边会在 index-repo 期间根据 Python AST 自动构建。 使用 subgraph("MyClass", depth=2) 或 dependency_graph("mymodule") 查询这些边。

用户行为画像

CogniRepo 会追踪你在不同会话中的交互方式，并建立一个 Claude 用来调整回复的用户画像——无需你在每次会话中重复说明偏好。

追踪内容
  • 详细程度偏好 — 根据平均查询长度推断：concise / medium / detailed
  • 问题类型 — 以下类型的分布：why、what、how、fix、explain、where、refactor、add
  • 领域词汇 — 在你的查询中频繁出现的高频术语
  • 代码关注度 — 提及代码标识符（符号、函数）的查询所占百分比
  • 示例查询 — 最近 3 条查询，供 Claude 推断表达风格
查看你的用户画像
# MCP tool (Claude calls automatically at session start):
get_user_profile()

# CLI:
cognirepo user-prefs
用户画像输出示例
{
  "depth_preference": "detailed",
  "top_question_type": "how",
  "question_type_distribution": {"how": 12, "why": 8, "fix": 5},
  "top_terminology": ["auth", "token", "session", "middleware", "validate"],
  "code_focus_percent": 73,
  "framing_hints": "prefers detailed responses; often asks 'how' questions; domain vocabulary: auth, token, session",
  "total_queries_tracked": 47
}

Claude 会在会话开始时收到 framing_hints，并据此调整回复长度、代码密度和术语。用户画像会随着时间不断积累——使用得越多，就越准确。

错误跟踪与预防

CogniRepo 会记录会话期间发生的每个错误——无论是 Python 异常、构建步骤失败，还是工具调用出错。错误会连同以下信息一起存储：

  • 去重签名 — 防止同一错误导致计数虚增
  • 预防提示 — 针对性建议，帮助避免同类错误再次发生
  • 发生上下文 — 最近 5 次发生记录，包含文件路径和错误消息
  • 查询上下文 — 触发错误的查询或操作
记录错误
# MCP tool (Claude calls after errors):
record_error("TypeError", "expected str got int", "config/parser.py", "fix config loading")
查看错误模式
# MCP tool:
get_error_patterns()

返回：

[
  {
    "error_type": "TypeError",
    "count": 7,
    "files": ["config/parser.py", "api/handlers.py"],
    "last_seen": "2026-04-22T10:30:00Z",
    "prevention_hint": "Wrong type — validate inputs at function boundary.",
    "recent_context": "expected str got int in parse_config"
  }
]
内置预防提示
错误类别预防提示
NameError变量未定义 — 使用前检查导入和作用域
ImportError导入失败 — 确认已安装软件包，且模块路径正确
AttributeError对象缺少属性 — 检查类型、是否需要 None 防护，或拼写是否正确
TypeError类型错误 — 在函数边界验证输入
KeyError字典键缺失 — 使用带默认值的 .get()，或先检查键是否存在
IndexError列表索引越界 — 访问前使用 len() 检查并进行防护
OSError文件/IO 错误 — 始终使用 try/except OSError 防护文件操作
SyntaxError语法错误 — 提交前运行代码检查工具
Timeout超时 — 添加显式超时参数和重试逻辑
AssertionError断言失败 — 检查不变量；不要在生产环境中使用 assert

会话历史

每次 cognirepo ask 交互都会持久化到 .cognirepo/sessions/。 会话按 UUID 编入索引，可通过以下方式检索：

# List recent sessions:
cognirepo sessions

# MCP tool — Claude calls at session start to resume context:
get_session_history(limit=5)

每个条目都会返回：会话 ID、创建时间戳、消息数、所用模型，以及最近一次用户/助手交互，便于快速了解上下文。

架构摘要

首次建立索引后，cognirepo init 会自动提示运行 cognirepo summarize。 这会生成涵盖整个代码库的 3 级大模型摘要：

  • 第 1 级 — 仓库级摘要（项目的用途、关键模块、入口点）
  • 第 2 级 — 目录级摘要（每个软件包负责的内容）
  • 第 3 级 — 文件级摘要（每个文件包含的内容、关键函数/类）

摘要存储在 .cognirepo/index/summaries.json 中，并通过 architecture_overview MCP 工具提供——Claude 无需消耗令牌即可了解整体情况。

# Auto-prompted on first init. Run manually anytime:
cognirepo summarize

# Fully local — no API key required. Reads from ast_index.json, runs in < 1 second.
# File summaries are also embedded into FAISS for semantic architecture queries.

仓库洞察

CogniRepo 能告诉你关于仓库的哪些信息：generate_insights()（或 cognirepo insights） 会将 CogniRepo 记录的项目所有信息——情景事件、架构决策、未解决的挑战、分支/提交活动、索引健康状况——整合为一份独立的 HTML 报告。内容仅取自实际存储的记录；不会捏造任何信息。下方截图来自本仓库实际生成的报告（cognirepo insights --since 365d），并非样图：

CogniRepo 洞察报告，浅色模式 CogniRepo 洞察报告，深色模式 

cognirepo insights --since 90d   # writes .claude/insights/<repoName>-insights.html

多模型编排

cognirepo ask 会为每个查询自动选择合适的模型：

层级分数默认模型使用场景
QUICK≤2本地解析器单令牌 / 简单查询 — 无需 API，速度最快
STANDARD≤4Haiku快速查找、事实查询、单个符号
COMPLEX≤9Sonnet中等程度的推理
EXPERT>9Opus跨文件、架构类、含糊不清的查询 — 完整上下文，最强模型
cognirepo ask "where is verify_token defined?"       # → QUICK, answered locally
cognirepo ask "why is auth slow?"                    # → EXPERT, Claude with full context
cognirepo ask --verbose "explain the circuit breaker"  # show tier/score/signals

提供商回退链：Grok → Gemini → Anthropic → OpenAI。 所有错误都会记录到 .cognirepo/errors/<date>.log 中——不会向用户显示原始堆栈跟踪。

语言支持

语言扩展名安装
Python.py内置
Swift.swiftcognirepo[languages]
Kotlin.kt .ktscognirepo[languages]
JavaScript / TypeScript.js .ts .jsx .tsxcognirepo[languages]
Java.javacognirepo[languages]
C#.cscognirepo[languages]
Go.gocognirepo[languages]
Rust.rscognirepo[languages]
Ruby.rbcognirepo[languages]
C / C++.c .cpp .hcognirepo[languages]
PHP.phpcognirepo[languages]

完整详情和路线图：docs/LANGUAGES.md

存储布局

.cognirepo/
  config.json              ← project settings (project_id, models, retrieval weights, indexing, behaviour bounds)
  cognirepo.lock           ← cross-process store lock (OS advisory lock; never delete by hand)
  graph/
    graph.pkl              ← NetworkX DiGraph (optionally Fernet-encrypted)
    graph.journal          ← append-only journal, present only while `index-repo` runs or after a failed save
    behaviour.json         ← per-symbol hit counts, user profile, error patterns (bounded, see CONFIGURATION.md)
  index/
    ast_index.json         ← reverse symbol index + file records
    ast.index              ← FAISS IndexIDMap2 for code symbols
    ast_metadata.json      ← parallel metadata for ast.index rows
    manifest.json          ← git SHA, platform info and checksums for integrity checks (`verify-index`)
    summaries.json         ← LLM architectural summaries (Level 1–3)
    last_indexed.json, endpoints.json, http_calls.json, …   ← indexing bookkeeping
  vector_db/
    chroma/                ← default semantic-memory store (ChromaDB); `semantic.index` when `vector_backend: "faiss"`
  memory/
    episodic.json          ← append-only event journal
    semantic_metadata.json ← metadata for the local FAISS semantic store (`vector_backend: "faiss"`) and project memory
  learnings/
    learnings.json         ← structured learnings: decisions, bugs, prod issues
  watchers/                ← watcher registry (<pid>.json), heartbeat, lease (watcher.writer), logs
  sessions/                ← conversation session files
  errors/                  ← daily error logs (full tracebacks, never shown to users)
  hook.log, hook.last      ← output and last result of the git post-commit hook (`install-hooks`)

加载器隔离出来的文件会保留，绝不会在没有提示的情况下删除：graph.pkl.corrupt-<ts>（其中很可能包含完整的图——参见 cognirepo graph restore）、vector_db/chroma.corrupt-<ts>/、*.stale。cognirepo doctor --resources 会列出这些文件及其大小。预期大小和调优选项： docs/RESOURCES.md。

默认情况下，.cognirepo/ 下的所有内容都会被 .gitignore 忽略——绝不会提交。 Fernet 加密需通过 config.json 中的 storage.encrypt: true 选择启用；它涵盖图、行为模型、组织图、情景日志和本地 FAISS 存储，但不涵盖 AST 索引或默认的 Chroma 存储——具体涵盖和不涵盖的内容请参见 SECURITY.md。

CLI 参考

# Setup
cognirepo init                  # scaffold + configure; auto-indexes + auto-summarizes
cognirepo setup-env             # interactive API key wizard
cognirepo test-connection       # test API key connectivity
cognirepo migrate-config        # migrate deprecated config keys

# Indexing
cognirepo index-repo [path]     # AST-index a codebase
cognirepo summarize             # generate LLM architectural summaries (auto-prompted on init)
cognirepo seed --from-git       # seed behaviour weights from git history
cognirepo verify-index          # verify AST index integrity
cognirepo coverage              # per-directory symbol counts

# Querying
cognirepo ask <query>           # route through multi-model orchestrator
cognirepo retrieve-memory <q>   # similarity search
cognirepo search-docs <q>       # full-text search in .md files
cognirepo log-episode <event>   # append episodic event
cognirepo history               # print recent episodic events
cognirepo sessions              # list recent conversation sessions

# Memory management
cognirepo store-memory <text>   # save a semantic memory
cognirepo user-prefs            # view/set global user preferences
cognirepo prune [--dry-run]     # prune low-score memories

# Health & monitoring
cognirepo prime                 # generate session bootstrap brief
cognirepo status                # live retrieval signal weights + index health
cognirepo doctor [--fix]        # full health check; --fix auto-repairs common issues
cognirepo doctor --resources    # processes, store sizes and left-over files (read-only)
cognirepo benchmark             # run quantitative value benchmarks
cognirepo install-hooks         # git post-commit hook: reindex changed files after each commit
cognirepo graph restore         # list quarantined graphs and restore the best intact one (dry-run; --apply)

# Organization
cognirepo org create <name>     # create local organization
cognirepo org link <org> [path] # link repo to organization
cognirepo org list              # list organizations

# Daemon management
cognirepo list                  # list MCP servers, running daemons (`-n PID --stop` to stop one)
cognirepo watch --ensure-running  # start the background file-watcher (one per repo); `--status` to inspect

所有命令、标志和退出代码：docs/CLI_REFERENCE.md。

未来计划

优先事项根据 v0.3.0 基准测试结果和社区反馈确定。目前已到 v2.5.0——下方部分事项现已完成；如有完成情况，会在对应条目中注明。

近期
  • Go 调用图索引 — 已完成（COGNIREPO-203）： Go 接收者限定的方法调用 （recv.Method()）现在可以通过 who_calls/CALLS 边解析——tree-sitter 的 Go selector_expression 将其方法字段命名为 field，而不是 property（此前提取器假设采用的 JS 惯例），因此方法调用会被静默丢弃；已在 _ts_collect_calls（intelligence/indexer/ast_indexer.py）中修复。同一 函数中的第二个 bug——调用收集递归深度上限为 12，对于 Go 方法中由复合字面量调用参数外层的 if 语句来说太浅——也已调高（至 60）。Go IMPORTS 边现已实现，可处理通过 go.mod 解析的本地包导入 （_extract_imports_go/_resolve_go_import_to_file）。在 cognirepo_test_repo/advanced/moby 中经过实时验证：两项修复后，人工核验的调用方中有 4/4 得到解析（100%，高于 90% 的目标）。
  • cognirepo ask — 已完成： 多模型编排器（QUICK/STANDARD/COMPLEX/EXPERT 级别）已实现，并接入为正式 CLI 命令（_cmd_ask_local、interface/cli/main.py）。流式 REPL 模式（参见长期计划）尚未构建。
  • 保存时增量重新索引 — 已完成： 文件监视守护进程（cognirepo watch）会对写入操作进行防抖（config.json → indexing.debounce_ms，默认 500ms），并批量保存索引器/图；tests/test_watcher_debounce.py 覆盖了这一功能，包括关机时刷新。
  • 放宽 CLAUDE.md 强制调用要求 — 基准测试反馈（Moby 测试）指出，在内存压力下，强制每次读取文件前调用 context_pack 会增加延迟。跳过文件少于 50 行时工具优先门槛的 --fast 模式尚未实现。
中期
  • 平台（计划于 3.0 推出） — 单个面向每位用户的守护进程、本地控制 API（/api/v1）及 cognirepo ui 命令，以及用于替代常驻内存图谱的 SQLite（WAL）图存储。使用该 API 的 Engram 控制台位于独立仓库中。设计上仅限本地使用：没有托管中继，也不支持远程访问。相关工作已纳入“Platform”史诗。
  • Kubernetes / 2M-LOC 规模验证 — K8-1 至 K8-5 测试套件尚未完成。目标：使用 CogniRepo 时，完整的调度决策跟踪少于 8 000 个 token；不使用时则超过 50 000 个 token。
  • 插件注册模式检测 — 已完成（COGNIREPO-203）： 静态、仅注解的启发式扫描会为可通过动态分派访问的符号添加标记，包括 celery 风格的 @task/@shared_task 装饰器、register(...) 风格的插件注册调用、Python __init_subclass__ 钩子，以及打包入口点（pyproject.toml [project.entry-points.*] / setup.cfg [options.entry_points]），并添加 dispatch:"dynamic"，以及指向 dynamic_dispatch CONCEPT 节点的 RELATES_TO 边（intelligence/indexer/ast_indexer.py 中的 _detect_dynamic_dispatch、_apply_entry_points_dispatch）。设计上仅添加注解，绝不伪造 CALLS 边。已通过 cognirepo_test_repo/medium/celery 中真实的 @shared_task 函数进行实时验证。
  • 基于符号名称的 BM25 — 部分完成： 在无法使用嵌入时，core/_bm25.py 会被 intelligence/retrieval/hybrid.py 用作熔断回退排序器（也用于情景搜索），但在常规（嵌入可用）检索路径中，它尚未成为提升符号名称部分匹配召回率的主要排序信号（例如让 HttpClient 匹配 http_client）。
  • 跨会话记忆预热 — Ansible 基准测试指出，在新会话中，情景记忆检索的价值较低。cognirepo prime 已存在，但 init 不会自动运行；将使其默认选择加入。
长期
  • cognirepo ask 流式 REPL — 完整的交互式会话，支持分层路由、会话持久化和子 Agent 委派。
  • 知识图谱中的相似边 — 已完成（COGNIREPO-202）： 索引后对已嵌入的 FUNCTION/CLASS 符号向量执行 FAISS k-NN 扫描，在近似重复的符号之间添加 SIMILAR_TO 边（余弦相似度 ≥ 0.80，每个节点最多 5 条，仅跨文件），并添加双向边。通过 config.json → indexing.similarity_edges 控制（候选符号少于 20k 时默认开启）。在 intelligence/retrieval/hybrid.py::_graph_score 中以加权（折扣）方式计入。
  • VS Code / JetBrains 扩展 — 无需支持 MCP 的宿主，即可在编辑器侧边栏中直接使用 lookup_symbol、context_pack 和 who_calls。

文档

文档说明
docs/ARCHITECTURE.md系统设计、组件职责、数据流
docs/architecture/SPECIFICATION.md技术规范、复杂度信号、存储布局
docs/USAGE.mdCLI、MCP 和 Docker 完整参考
docs/CLI_REFERENCE.md所有命令和标志（测试会对照实际 CLI 进行检查）
docs/CONFIGURATION.mdconfig.json 字段、环境变量、存储布局
docs/RESOURCES.md内存和磁盘占用、doctor --resources、调优选项
docs/TROUBLESHOOTING.md常见问题：索引过期、存储繁忙、钩子、残留进程
CHANGELOG.md各版本的变更及升级说明
docs/METRICS.md量化基准：token 减少量、查找速度提升、召回率
CONTRIBUTING.md如何添加适配器、工具和语言支持
SECURITY.md漏洞报告、数据处理、信任模型
docs/LANGUAGES.md语言支持详情和路线图

社区

有问题、反馈，或者只是想看看其他人在构建什么？加入 CogniRepo Discord。

想要贡献？请参阅 CONTRIBUTING.md——标记为 good first issue 的问题范围明确，适合作为首次 PR。

许可证

CogniRepo 采用 MIT License 授权。

  • 可免费使用、研究、修改和分发
  • 可用于专有产品和商业服务，不受限制
  • 无需将你的应用开源

详情请参阅 LICENSE。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。