{
"canonical_name": "RNBBarrett/thought-mcp",
"compilation_id": "pack_919bfae2946d4a6abec1b16e588d8a54",
"created_at": "2026-05-16T09:23:05.124796+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install thought-mcp` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install thought-mcp",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_bec078e506444e22b79f089a57d1df63"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_b46554c512d7b03b1abcdaf45a206ccb",
"canonical_name": "RNBBarrett/thought-mcp",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/RNBBarrett/thought-mcp",
"slug": "thought-mcp",
"source_packet_id": "phit_221d051f07004b45a19002f6c360c9ac",
"source_validation_id": "dval_1115cfafb5dd48f8842d7e45e3fc9b07"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 0,
"github_stars": 0,
"one_liner_en": "Local MCP memory server for LLMs. Bi-temporal graph + vector + Cypher queries + auto-write/auto-recall hooks for Claude Code. Works with Ollama, LM Studio, Anthropic, OpenAI.",
"one_liner_zh": "Local MCP memory server for LLMs. Bi-temporal graph + vector + Cypher queries + auto-write/auto-recall hooks for Claude Code. Works with Ollama, LM Studio, Anthropic, OpenAI.",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host, claude, claude_code 等宿主 AI 的用户",
"title_en": "thought-mcp",
"title_zh": "thought-mcp 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Natural-language Web Actions",
"label_zh": "自然语言网页操作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-natural-language-web-actions",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Structured Data Extraction",
"label_zh": "结构化数据提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-structured-data-extraction",
"type": "selection_signal"
}
]
},
"packet_id": "phit_221d051f07004b45a19002f6c360c9ac",
"page_model": {
"artifacts": {
"artifact_slug": "thought-mcp",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install thought-mcp",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/RNBBarrett/thought-mcp#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"自然语言网页操作",
"节点式流程编排",
"结构化数据提取"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Local MCP memory server for LLMs. Bi-temporal graph + vector + Cypher queries + auto-write/auto-recall hooks for Claude Code. Works with Ollama, LM Studio, Anthropic, OpenAI."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude, claude_code, chatgpt",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | host_targets=mcp_host, claude, claude_code, chatgpt"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1,
"forks": 0,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 0
},
"source_url": "https://github.com/RNBBarrett/thought-mcp",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Local MCP memory server for LLMs. Bi-temporal graph + vector + Cypher queries + auto-write/auto-recall hooks for Claude Code. Works with Ollama, LM Studio, Anthropic, OpenAI.",
"title": "thought-mcp 能力包",
"trial_prompt": "# thought-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 thought-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code / chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Local MCP memory server for LLMs. Bi-temporal graph + vector + Cypher queries + auto-write/auto-recall hooks for Claude Code. Works with Ollama, LM Studio, Anthropic, OpenAI. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与快速开始。围绕“安装与快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-code-ingestion：代码摄取与解析。围绕“代码摄取与解析”模拟一次用户任务，不展示安装或运行结果。\n5. page-entity-management：实体与关系管理。围绕“实体与关系管理”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-code-ingestion\n输入：用户提供的“代码摄取与解析”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-entity-management\n输入：用户提供的“实体与关系管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-code-ingestion：Step 4 必须围绕“代码摄取与解析”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-entity-management：Step 5 必须围绕“实体与关系管理”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/RNBBarrett/thought-mcp\n- https://github.com/RNBBarrett/thought-mcp#readme\n- README.md\n- src/thought/__init__.py\n- pyproject.toml\n- src/thought/cli.py\n- Dockerfile\n- src/thought/server.py\n- src/thought/storage/base.py\n- src/thought/ingest/pipeline.py\n- src/thought/layers/__init__.py\n- src/thought/router/dispatcher.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 thought-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_release: v0.2.2 — MCP stdio transport fix（https://github.com/RNBBarrett/thought-mcp/releases/tag/v0.2.2）；github/github_release: v0.2.1 — thought upgrade + mcp-extras fix（https://github.com/RNBBarrett/thought-mcp/releases/tag/v0.2.1）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_release",
"source": "github",
"title": "v0.2.2 — MCP stdio transport fix",
"url": "https://github.com/RNBBarrett/thought-mcp/releases/tag/v0.2.2"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.2.1 — thought upgrade + mcp-extras fix",
"url": "https://github.com/RNBBarrett/thought-mcp/releases/tag/v0.2.1"
}
],
"status": "已收录 2 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "Local MCP memory server for LLMs. Bi-temporal graph + vector + Cypher queries + auto-write/auto-recall hooks for Claude Code. Works with Ollama, LM Studio, Anthropic, OpenAI.",
"effort": "安装已验证",
"forks": 0,
"icon": "link",
"name": "thought-mcp 能力包",
"risk": "需复核",
"slug": "thought-mcp",
"stars": 0,
"tags": [
"MCP 工具",
"知识库问答",
"自然语言网页操作",
"节点式流程编排",
"结构化数据提取"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/RNBBarrett/thought-mcp 项目说明书\n\n生成时间：2026-05-16 09:07:15 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [安装与快速开始](#page-installation)\n- [系统架构](#page-architecture)\n- [配置管理](#page-configuration)\n- [代码摄取与解析](#page-code-ingestion)\n- [实体与关系管理](#page-entity-management)\n- [记忆模型与检索](#page-memory-model)\n- [查询系统](#page-query-system)\n- [图形层与图遍历](#page-graph-layer)\n- [Agent集成与适配器](#page-agent-integration)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [安装与快速开始](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CHANGELOG.md](https://github.com/RNBBarrett/thought-mcp/blob/main/CHANGELOG.md)\n- [src/thought/demo.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/demo.py)\n- [src/thought/cli.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/cli.py)\n- [src/thought/models.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/models.py)\n- [src/thought/layers/code.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/code.py)\n- [src/thought/ingest/code/types.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/types.py)\n- [src/thought/ingest/code/pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/pipeline.py)\n- [src/thought/ingest/code/python_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/python_extractor.py)\n- [src/thought/ingest/code/git_pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/git_pipeline.py)\n- [CONTRIBUTING.md](https://github.com/RNBBarrett/thought-mcp/blob/main/CONTRIBUTING.md)\n \n\n# 项目概述\n\n## 简介\n\n**thought-mcp** 是一个本地AI记忆工具（Local-AI Memory Tool），旨在为开发者提供完整的知识库管理、代码理解、本地大语言模型集成和自然语言查询能力。该项目通过 SQLite 作为底层存储，结合向量嵌入技术和 Cypher 图查询语言，实现了一个功能完备的个人知识管理系统。\n\n资料来源：[CHANGELOG.md:1-15]()\n\n## 核心定位\n\nthought-mcp 扮演着**开发者第二大脑**的角色，它将代码库、知识文档、工作会话等信息统一纳入管理范围。与传统的笔记工具不同，thought-mcp 具有以下独特优势：\n\n- **代码感知**：原生支持多种编程语言的 AST 解析，能够理解代码结构、依赖关系和调用图\n- **时间旅行**：采用双时态模型（Bi-temporal Model），支持 `valid_time` 和 `learned_time` 两种时间维度\n- **本地优先**：完全运行在本地环境，支持 Ollama、LM Studio 等本地 LLM 和 embedding 服务\n- **图数据库能力**：通过 Cypher 查询语言实现复杂的知识图谱查询\n\n资料来源：[src/thought/layers/code.py:1-20]()\n\n## 系统架构\n\nthought-mcp 采用分层架构设计，各层职责明确：\n\n```mermaid\ngraph TD\n subgraph \"表示层\"\n CLI[CLI 命令行]\n MCP[MCP 服务器]\n TUI[图形界面 TUI]\n end\n \n subgraph \"应用层\"\n Router[路由层]\n Ask[自然语言查询]\n Demo[演示模块]\n end\n \n subgraph \"领域层\"\n CodeLayer[代码层]\n GraphLayer[图查询层]\n MemoryLayer[记忆层]\n end\n \n subgraph \"摄入层\"\n Ingest[代码摄入]\n GitIngest[Git历史摄入]\n ProseIngest[文本摄入]\n end\n \n subgraph \"存储层\"\n SQLite[(SQLite)]\n Backend[存储后端]\n WAL[WAL检查点]\n end\n \n CLI --> Router\n MCP --> Router\n Router --> Ask\n Ask --> GraphLayer\n CodeLayer --> GraphLayer\n Ingest --> Backend\n GitIngest --> Backend\n Backend --> SQLite\n```\n\n### 各层职责\n\n| 层次 | 组件 | 职责 | 源码位置 |\n|------|------|------|----------|\n| 表示层 | `cli.py` | 命令行入口，处理用户输入 | `src/thought/cli.py` |\n| 表示层 | MCP 服务器 | 提供 Model Context Protocol 接口 | `src/thought/server/` |\n| 应用层 | `ask` 命令 | 自然语言转 Cypher 查询 | `src/thought/cli.py` |\n| 领域层 | `CodeLayer` | 代码特定查询封装 | `src/thought/layers/code.py` |\n| 领域层 | `GraphLayer` | 图查询操作核心 | `src/thought/layers/graph.py` |\n| 存储层 | `SQLiteBackend` | 数据库操作封装 | `src/thought/storage/sqlite/backend.py` |\n\n资料来源：[src/thought/cli.py:1-35]()\n资料来源：[src/thought/layers/code.py:1-30]()\n\n## 核心功能模块\n\n### 1. CLI 命令行工具\n\n`thought` CLI 是用户与系统交互的主要入口，提供以下命令：\n\n| 命令 | 功能 | 源码位置 |\n|------|------|----------|\n| `thought init` | 初始化数据库和配置 | `src/thought/cli.py` |\n| `thought serve` | 启动 MCP 服务器 | `src/thought/cli.py` |\n| `thought ingest` | 摄入实体信息 | `src/thought/cli.py` |\n| `thought recall` | 召回相关记忆 | `src/thought/cli.py` |\n| `thought ask` | 自然语言查询 | `src/thought/cli.py` |\n| `thought callers` | 查找调用者（PageRank排序） | `CHANGELOG.md` |\n| `thought impact` | 计算变更影响范围 | `CHANGELOG.md` |\n| `thought diff` | 比较两个提交间的差异 | `CHANGELOG.md` |\n| `thought schema` | 查看实体类型统计 | `src/thought/cli.py` |\n| `thought db flush/backup/load/inspect` | 数据库生命周期管理 | `CHANGELOG.md` |\n\n资料来源：[src/thought/cli.py:15-30]()\n\n### 2. 代码理解引擎\n\nthought-mcp 的代码理解能力基于多语言 AST 解析器，支持以下编程语言：\n\n| 语言 | 提取器 | 源码位置 |\n|------|--------|----------|\n| Python | `python_extractor.py` | `src/thought/ingest/code/python_extractor.py` |\n| TypeScript | `typescript_extractor.py` | `src/thought/ingest/code/typescript_extractor.py` |\n| Rust | `rust_extractor.py` | `src/thought/ingest/code/rust_extractor.py` |\n| PHP | `php_extractor.py` | `src/thought/ingest/code/php_extractor.py` |\n\n每个语言提取器都能识别以下代码实体类型：\n\n```mermaid\ngraph TD\n subgraph \"代码实体类型\"\n Module[模块/命名空间]\n Class[类定义]\n Function[函数]\n Method[方法]\n File[文件]\n Import[导入关系]\n end\n \n subgraph \"代码边类型\"\n DEFINES[DEFINES - 定义关系]\n IMPORTS[IMPORTS - 导入关系]\n INHERITS_FROM[INHERITS_FROM - 继承关系]\n OVERRIDES[OVERRIDES - 重写关系]\n CALLS[CALLS - 调用关系]\n end\n \n Class --> DEFINES\n Class --> INHERITS_FROM\n Module --> IMPORTS\n```\n\n资料来源：[src/thought/ingest/code/types.py:1-50]()\n资料来源：[src/thought/ingest/code/python_extractor.py:1-50]()\n\n### 3. 数据模型\n\nthought-mcp 使用双时态数据模型记录实体和边的生命周期：\n\n#### Entity 实体模型\n\n```python\nclass Entity(BaseModel):\n id: str\n type: str\n name: str\n canonical_name: str\n owner_id: str | None = None\n scope: ScopeName # shared | private\n tier: Tier # hot | warm | cold\n importance: float # 0.0 ~ 1.0\n valid_from: datetime # 事实生效时间\n valid_until: datetime | None # 事实失效时间\n learned_at: datetime # 系统学习时间\n unlearned_at: datetime | None\n created_at: datetime\n last_accessed_at: datetime\n access_count: int = 0\n attrs: dict[str, object]\n```\n\n资料来源：[src/thought/models.py:1-80]()\n\n#### 双时态模型说明\n\n| 时间维度 | 字段 | 含义 | 使用场景 |\n|----------|------|------|----------|\n| 有效时间 | `valid_from` / `valid_until` | 事实本身在现实世界生效的时间段 | 查询\"某代码在某个时间点是否存在\" |\n| 学习时间 | `learned_at` / `unlearned_at` | 系统何时获知该事实 | 查询\"系统在某个时间点知道什么\" |\n\n这种设计允许用户进行真正的\"时间旅行\"查询：\n\n- `as_of_kind='valid'` — \"在 X 日期，什么是真实现实？\"\n- `as_of_kind='learned'` — \"在 X 日期，系统知道什么？\"\n\n资料来源：[src/thought/cli.py:1-30]()\n\n### 4. Git 历史感知摄入\n\n`thought ingest-git` 命令支持两种摄入模式：\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| `snapshot` (默认) | 仅摄入 HEAD 提交 | 快速初始化 |\n| `full` | 遍历每个提交，记录每个实体的提交SHA | 完整历史追溯 |\n\n```mermaid\ngraph LR\n A[Git仓库] --> B[GitWalker]\n B --> C[逐提交遍历]\n C --> D{摄入模式}\n D -->|snapshot| E[仅HEAD]\n D -->|full| F[所有提交]\n E --> G[(SQLite KB)]\n F --> G\n```\n\n`GitWalker` 使用纯 Python subprocess 实现，不依赖 `pygit2` 等本地库。\n\n资料来源：[src/thought/ingest/code/git_pipeline.py:1-50]()\n\n### 5. 本地 LLM 集成\n\nthought-mcp 支持多种本地 LLM 提供商：\n\n| 提供商 | Embedder 类 | 特点 |\n|--------|-------------|------|\n| Ollama | `OllamaEmbedder` | 使用原生 `/api/embed` 接口，支持批量操作 |\n| LM Studio | `LMStudioEmbedder` | OpenAI 兼容接口 |\n| 任意 OpenAI 兼容服务器 | `OpenAICompatEmbedder` | 通用兼容层 |\n\n配置通过 `thought.toml` 文件管理：\n\n```toml\n[llm]\nprovider = \"ollama\" # anthropic | ollama | lmstudio | openai-compat | openai\n\n[embedding]\nmodel = \"nomic-embed-text\" # 或其他 embedding 模型\n```\n\n资料来源：[CHANGELOG.md:1-50]()\n\n### 6. Cypher 图查询\n\nv0.4.0 引入的 Cypher 查询子集允许直接查询知识图谱：\n\n```cypher\n// 查找某个函数的所有调用者\nMATCH (caller)-[:CALLS]->(target {name: 'authenticate_user'})\nRETURN caller\n\n// 查找继承链\nMATCH (child)-[:INHERITS_FROM*]->(parent)\nWHERE child.name = 'MyClass'\nRETURN parent\n```\n\n**当前限制**：Cypher 子集是**只读**的，写操作仍需通过 `remember` / `ingest` / 自动写入钩子。\n\n资料来源：[CHANGELOG.md:1-80]()\n\n## 使用场景与演示\n\n`thought demo` 命令提供内置的演示功能，针对不同用户群体：\n\n| 受众 | 演示内容 | 源码位置 |\n|------|----------|----------|\n| `code` | Agent/开发者流程，14阶段代码分析演示 | `src/thought/demo.py` |\n| `writer` | 小说家/论文作者，矛盾检测，时间旅行查询 | `src/thought/demo.py` |\n| `legal` | 调查员/律师，证词矛盾图分析 | `src/thought/demo.py` |\n| `researcher` | 学术研究，引用关系分析 | `src/thought/demo.py` |\n| `all` | 运行所有受众演示 | `src/thought/demo.py` |\n\n资料来源：[src/thought/demo.py:1-50]()\n\n## 技术栈概览\n\n| 组件 | 技术选型 | 用途 |\n|------|----------|------|\n| 数据库 | SQLite + WAL 模式 | 持久化存储 |\n| 向量检索 | sentence-transformers / Ollama embed | 语义搜索 |\n| 图查询 | Cypher 子集 | 复杂关系查询 |\n| AST 解析 | tree-sitter | 多语言代码解析 |\n| CLI | Typer + Rich | 命令行界面 |\n| 协议 | MCP (Model Context Protocol) | AI 助手集成 |\n\n资料来源：[src/thought/ingest/code/python_extractor.py:1-30]()\n\n## 版本路线图\n\n| 版本 | 主题 | 资料来源 |\n|------|------|----------|\n| v0.5 | 写作垂直领域，代码理解增强 | `CHANGELOG.md` |\n| v0.6 | 写作功能完善（小说/学术写作） | `CHANGELOG.md` |\n| v0.7 | 调查领域（法律/合规/取证） | `CHANGELOG.md` |\n| v0.8 | 平台功能（图TUI/基准测试/联邦同步） | `CHANGELOG.md` |\n\n资料来源：[CHANGELOG.md:1-100]()\n\n## 开发规范\n\n项目遵循以下开发准则：\n\n1. **测试策略**：使用真实 SQLite 数据库测试，不使用 mock，确保测试与生产环境一致\n2. **代码风格**：显式优于巧妙，注释说明\"为什么\"而非\"做什么\"\n3. **PR 规范**：一个 PR 一个主题，必须有测试，必须更新 CHANGELOG\n4. **类型注解**：新代码应清晰标注类型\n5. **Linting**：提交前必须通过 `ruff check src tests`\n\n资料来源：[CONTRIBUTING.md:1-50]()\n\n## 总结\n\nthought-mcp 是一个功能完备的本地 AI 记忆工具，通过以下核心能力为开发者提供知识管理服务：\n\n- **多语言代码理解**：支持 Python、TypeScript、Rust、PHP 等语言的 AST 解析\n- **双时态模型**：支持事实的有效时间和系统学习时间的独立追踪\n- **本地优先**：无需云服务，完全运行在本地环境\n- **图查询能力**：通过 Cypher 子集实现复杂关系查询\n- **灵活摄入**：支持代码、文本、Git 历史等多种数据源的摄入\n\n---\n\n\n\n## 安装与快速开始\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [配置管理](#page-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/RNBBarrett/thought-mcp/blob/main/pyproject.toml)\n- [src/thought/cli.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/cli.py)\n- [src/thought/demo.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/demo.py)\n- [src/thought/ingest/code/pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/pipeline.py)\n- [src/thought/ingest/code/git_walker.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/git_walker.py)\n- [src/thought/layers/code.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/code.py)\n- [CONTRIBUTING.md](https://github.com/RNBBarrett/thought-mcp/blob/main/CONTRIBUTING.md)\n \n\n# 安装与快速开始\n\n本页面介绍 thought-mcp 的完整安装流程和快速上手指南。thought-mcp 是一个本地AI记忆工具，通过 SQLite 数据库存储知识库，支持代码图谱查询、Git历史感知摄取和多语言代码解析。\n\n## 系统要求\n\n在开始安装前，请确保环境满足以下要求：\n\n| 组件 | 最低版本 | 说明 |\n|------|---------|------|\n| Python | 3.10+ | 项目主语言 |\n| Git | 任意版本 | 用于代码仓库摄取 |\n| pip / uv | 最新版本 | 包管理器 |\n\n可选依赖项：\n\n| 组件 | 用途 | 安装方式 |\n|------|------|---------|\n| sentence-transformers | 语义向量嵌入 | 可选，未安装时使用确定性嵌入器 |\n| Ollama / LM Studio | 本地LLM集成 | 支持OpenAI兼容API |\n| tree-sitter | AST代码解析 | 自动安装 |\n\n## 安装方式\n\n### 方式一：pip 安装（推荐）\n\n```bash\npip install thought-mcp\n```\n\n### 方式二：源码安装\n\n```bash\ngit clone https://github.com/RNBBarrett/thought-mcp.git\ncd thought-mcp\npip install -e .\n```\n\n### 方式三：Docker 部署\n\n项目根目录包含 Dockerfile，支持容器化部署：\n\n```bash\ndocker build -t thought-mcp .\ndocker run thought-mcp thought --help\n```\n\n资料来源：[src/thought/cli.py:1-25]()\n\n## 初始化项目\n\n安装完成后，需要初始化 thought-mcp 来创建数据库和配置文件：\n\n```bash\nthought init\n```\n\n### init 命令参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--config` | `thought.toml` | 配置文件路径 |\n| `--db-path` | `.thought/thought.db` | SQLite 数据库路径 |\n| `--embedder` | `auto` | 嵌入器选择：`auto`、`sentence-transformers` 或 `deterministic` |\n| `--write-claude-md` | `True` | 是否生成 CLAUDE.md 供 MCP 客户端使用 |\n| `--quick` | `False` | 跳过首次运行的嵌入器预热 |\n\n初始化过程会执行以下操作：\n\n1. 创建 `.thought` 目录\n2. 初始化 SQLite 数据库文件\n3. 生成 `thought.toml` 配置文件\n4. 可选：写入 `CLAUDE.md` 提示文件\n\n资料来源：[src/thought/cli.py:50-85]()\n\n## 核心命令速查\n\n初始化完成后，可以使用以下核心命令：\n\n| 命令 | 功能 |\n|------|------|\n| `thought ingest TEXT` | 从命令行一次性摄取文本 |\n| `thought recall QUERY` | 自然语言查询知识库 |\n| `thought serve` | 启动 MCP 服务器 |\n| `thought stats` | 查看知识库统计信息 |\n| `thought doctor` | 环境健康检查 |\n\n## 快速开始示例\n\n### 步骤一：验证安装\n\n```bash\nthought doctor\n```\n\n此命令会检查环境依赖是否正确安装，包括数据库访问、嵌入器配置等。\n\n### 步骤二：知识摄取\n\n**摄取文本：**\n```bash\nthought ingest \"今天学习了Python的装饰器模式\"\n```\n\n**摄取文件：**\n```bash\nthought ingest --file ./src/main.py\n```\n\n**批量摄取（glob模式）：**\n```bash\nthought ingest --glob \"**/*.py\"\n```\n\n**从标准输入摄取：**\n```bash\ncat files.txt | thought ingest --stdin\n```\n\n资料来源：[src/thought/cli.py:100-120]()\n\n### 步骤三：查询召回\n\n```bash\nthought recall \"Python装饰器\"\n```\n\nrecall 命令返回最多 10 条匹配结果，支持以下高级参数：\n\n| 参数 | 说明 |\n|------|------|\n| `--as-of` | 时间旅行查询，指定历史时间点 |\n| `--scope` | 作用域过滤 |\n\n### 步骤四：运行演示\n\n项目内置多种场景演示：\n\n```bash\nthought demo [audience]\n```\n\n| audience 参数 | 说明 |\n|---------------|------|\n| `code` | Agent/开发者流程，包含 14 阶段代码垂直演示 |\n| `writer` | 小说家/论文作者场景，演示双时态模型 |\n| `legal` | 法律调查场景，演示矛盾检测 |\n| `researcher` | 学术研究场景，Cypher 查询演示 |\n| `all` | 运行所有场景 |\n\n资料来源：[src/thought/demo.py:1-45]()\n\n## 代码仓库摄取\n\nthought-mcp 支持深入分析代码仓库，建立代码知识图谱：\n\n### 基本摄取\n\n```bash\nthought ingest-git ./my-project\n```\n\n### 高级选项\n\n| 参数 | 可选值 | 说明 |\n|------|--------|------|\n| `--mode` | `snapshot`（默认）、`full` | 快照模式仅摄取HEAD，全量模式遍历所有提交 |\n| `--language` | `python`、`typescript`、`rust`、`php` 等 | 指定语言覆盖自动检测 |\n| `--skip-call-graph` | - | 跳过调用图构建 |\n\n摄取流程架构：\n\n```mermaid\ngraph TD\n A[git仓库] --> B[GitWalker遍历]\n B --> C{--mode参数}\n C -->|snapshot| D[仅获取HEAD]\n C -->|full| E[遍历所有提交]\n D --> F[代码文件解析]\n E --> F\n F --> G[语言提取器]\n G --> H[CodeEntity + CodeEdge]\n H --> I[CallGraph构建]\n I --> J[SQLite存储]\n```\n\n摄取完成后，可使用以下代码查询命令：\n\n| 命令 | 功能 |\n|------|------|\n| `thought callers ` | 查询直接调用者，按 PageRank 排序 |\n| `thought impact ` | 变更影响分析，查询传递调用者 |\n| `thought diff --from SHA1 --to SHA2` | 对比两次提交间的实体差异 |\n\n资料来源：[src/thought/ingest/code/git_walker.py:1-35]()\n\n## MCP 服务器模式\n\n启动 MCP 服务器供 AI 助手集成使用：\n\n```bash\nthought serve\n```\n\n### 传输方式\n\n| 方式 | 命令 | 说明 |\n|------|------|------|\n| stdio（默认） | `thought serve` | 标准输入输出通信 |\n| HTTP | `thought serve --transport streamable-http` | HTTP 协议通信 |\n\n服务器启动后会持续运行，等待 MCP 客户端连接。\n\n## 配置说明\n\n初始化后生成的 `thought.toml` 配置文件结构：\n\n```toml\n[database]\npath = \".thought/thought.db\"\n\n[embedder]\ntype = \"auto\" # auto | sentence-transformers | deterministic\n\n[server]\ntransport = \"stdio\"\n```\n\n### 嵌入器配置\n\n| 类型 | 说明 | 依赖 |\n|------|------|------|\n| `auto` | 自动检测sentence-transformers可用性 | 可选安装 |\n| `sentence-transformers` | 语义向量嵌入 | pip install sentence-transformers |\n| `deterministic` | 基于文本哈希的确定性嵌入 | 无外部依赖 |\n\n当设置 `auto` 时，系统会通过 `importlib.util.find_spec` 检测 sentence-transformers 是否可用，若未安装则回退到确定性嵌入器。\n\n资料来源：[src/thought/ingest/code/pipeline.py:40-60]()\n\n## 故障排除\n\n### doctor 命令检查项\n\n`thought doctor` 会验证以下项目：\n\n- Python 版本兼容性\n- 数据库文件可访问性\n- 嵌入器配置有效性\n- 必要的目录权限\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 嵌入器加载失败 | 使用 `--embedder deterministic` 降级使用 |\n| Git仓库检测失败 | 确认目录包含 `.git` 目录 |\n| 数据库锁定 | 检查是否有其他进程正在访问 |\n\n## 下一步\n\n安装完成后，建议继续阅读以下文档：\n\n- [使用指南]() - 深入了解 recall、caller、impact 等高级命令\n- [代码图谱分析]() - 理解调用图构建和代码实体关系\n- [开发指南](CONTRIBUTING.md) - 参与项目开发的代码规范\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [查询系统](#page-query-system), [图形层与图遍历](#page-graph-layer)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/server.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/server.py)\n- [src/thought/storage/base.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/storage/base.py)\n- [src/thought/ingest/pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/pipeline.py)\n- [src/thought/layers/__init__.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/__init__.py)\n- [src/thought/router/dispatcher.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/router/dispatcher.py)\n \n\n# 系统架构\n\n## 概述\n\nthought-mcp 是一个基于 SQLite 的本地 AI 记忆工具，采用分层架构设计，核心功能围绕知识库（Knowledge Base）管理、代码实体解析、自然语言查询路由三大模块展开。系统通过 MCP（Model Context Protocol）协议对外提供服务，支持本地 LLM 集成和双时态（bi-temporal）数据模型。资料来源：[src/thought/layers/__init__.py](src/thought/layers/__init__.py)\n\n## 核心架构分层\n\n系统采用四层架构模型，每一层职责明确，通过标准化接口进行通信：\n\n| 层级 | 模块 | 职责 |\n|------|------|------|\n| 接口层 | CLI / MCP Server | 用户交互、命令解析 |\n| 路由层 | Router / Dispatcher | 查询分类、自然语言转 Cypher |\n| 业务层 | Layers (Graph, Code, Recall) | 图查询、代码分析、实体检索 |\n| 存储层 | SQLite Backend | 数据持久化、向量存储 |\n\n```mermaid\ngraph TD\n A[CLI / MCP Client] --> B[Router / Dispatcher]\n B --> C{C 查询类型}\n C -->|CODE| D[CodeLayer]\n C -->|GRAPH| E[GraphLayer]\n C -->|RECALL| F[RecallLayer]\n C -->|ASK| G[AskModule]\n D --> H[SQLite Backend]\n E --> H\n F --> H\n G --> H\n H --> I[(SQLite DB)]\n```\n\n资料来源：[src/thought/router/dispatcher.py](src/thought/router/dispatcher.py)\n\n## 存储层架构\n\n### SQLite Backend\n\n存储层是整个系统的基础，采用 SQLite 作为主数据库，支持向量嵌入存储和双时态数据模型。Backend 提供了实体的创建、更新、查询以及嵌入向量存储的核心接口。资料来源：[src/thought/storage/base.py](src/thought/storage/base.py)\n\n#### 核心数据模型\n\n系统定义了两种核心数据模型：\n\n**Entity（实体）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | str | 实体唯一标识符 |\n| type | str | 实体类型（function, class, method 等） |\n| name | str | 实体名称 |\n| canonical_name | str | 规范化名称 |\n| scope | ScopeName | 作用域（shared/private） |\n| tier | Tier | 热数据层级（hot/cold） |\n| valid_from | datetime | 有效起始时间 |\n| valid_until | datetime \\| None | 有效结束时间（双时态） |\n| code_file | str \\| None | 代码文件路径 |\n| code_language | str \\| None | 编程语言 |\n| code_commit_sha | str \\| None | Git 提交 SHA |\n\n**Edge（关系）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | str | 关系唯一标识符 |\n| source_id | str | 源实体 ID |\n| target_id | str | 目标实体 ID |\n| relation_type | str | 关系类型（CALLS, IMPORTS, DEFINES 等） |\n\n资料来源：[src/thought/models.py](src/thought/models.py)\n\n### 存储层核心接口\n\nBackend 提供了以下核心方法来管理实体和关系：\n\n- `upsert_entity()` - 创建或更新实体，身份包含 `(code_file, code_commit_sha)` 以区分同名方法\n- `find_code_entity()` - 通过规范化名称快速查找代码实体\n- `store_embedding()` - 存储嵌入向量\n- `query_similar()` - 相似度检索\n\n资料来源：[src/thought/storage/base.py](src/thought/storage/base.py)\n\n## 摄入层架构\n\n### 摄入管道\n\n摄入管道负责将外部数据（代码、文档、法律文本等）转换为统一的实体-关系模型并存储到知识库中。Pipeline 是摄入管道的核心调度器，支持文件级别的原子性写入。资料来源：[src/thought/ingest/pipeline.py](src/thought/ingest/pipeline.py)\n\n```mermaid\ngraph LR\n A[Source File] --> B[Language Detection]\n B --> C[Language Extractor]\n C --> D[Entities + Edges]\n D --> E[Backend upsert]\n E --> F[Embedding]\n F --> G[(Knowledge Base)]\n```\n\n### 多语言代码解析器\n\n系统为每种支持的编程语言实现了专门的提取器，所有提取器遵循统一的接口规范：\n\n```python\ndef extract(source: str, file_path: str) -> tuple[list[CodeEntity], list[CodeEdge]]\n```\n\n**支持的编程语言及提取器：**\n\n| 语言 | 提取器文件 | 提取的实体类型 |\n|------|-----------|---------------|\n| Python | python_extractor.py | module, function, class, method, import |\n| TypeScript | typescript_extractor.py | module, function, class, method, import, export, inheritance |\n| PHP | php_extractor.py | module, function, class, method, import |\n| Rust | rust_extractor.py | module, function, struct, impl, method |\n\n资料来源：[src/thought/ingest/code/python_extractor.py](src/thought/ingest/code/python_extractor.py)\n\n### 调用图构建\n\n`build_call_graph` 模块负责解析代码中的函数调用关系，支持多级解析策略：\n\n1. **文件内匹配** - 在同一文件中查找被调用函数定义\n2. **唯一qualified后缀匹配** - `obj.method()` 匹配唯一的 `ClassName.method`\n3. **跨文件裸名称匹配** - 查找其他文件中定义的顶级函数\n4. **Stub创建** - 当找不到定义时，创建占位实体\n\n资料来源：[src/thought/ingest/code/call_graph.py](src/thought/ingest/code/call_graph.py)\n\n### Git 历史感知摄入\n\n`GitWalker` 支持两种摄入模式：\n\n- **snapshot 模式（默认）** - 仅摄入 HEAD 提交内容\n- **full 模式** - 遍历每个提交，关联实体与对应提交 SHA\n\n这种设计支持双时态查询，可以查询特定时间点的代码状态。资料来源：[src/thought/ingest/code/git_pipeline.py](src/thought/ingest/code/git_pipeline.py)\n\n## 业务层架构\n\n### Layer 模块\n\n`Layers` 模块封装了针对不同数据类型的图查询操作，提供领域特定的查询接口。资料来源：[src/thought/layers/__init__.py](src/thought/layers/__init__.py)\n\n#### GraphLayer\n\n通用的图查询层，提供基础的实体和关系查询能力，支持作用域过滤（shared/private/all）。\n\n#### CodeLayer\n\n代码专用查询层，提供程序员友好的接口：\n\n| 方法 | 功能 |\n|------|------|\n| `callers_of(name)` | 查询直接调用者，按 PageRank 排序 |\n| `callees_of(name)` | 查询调用的函数（同包内） |\n| `impact_set(name)` | 传递性影响集合（变更会影响哪些代码） |\n| `defines_in_file(path)` | 查询文件中定义的所有实体 |\n\n资料来源：[src/thought/layers/code.py](src/thought/layers/code.py)\n\n### 查询路由器\n\n`Router/Dispatcher` 是系统的查询入口点，负责将用户查询分类到对应的处理器：\n\n**查询类型分类：**\n\n| 查询类型 | 触发关键词 | 处理器 |\n|----------|-----------|--------|\n| CODE | function, class, caller, callee, file extensions, camelCase/snake_case |\n| CHANGE | changed, added, removed, since, before |\n| RECALL | 记忆相关查询 |\n| ASK | 自然语言问题 |\n\n**路由组合：**\n\n- CODE × CHANGE → HYBRID（如 \"auth.middleware 自 v1.0 以来的变更\"）\n- 支持 `as_of` 时间旅行查询\n\n资料来源：[src/thought/router/dispatcher.py](src/thought/router/dispatcher.py)\n\n### 自然语言查询模块\n\n`Ask` 模块将自然语言问题翻译为 Cypher 查询语句：\n\n```mermaid\ngraph TD\n A[Natural Language Question] --> B[LLM Provider]\n B --> C[Cypher Query]\n C --> D[Parser Validation]\n D -->|Valid| E[Execute Query]\n D -->|Invalid| F[Recall Fallback]\n```\n\n翻译过程遵循以下约束：\n- 仅使用只读 Cypher 特性（MATCH, WHERE, RETURN, LIMIT）\n- 禁止使用写操作（MERGE, CREATE, DELETE, SET）\n- 支持 AS_OF 时间旅行语法\n\n资料来源：[src/thought/query/ask.py](src/thought/query/ask.py)\n\n## MCP 服务器架构\n\n### Server 组件\n\nMCP 服务器通过 `server.py` 实现，提供标准化的工具接口供 MCP 客户端调用。服务器封装了 CLI 的核心功能，暴露为 MCP 工具。资料来源：[src/thought/server.py](src/thought/server.py)\n\n```mermaid\ngraph TD\n A[MCP Client] --> B[Server Handler]\n B --> C[Router]\n B --> D[Ingest Pipeline]\n B --> E[Recall Layer]\n B --> F[Code Layer]\n```\n\n## 数据库生命周期管理\n\n系统提供完整的数据库管理命令：\n\n| 命令 | 功能 |\n|------|------|\n| `thought db size` | 查看磁盘使用情况和实体/关系数量 |\n| `thought db flush` | 清空知识库（支持时间范围过滤） |\n| `thought db backup` | 在线备份快照 |\n| `thought db load` | 加载备份文件（支持合并模式） |\n| `thought db inspect` | 预览备份文件内容 |\n\n所有破坏性操作前自动备份到 `.bak.`。资料来源：[src/thought/cli.py](src/thought/cli.py)\n\n## 本地 LLM 集成\n\n系统支持连接本地 LLM 提供者：\n\n- **Ollama** - 原生 `/api/embed` 端点（批量）\n- **LM Studio** - OpenAI 兼容接口\n- **任意 OpenAI 兼容服务器**\n\n自动嵌入选择器会探测 `sentence_transformers` 包是否可用，不可用时自动降级到确定性嵌入器。资料来源：[src/thought/storage/sqlite/backend.py](src/thought/storage/sqlite/backend.py)\n\n## CLI 命令体系\n\n系统提供丰富的命令行接口：\n\n| 命令类别 | 主要命令 |\n|----------|----------|\n| 初始化 | `thought init` |\n| 数据摄入 | `thought ingest-code`, `thought ingest-git`, `thought ingest-prose` |\n| 查询 | `thought recall`, `thought ask`, `thought callers`, `thought impact` |\n| 代码分析 | `thought diff --from --to ` |\n| 数据库 | `thought db size/flush/backup/load` |\n| 客户端 | `thought install` (Cline/Claude Code/Cursor) |\n\n资料来源：[src/thought/cli.py](src/thought/cli.py)\n\n---\n\n\n\n## 配置管理\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [Agent集成与适配器](#page-agent-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/cli.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/cli.py)\n- [src/thought/hooks/install.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/hooks/install.py)\n- [src/thought/clients.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/clients.py)\n- [src/thought/storage/sqlite/backend.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/storage/sqlite/backend.py)\n- [src/thought/ingest/code/git_pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/git_pipeline.py)\n- [src/thought/layers/code.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/code.py)\n \n\n# 配置管理\n\n## 概述\n\n配置管理是 thought-mcp 系统的核心基础设施，负责管理数据库连接、嵌入器选择、CLI 参数配置以及多客户端（MCP Server）集成配置。系统通过 TOML 格式的配置文件、环境变量和命令行参数三层配置机制，为用户提供灵活的定制能力。\n\n配置管理模块贯穿整个应用生命周期，包括初始化阶段（`thought init`）、运行阶段（各 CLI 命令）以及客户端集成阶段（Claude Code Hooks、MCP Server 安装）。资料来源：[src/thought/cli.py:50-80]()\n\n## 配置架构\n\nthought-mcp 采用分层配置架构，核心组件包括：\n\n```mermaid\ngraph TD\n A[用户配置] --> B[CLI 参数]\n A --> C[TOML 配置文件]\n A --> D[环境变量]\n B --> E[Config 对象]\n C --> E\n D --> E\n E --> F[SQLiteBackend]\n E --> G[Embedder]\n E --> H[HookInstall]\n E --> I[ClientInstall]\n```\n\n### 配置层级\n\n| 层级 | 来源 | 优先级 | 典型用途 |\n|------|------|--------|----------|\n| CLI 参数 | 命令行传入 | 最高 | 临时覆盖、脚本自动化 |\n| TOML 配置 | `thought.toml` | 中 | 持久化项目级配置 |\n| 环境变量 | 系统环境 | 最低 | 容器化部署默认值 |\n\n资料来源：[src/thought/cli.py:50-72]()\n\n## CLI 初始化配置\n\n`thought init` 命令是配置管理的入口点，负责创建数据库文件、配置文件和 Agent 面向文档。\n\n### 命令签名\n\n```python\n@app.command()\ndef init(\n config: Path = typer.Option(\"thought.toml\", help=\"Path to config file.\"),\n db_path: str = typer.Option(\".thought/thought.db\", help=\"SQLite database path.\"),\n embedder: str = typer.Option(\n \"auto\", help=\"'auto' picks sentence-transformers if available, else deterministic.\",\n ),\n write_claude_md: bool = typer.Option(\n True, \"--write-claude-md/--no-claude-md\",\n help=\"Drop a CLAUDE.md so MCP clients learn how to use the tool.\",\n ),\n quick: bool = typer.Option(\n False, \"--quick\", help=\"Skip first-run embedder warmup.\",\n ),\n) -> None:\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `config` | Path | `thought.toml` | TOML 配置文件路径 |\n| `db_path` | str | `.thought/thought.db` | SQLite 数据库文件路径 |\n| `embedder` | str | `auto` | 嵌入器选择：`auto`、`sentence-transformers`、`deterministic` |\n| `write_claude_md` | bool | `True` | 是否生成 CLAUDE.md 供 MCP 客户端学习 |\n| `quick` | bool | `False` | 是否跳过嵌入器首次预热 |\n\n资料来源：[src/thought/cli.py:52-68]()\n\n### 配置初始化流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as thought init\n participant FS as 文件系统\n participant TOML as TOML 解析器\n participant DB as SQLiteBackend\n\n User->>CLI: thought init --config thought.toml\n CLI->>FS: 检查配置文件\n FS-->>CLI: 配置文件不存在\n CLI->>FS: 创建目录结构 (.thought/)\n CLI->>FS: 创建 thought.toml\n Note over CLI: 使用 POSIX 风格路径分隔符
避免 Windows 路径解析问题\n CLI->>DB: 初始化数据库\n CLI->>FS: 写入 CLAUDE.md (可选)\n CLI-->>User: 配置完成\n```\n\n初始化时，系统会自动创建父目录（`parents=True`），确保数据库路径有效。TOML 配置文件采用 POSIX 风格路径分隔符，以兼容 Windows 系统。资料来源：[src/thought/cli.py:74-78]()\n\n## 嵌入器配置\n\n嵌入器（Embedder）是 thought-mcp 向量检索能力的核心，负责将文本转换为高维向量。\n\n### 嵌入器自动选择机制\n\n```python\n# 伪代码示例\nif embedder == \"auto\":\n if importlib.util.find_spec(\"sentence_transformers\"):\n return OllamaEmbedder() # 或 SentenceTransformerEmbedder\n else:\n return DeterministicEmbedder()\n```\n\n系统通过 `importlib.util.find_spec` 检测 `sentence_transformers` 包是否可用，自动选择最优嵌入器实现。这种设计确保了：\n\n1. 在安装了 `sentence-transformers` 的环境中自动使用高质量嵌入器\n2. 在未安装可选依赖时优雅降级到确定性嵌入器\n3. 避免因可选依赖缺失导致的运行时错误\n\n资料来源：[src/thought/cli.py:95-102]()\n\n### 嵌入器配置参数\n\n| 参数 | 说明 | 可选值 |\n|------|------|--------|\n| `model_name` | 嵌入模型名称 | 字符串 |\n| `model_version` | 模型版本 | 字符串 |\n| `dim` | 向量维度 | 整数 |\n| `batch_size` | 批处理大小 | 整数 |\n\n嵌入器配置存储在数据库的 `embeddings` 表中，每个实体可关联多个嵌入向量。资料来源：[src/thought/storage/sqlite/backend.py:1-50]()\n\n## 数据库配置\n\n### 数据库路径配置\n\n数据库路径通过 `db_path` 参数指定，默认为 `.thought/thought.db`。初始化时会自动创建父目录：\n\n```python\nPath(db_path).parent.mkdir(parents=True, exist_ok=True)\n```\n\n### 数据库后端配置\n\n`SQLiteBackend` 类管理所有数据库操作，包括：\n\n- 连接管理（读写、只读模式）\n- 事务控制\n- 实体与关系存储\n- 向量嵌入存储\n- 代码实体索引\n\n```mermaid\ngraph TD\n A[应用程序] --> B[SQLiteBackend]\n B --> C[主数据库文件]\n B --> D[WAL 文件]\n B --> E[SHM 文件]\n B --> F[entities 表]\n B --> G[edges 表]\n B --> H[embeddings 表]\n B --> I[applied_migrations 表]\n```\n\n资料来源：[src/thought/storage/sqlite/backend.py:1-100]()\n\n### 数据库生命周期命令\n\n| 命令 | 功能 |\n|------|------|\n| `thought db size` | 显示数据库磁盘占用及实体/关系计数 |\n| `thought db flush` | 清空知识库，支持按时间范围过滤 |\n| `thought db backup` | 在线备份数据库快照 |\n| `thought db load` | 原子级替换或合并数据库 |\n| `thought db inspect` | 检查备份文件内容 |\n\n## Hook 配置管理\n\nHook 系统允许 thought-mcp 与 Claude Code 深度集成，在特定事件触发时自动执行记忆操作。\n\n### 支持的 Hook 类型\n\n| Hook 类型 | 触发事件 | 命令 | 说明 |\n|-----------|----------|------|------|\n| `recall` | UserPromptSubmit | `thought hook recall` | 用户提交提示时召回相关记忆 |\n| `write` | Stop | `thought hook write` | 会话结束时自动保存上下文 |\n| `context` | SessionStart | `thought hook context` | 会话开始时注入相关上下文 |\n\n### Hook 安装范围\n\n```python\ndef settings_path(*, scope: Literal[\"project\", \"user\"] = \"project\") -> Path:\n \"\"\"Return the ``.claude/settings.json`` path for the requested scope.\"\"\"\n if scope == \"project\":\n return Path.cwd() / \".claude\" / \"settings.json\"\n```\n\n- **项目级别**（默认）：`.claude/settings.json`，随代码库版本控制\n- **用户级别**：用户主目录下的全局配置\n\n资料来源：[src/thought/hooks/install.py:40-50]()\n\n### Hook 安装结果\n\n```python\n@dataclass(frozen=True)\nclass HookInstallResult:\n kind: HookKind\n path: Path\n status: Literal[\"installed\", \"already_present\", \"error\"]\n detail: str = \"\"\n```\n\n安装状态含义：\n\n- `installed`：新安装成功\n- `already_present`：Hook 已存在且配置匹配\n- `error`：安装失败（详情在 `detail` 中）\n\n## MCP 客户端配置\n\nMCP（Model Context Protocol）客户端配置允许将 thought-mcp 作为服务器集成到各种 IDE 和工具中。\n\n### 支持的客户端\n\n| 客户端 | 配置文件 |\n|--------|----------|\n| Claude Code | `.claude/settings.json` |\n| Cursor | `cursor.settings.json` |\n| VS Code | `vscode-mcp.json` |\n| 其他 | 根据 `_PATH_FNS` 映射 |\n\n### 服务器配置块\n\n```python\ndef server_block() -> dict:\n \"\"\"Generate the MCP server configuration block.\"\"\"\n return {\n \"command\": \"uv\",\n \"args\": [\"run\", \"thought\", \"mcp\"],\n \"env\": {\n \"THOUGHT_DB_PATH\": str(DB_PATH),\n },\n }\n```\n\n### 客户端安装流程\n\n```mermaid\ngraph TD\n A[install call] --> B{配置文件存在?}\n B -->|否| C[创建空配置对象]\n B -->|是| D[读取现有配置]\n D --> E{JSON 有效?}\n E -->|否| F[返回错误]\n E -->|是| G[合并服务器配置]\n C --> G\n G --> H{需要备份?}\n H -->|是| I[创建 .thought.bak 备份]\n H -->|否| J[写入配置文件]\n I --> J\n J --> K[返回安装结果]\n```\n\n安装过程会备份原配置文件（后缀 `.thought.bak`），确保配置可回滚。资料来源：[src/thought/clients.py:60-90]()\n\n## TOML 配置文件格式\n\n### 配置文件位置\n\n默认搜索顺序：\n1. 当前目录的 `thought.toml`\n2. 用户指定路径（通过 `--config` 参数）\n\n### 典型配置示例\n\n```toml\n# thought.toml\n[database]\npath = \".thought/thought.db\"\n\n[embedder]\ntype = \"auto\" # 或 \"sentence-transformers\", \"deterministic\"\nmodel_name = \"all-MiniLM-L6-v2\"\n\n[hooks]\nrecall = true\nwrite = true\ncontext = false\n\n[client]\nserver_name = \"thought\"\n```\n\n### 路径格式规范\n\n```python\n# 确保 TOML 中使用 POSIX 风格路径分隔符\n# 避免 Windows 路径如 C:\\Users\\...\\thought.db 在 TOML 解析时出现问题\n```\n\n资料来源：[src/thought/cli.py:77-78]()\n\n## 代码图谱配置\n\n代码图谱是 thought-mcp 的核心功能之一，支持通过 Git 历史追踪代码实体变化。\n\n### Git 摄入配置\n\n```python\nclass GitIngestReport:\n head_sha: str # 当前 HEAD 提交 SHA\n mode: str # \"snapshot\" 或 \"full\"\n commits_visited: int # 访问的提交数\n files_ingested: int # 摄入的文件数\n call_edges: int # 创建的调用关系边数\n```\n\n### Git 摄入模式\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| `snapshot`（默认） | 仅摄入 HEAD，快速初始化 | 首次摄入、日常使用 |\n| `full` | 遍历所有提交，完整历史 | 历史分析、时间旅行查询 |\n\n```bash\n# 快照模式（默认）\nthought ingest-git \n\n# 全量模式\nthought ingest-git --mode full\n```\n\n资料来源：[src/thought/ingest/code/git_pipeline.py:80-95]()\n\n### 代码实体存储配置\n\n每个代码实体存储以下元数据：\n\n| 字段 | 说明 |\n|------|------|\n| `code_file` | 代码文件相对路径 |\n| `code_language` | 编程语言（python, typescript, rust, php） |\n| `code_commit_sha` | 所在提交的 SHA |\n\n这些字段支持按代码文件和提交进行精确查询。资料来源：[src/thought/layers/code.py:30-50]()\n\n## 环境变量配置\n\n### 支持的环境变量\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `THOUGHT_DB_PATH` | 数据库文件路径 | `.thought/thought.db` |\n| `THOUGHT_CONFIG` | 配置文件路径 | `thought.toml` |\n\n环境变量在配置层级中优先级最低，可被 CLI 参数和 TOML 配置覆盖。\n\n## 配置验证与错误处理\n\n### 常见配置错误\n\n| 错误类型 | 原因 | 解决方案 |\n|----------|------|----------|\n| 数据库路径无效 | 父目录不存在 | 使用 `--db-path` 指定有效路径 |\n| TOML 解析失败 | 语法错误 | 检查配置文件格式 |\n| 嵌入器初始化失败 | 缺少可选依赖 | 安装 `sentence-transformers` 或使用 `auto` |\n| Hook 安装失败 | 权限不足 | 检查 `.claude` 目录写入权限 |\n\n### 备份与恢复\n\n系统自动执行以下备份：\n\n1. **数据库备份**：执行 `db flush` 前自动备份到 `.bak.`\n2. **配置文件备份**：安装 Hook/Client 前备份原配置到 `.thought.bak`\n\n```python\n# 自动备份示例\nif backup:\n shutil.copy(path, f\"{path}.thought.bak\")\n```\n\n## 配置最佳实践\n\n### 项目级配置\n\n- 使用默认的 `thought.toml` 配置文件\n- 将 `.thought/` 目录添加到 `.gitignore`\n- 通过 `.claude/settings.json` 版本控制 Hook 配置\n\n### 生产环境配置\n\n- 使用绝对路径指定数据库位置\n- 启用 `db backup` 定期备份\n- 生产环境建议显式指定嵌入器类型而非 `auto`\n\n### 团队协作\n\n- 项目级 Hook 配置应纳入版本控制\n- 数据库文件不应提交到代码仓库\n- 使用 `thought db inspect` 验证备份文件后再加载\n\n## 相关命令参考\n\n| 命令 | 功能 |\n|------|------|\n| `thought init` | 初始化配置和数据库 |\n| `thought db size` | 查看配置状态 |\n| `thought db backup` | 备份配置数据 |\n| `thought hook install` | 安装 Claude Code Hooks |\n| `thought client install` | 安装 MCP 客户端配置 |\n| `thought config show` | 显示当前配置 |\n\n---\n\n\n\n## 代码摄取与解析\n\n### 相关页面\n\n相关主题：[实体与关系管理](#page-entity-management), [图形层与图遍历](#page-graph-layer)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/ingest/code/pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/pipeline.py)\n- [src/thought/ingest/code/python_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/python_extractor.py)\n- [src/thought/ingest/code/typescript_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/typescript_extractor.py)\n- [src/thought/ingest/code/rust_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/rust_extractor.py)\n- [src/thought/ingest/code/php_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/php_extractor.py)\n- [src/thought/ingest/code/call_graph.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/call_graph.py)\n- [src/thought/ingest/code/git_pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/git_pipeline.py)\n \n\n# 代码摄取与解析\n\n## 概述\n\n代码摄取与解析是 thought-mcp 项目的核心子系统，负责将源代码文件解析为结构化的实体（Entity）和关系边（Edge），并存储到知识库中。该系统支持多种编程语言的 AST 解析、调用图构建、嵌入向量生成，以及 Git 历史感知的增量摄取。\n\n**核心职责：**\n\n- 使用 tree-sitter 解析多种语言的源代码\n- 提取函数、类、方法、模块等代码实体\n- 构建实体间的调用关系（Call Graph）\n- 生成语义嵌入向量以支持 VIBE 检索\n- 支持 Git 历史感知的多快照摄取\n\n资料来源：[src/thought/ingest/code/pipeline.py:1-50]()\n\n## 系统架构\n\n```mermaid\ngraph TD\n A[代码文件] --> B[语言检测]\n B --> C[对应语言 Extractor]\n C --> D[CodeEntity 列表]\n C --> E[CodeEdge 列表]\n D --> F[upsert_entity]\n E --> G[build_call_graph]\n G --> H[upsert_edge]\n F --> I[嵌入向量生成]\n I --> J[store_embedding]\n D --> K[source_id 生成]\n J --> L[(SQLite KB)]\n H --> L\n K --> F\n K --> G\n```\n\n### 核心组件\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| CodePipeline | `pipeline.py` | 主编排器，协调摄取流程 |\n| PythonExtractor | `python_extractor.py` | Python AST 解析 |\n| TypeScriptExtractor | `typescript_extractor.py` | TypeScript/JavaScript 解析 |\n| RustExtractor | `rust_extractor.py` | Rust AST 解析 |\n| PHPExtractor | `php_extractor.py` | PHP AST 解析 |\n| CallGraphBuilder | `call_graph.py` | 调用关系构建 |\n| GitPipeline | `git_pipeline.py` | Git 历史感知摄取 |\n| GitWalker | `git_walker.py` | Git 仓库遍历 |\n\n资料来源：[src/thought/ingest/code/pipeline.py:1-100]()\n\n## 语言支持与检测\n\n### 支持的语言\n\n系统通过文件扩展名自动检测编程语言：\n\n| 语言 | 扩展名 | Extractor |\n|------|--------|-----------|\n| Python | `.py` | PythonExtractor |\n| TypeScript | `.ts`, `.tsx` | TypeScriptExtractor |\n| Rust | `.rs` | RustExtractor |\n| PHP | `.php` | PHPExtractor |\n\n语言检测逻辑位于 `detect_language()` 函数，通过文件扩展名匹配对应的提取器。\n\n资料来源：[src/thought/ingest/code/pipeline.py:150-180]()\n\n## 实体提取流程\n\n### 通用提取模式\n\n每种语言的提取器遵循统一的接口模式：\n\n```python\ndef extract(source: str, file_path: str) -> tuple[list[CodeEntity], list[CodeEdge]]:\n parser = _get_parser()\n source_bytes = source.encode(\"utf-8\")\n tree = parser.parse(source_bytes)\n root = tree.root_node\n \n # 1. 创建模块实体\n entities.append(CodeEntity(...))\n \n # 2. 遍历 AST 节点\n _walk_module(root, ...)\n \n return entities, edges\n```\n\n所有提取器返回类型一致的 `CodeEntity` 列表和 `CodeEdge` 列表，确保下游处理逻辑统一。\n\n资料来源：[src/thought/ingest/code/python_extractor.py:80-100]()\n\n### 提取的实体类型\n\n| 实体类型 | 说明 | 典型属性 |\n|----------|------|----------|\n| `module` | 模块/文件 | `signature`, `docstring`, `visibility` |\n| `class` | 类定义 | `signature`, `docstring`, `visibility` |\n| `function` | 函数定义 | `signature`, `docstring`, `visibility` |\n| `method` | 类方法 | `signature`, `visibility`, `class` 属性 |\n| `import` | 导入语句 | `from_import` 属性 |\n\n资料来源：[src/thought/ingest/code/python_extractor.py:1-50]()\n\n### Python 提取器\n\nPython 提取器使用 tree-sitter-python 解析器，处理以下 AST 节点类型：\n\n- `module` → 模块实体\n- `class_definition` → 类实体\n- `function_definition` → 函数/方法实体\n- `import_statement` / `import_from_statement` → 导入边\n- `decorated_definition` → 装饰器处理\n\nPython 内置函数（`len`, `sum`, `.append` 等）被过滤，不生成实体，避免污染影响图。\n\n资料来源：[src/thought/ingest/code/python_extractor.py:50-80]()\n\n### TypeScript 提取器\n\nTypeScript 提取器额外处理：\n\n- **继承关系** (`INHERITS_FROM`)：解析 `extends` 和 `implements` 子句\n- **导出语句** (`export_statement`)：支持 `export class` / `export function` 递归解析\n\n```typescript\nclass Foo extends Bar implements Baz {}\n// 生成 INHERITS_FROM 边: Foo → Bar\n```\n\n资料来源：[src/thought/ingest/code/typescript_extractor.py:1-80]()\n\n### Rust 提取器\n\nRust 提取器处理 `function_item` 节点，并记录 `impl_type` 属性以关联方法与类型：\n\n```rust\nimpl TypeName {\n fn method(&self) {}\n}\n// 方法实体的 attrs 包含 {\"impl_type\": \"TypeName\"}\n```\n\n资料来源：[src/thought/ingest/code/rust_extractor.py:1-60]()\n\n### PHP 提取器\n\nPHP 提取器使用递归扫描处理嵌套结构：\n\n```php\n # 获取提交时的文件列表\ngit show : # 获取文件在特定提交的内容\n```\n\n资料来源：[src/thought/ingest/code/git_walker.py:1-50]()\n\n### Bi-temporal 模型\n\n摄取时记录 `code_commit_sha`，支持 bi-temporal 查询：\n\n- `valid_from` / `valid_until`：实体的有效时间范围\n- `as_of_kind='valid'`：查询特定日期的代码状态\n- `as_of_kind='learned'`：查询系统在该日期学到的知识\n\n```python\neid = self._backend.upsert_entity(\n code_commit_sha=commit_sha, # 关联到特定提交\n ...\n)\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:100-150]()\n\n## 嵌入向量生成\n\n### VIBE 检索支持\n\n为每个代码实体生成嵌入向量，支持通过意图（而非精确名称）检索：\n\n```python\nembed_text_parts = [ent.name, ent.signature]\nif ent.docstring:\n embed_text_parts.append(ent.docstring)\nembed_text = \"\\n\".join(p for p in embed_text_parts if p)\nvec = self._embedder.embed(embed_text)\nself._backend.store_embedding(\n entity_id=eid,\n model_name=self._embedder.model_name,\n model_version=self._embedder.model_version,\n dim=self._embedder.dim,\n vector=vector_to_bytes(vec),\n)\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:120-140]()\n\n### 自动嵌入器选择\n\n系统支持自动选择嵌入器：\n\n- 优先使用 `sentence-transformers`（如已安装）\n- 回退到确定性嵌入器（`auto` 模式）\n\n```python\n# auto embedder selector\nif importlib.util.find_spec(\"sentence_transformers\") is not None:\n return SentenceTransformerEmbedder()\nreturn DeterministicEmbedder()\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:150-180]()\n\n## 事务与存储\n\n### 原子性保证\n\n每个文件的摄取在单个事务中完成：\n\n```python\nself._backend.begin()\ntry:\n name_to_id, embeddings_created = self._write_entities(...)\n edge_ids, unresolved = self._write_edges(...)\n self._backend.commit()\nexcept Exception:\n self._backend.rollback()\n raise\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:180-220]()\n\n### 实体唯一性\n\n实体的唯一标识包含 `(code_file, code_commit_sha)`，确保同一函数在不同文件或不同提交中不会合并：\n\n```python\n# upsert_entity identity now includes (code_file, code_commit_sha)\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:60-80]()\n\n## 增量扫描\n\n### ScanLog\n\n系统维护 `scan_log` 表记录扫描历史，支持增量摄取：\n\n```python\ndef scan(repo_path: str, agent: str | None = None, since: str | None = None, max_files: int | None = None, note: str | None = None):\n \"\"\"Incremental code-scan primitive. Walks repo_path, ingests changed/new files,\n records a row in scan_log so the next call picks up where this one left off.\"\"\"\n```\n\n每次扫描后记录时间戳，下次调用时跳过已处理的变更。\n\n资料来源：[src/thought/server.py:1-50]()\n\n## 配置与使用\n\n### CLI 命令\n\n| 命令 | 说明 |\n|------|------|\n| `thought ingest-git ` | Git 历史摄取 |\n| `thought ingest-code ` | 单文件/目录摄取 |\n| `thought callers ` | 查询直接调用者 |\n| `thought impact ` | 查询影响集合 |\n| `thought diff --from --to ` | 提交间差异 |\n\n### 初始化配置\n\n```python\n@app.command()\ndef init(\n config: Path = typer.Option(\"thought.toml\"),\n db_path: str = typer.Option(\".thought/thought.db\"),\n embedder: str = typer.Option(\"auto\"),\n write_claude_md: bool = typer.Option(True),\n quick: bool = typer.Option(False),\n):\n```\n\n资料来源：[src/thought/cli.py:1-50]()\n\n## 数据模型\n\n### CodeEntity\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `name` | str | 实体名称 |\n| `type_` | str | 实体类型（module/class/function/method） |\n| `language` | str | 编程语言 |\n| `file_path` | str | 文件路径 |\n| `line_start` | int | 起始行号 |\n| `line_end` | int | 结束行号 |\n| `signature` | str | 函数签名 |\n| `docstring` | str | 文档字符串 |\n| `visibility` | str | 可见性（public/private） |\n| `attrs` | dict | 额外属性 |\n\n### CodeEdge\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `source_name` | str | 源实体名称 |\n| `target_name` | str | 目标实体名称 |\n| `relation_type` | str | 关系类型（CALLS/DEFINES/IMPORTS） |\n| `line_number` | int | 关联代码行号 |\n| `attrs` | dict | 额外属性（如 `from_import`） |\n\n资料来源：[src/thought/ingest/code/python_extractor.py:20-50]()\n\n## 扩展新的语言\n\n要添加新的语言支持，需实现以下步骤：\n\n1. **创建提取器文件**：如 `newlang_extractor.py`\n2. **实现 `extract()` 函数**：返回 `list[CodeEntity]` 和 `list[CodeEdge]`\n3. **注册语言检测**：在 `pipeline.py` 的 `detect_language()` 中添加扩展名映射\n4. **安装 tree-sitter 语法**：确保 tree-sitter-{lang} 可用\n\n```python\ndef extract(source: str, file_path: str) -> tuple[list[CodeEntity], list[CodeEdge]]:\n parser = _get_parser()\n source_bytes = source.encode(\"utf-8\")\n tree = parser.parse(source_bytes)\n root = tree.root_node\n # ... 遍历 AST，生成实体和边\n return entities, edges\n\n---\n\n\n\n## 实体与关系管理\n\n### 相关页面\n\n相关主题：[代码摄取与解析](#page-code-ingestion), [记忆模型与检索](#page-memory-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/ingest/code/types.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/types.py)\n- [src/thought/ingest/code/python_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/python_extractor.py)\n- [src/thought/ingest/code/typescript_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/typescript_extractor.py)\n- [src/thought/ingest/code/rust_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/rust_extractor.py)\n- [src/thought/ingest/code/call_graph.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/call_graph.py)\n- [src/thought/ingest/code/pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/pipeline.py)\n- [src/thought/layers/code.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/code.py)\n- [src/thought/models.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/models.py)\n \n\n# 实体与关系管理\n\n## 概述\n\n实体与关系管理是 thought-mcp 的核心子系统，负责从代码库中提取结构化实体（函数、类、模块、方法等）及其关系（CALLS、IMPORTS、DEFINES、INHERITS_FROM 等），并将这些信息持久化到知识库中供后续查询使用。\n\n该系统基于树形语法解析器（tree-sitter）实现多语言代码解析，采用双向时态数据模型记录实体的生命周期，并通过 PageRank 算法实现智能调用链分析。\n\n资料来源：[src/thought/ingest/code/types.py:1-50]()\n\n## 核心数据模型\n\n### CodeEntity 代码实体\n\n`CodeEntity` 是代码提取阶段产生的中间数据结构，代表代码库中的一个可识别元素：\n\n```python\n@dataclass\nclass CodeEntity:\n name: str # 实体名称\n type_: str # 实体类型 (function, class, method, module...)\n language: str # 编程语言 (python, typescript, rust...)\n file_path: str # 文件路径\n line_start: int # 起始行号\n line_end: int # 结束行号\n signature: str | None = None # 函数/方法签名\n docstring: str | None = None # 文档字符串\n visibility: str = \"public\" # 可见性 (public, private, protected)\n attrs: dict[str, object] = field(default_factory=dict) # 扩展属性\n```\n\n资料来源：[src/thought/ingest/code/types.py:10-22]()\n\n### CodeEdge 代码关系\n\n`CodeEdge` 描述两个代码实体之间的关系：\n\n```python\n@dataclass\nclass CodeEdge:\n source_name: str # 源实体名称\n target_name: str # 目标实体名称\n relation_type: str # 关系类型\n line_number: int | None = None # 定义行号\n attrs: dict[str, object] = field(default_factory=dict) # 扩展属性\n```\n\n资料来源：[src/thought/ingest/code/types.py:24-31]()\n\n### Entity 与 Edge (存储模型)\n\n存储层使用 pydantic 模型定义实体和边的结构：\n\n```python\nclass Entity(BaseModel):\n id: str\n type: str\n name: str\n canonical_name: str\n scope: ScopeName # shared | private\n tier: Tier # hot | warm | cold\n importance: float = Field(ge=0.0, le=1.0)\n valid_from: datetime # 有效起始时间（双向时态）\n valid_until: datetime | None = None # 有效结束时间（NULL 表示当前有效）\n learned_at: datetime # 系统学习时间\n code_file: str | None = None # 代码文件路径\n code_language: str | None = None # 代码语言\n code_commit_sha: str | None = None # Git 提交 SHA\n access_count: int = 0\n attrs: dict[str, object] = Field(default_factory=dict)\n```\n\n资料来源：[src/thought/models.py:58-76]()\n\n## 实体类型分类\n\n| 类型 | 描述 | 示例 |\n|------|------|------|\n| `function` | 函数定义 | Python `def func()` |\n| `class` | 类定义 | Python `class Foo:` |\n| `method` | 类方法 | Rust `fn method(&self)` |\n| `module` | 模块/文件 | 每个代码文件 |\n| `interface` | 接口定义 | TypeScript `interface Foo` |\n| `struct` | 结构体 | Rust `struct Foo` |\n\n资料来源：[src/thought/ingest/code/python_extractor.py:40-48]()\n\n## 关系类型分类\n\n| 关系类型 | 描述 | 方向 |\n|----------|------|------|\n| `CALLS` | 函数调用关系 | source → target |\n| `DEFINES` | 定义关系 | class/module → method/function |\n| `INHERITS_FROM` | 继承关系 | 子类 → 父类 |\n| `IMPORTS` | 导入关系 | 模块 → 被导入模块 |\n| `CONTRADICTS` | 矛盾关系 | 用于事实校正 |\n\n资料来源：[src/thought/ingest/code/typescript_extractor.py:80-90]()\n\n## 多语言代码提取架构\n\n### 提取器注册表\n\n系统通过懒加载方式注册各语言的提取器：\n\n```python\n_LOADERS = {\n \"python\": _python_extractor,\n \"typescript\": _typescript_extractor,\n \"go\": _go_extractor,\n \"rust\": _rust_extractor,\n \"java\": _java_extractor,\n \"php\": _php_extractor,\n}\n```\n\n资料来源：[src/thought/ingest/code/ast_extractor.py:30-44]()\n\n### Python 提取器\n\nPython 提取器使用 tree-sitter-python 解析代码 AST：\n\n1. **模块实体**：为每个文件创建模块节点\n2. **函数扫描**：遍历 `function_definition` 节点\n3. **类扫描**：遍历 `class_definition` 节点\n4. **继承关系**：从类定义的 `base_clause` 提取父类\n5. **导入关系**：处理 `import_statement` 和 `import_from_statement`\n\n```python\ndef extract(source: str, file_path: str) -> tuple[list[CodeEntity], list[CodeEdge]]:\n parser = _get_parser()\n tree = parser.parse(source_bytes)\n # 创建模块实体，遍历 AST 提取函数/类/导入\n```\n\n资料来源：[src/thought/ingest/code/python_extractor.py:50-72]()\n\n### TypeScript 提取器\n\nTypeScript 提取器扩展了 Python 提取器的模式，增加了：\n\n- **可见性修饰符**：从 `accessibility_modifier` 节点提取\n- **接口支持**：处理 `interface_declaration`\n- **类型别名**：处理 `type_alias_declaration`\n- **命名空间**：处理 `namespace_declaration`\n\n```python\n# 继承关系提取\nfor hc in heritage.named_children:\n if hc.type == \"extends_clause\":\n parent = _text(v, source_bytes)\n out_edges.append(CodeEdge(\n source_name=class_name,\n target_name=parent,\n relation_type=\"INHERITS_FROM\",\n ))\n```\n\n资料来源：[src/thought/ingest/code/typescript_extractor.py:60-90]()\n\n### Rust 提取器\n\nRust 提取器处理特有的语言结构：\n\n- **结构体**：从 `struct_item` 节点提取\n- **impl 块**：关联方法与类型\n- **可见性**：从 `visibility` 节点提取（`pub`, `pub(crate)` 等）\n\n```python\nout_entities.append(CodeEntity(\n name=qualified,\n type_=\"method\",\n language=\"rust\",\n attrs={\"impl_type\": type_name}, # 关联 impl 块\n))\n```\n\n资料来源：[src/thought/ingest/code/rust_extractor.py:40-50]()\n\n### 语言支持矩阵\n\n```mermaid\ngraph LR\n A[源代码文件] --> B{语言检测}\n B -->|Python| C[python_extractor]\n B -->|TypeScript| D[typescript_extractor]\n B -->|Rust| E[rust_extractor]\n B -->|Go| F[go_extractor]\n B -->|Java| G[java_extractor]\n B -->|PHP| H[php_extractor]\n \n C --> I[CodeEntity + CodeEdge]\n D --> I\n E --> I\n F --> I\n G --> I\n H --> I\n```\n\n## 调用图构建\n\n调用图是理解代码依赖关系的关键组件。系统通过静态分析构建 CALLS 关系。\n\n### 解析策略\n\ncall_graph.py 实现三层解析策略：\n\n```mermaid\ngraph TD\n A[调用表达式] --> B{方法调用?}\n B -->|是| C[尝试同文件匹配]\n B -->|否| D{有qualifier?}\n \n C --> E[1. 同文件精确匹配]\n D --> F[Qualified 匹配]\n \n E --> G{找到?}\n F --> H[2. Qualified 后缀匹配]\n G -->|否| I[3. 跨文件裸名匹配]\n G -->|是| J[建立 CALLS 边]\n \n H --> K{唯一匹配?}\n I --> L[建立 CALLS 边]\n K -->|是| J\n```\n\n1. **同文件方法调用**：直接通过方法名匹配当前文件的类方法\n2. **唯一 Qualified 后缀匹配**：查找 `ClassName.method` 格式的唯一匹配\n3. **跨文件裸名匹配**：在其他文件中查找同名函数\n\n资料来源：[src/thought/ingest/code/call_graph.py:60-90]()\n\n### 解析示例\n\n```python\n# 解析 obj.method() 调用\ntarget_name = _resolve_method_call(node, source_bytes, file_path, backend, ...)\n# 目标名称可能为:\n# - \"ClassName.method\" (qualified)\n# - \"function_name\" (bare)\n```\n\n## 存储管道\n\n### 实体写入流程\n\n```mermaid\ngraph TD\n A[CodeEntity 列表] --> B[计算规范名称]\n B --> C[upsert_entity]\n C --> D[生成 embedding]\n D --> E[store_embedding]\n \n F[Entity ID 映射] <-- G[name_to_id 字典]\n E --> G\n```\n\n```python\ndef _write_entities(self, entities, scope, owner_id, source_id, commit_sha, language, now):\n eid = self._backend.upsert_entity(\n type_=ent.type_,\n name=ent.name,\n scope=scope,\n valid_from=now,\n code_file=ent.file_path,\n code_language=language,\n code_commit_sha=commit_sha,\n )\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:80-110]()\n\n### 身份去重策略\n\n实体标识包含 `(name, code_file, code_commit_sha)` 三元组，确保同名函数在不同文件或不同提交中不会合并：\n\n```python\n# upsert_entity 身份: (name, code_file, code_commit_sha)\n# 这允许:\n# - auth.py::authenticate (v1.0)\n# - auth.py::authenticate (v2.0) # 视为不同实体\n```\n\n## 代码查询层\n\n### CodeLayer 接口\n\n`CodeLayer` 提供程序员友好的查询接口：\n\n| 方法 | 功能 |\n|------|------|\n| `callers_of(name)` | 谁调用了这个函数？（直接调用者，按 PageRank 排序）|\n| `callees_of(name)` | 这个函数调用了什么？（直接调用，限包内）|\n| `impact_set(name)` | 变更这个的影响范围（传递调用者，PageRank 排序）|\n| `defines_in_file(path)` | 文件中定义的所有实体 |\n\n资料来源：[src/thought/layers/code.py:20-35]()\n\n### Personalized PageRank 查询\n\n系统使用 HippoRAG 风格的双向 PageRank 遍历进行调用者排名：\n\n```python\ndef callers_of(self, name: str) -> list[CodeHit]:\n entity_id = self._resolve_entity_id(name)\n # 执行 PPR 查询，返回按重要性排序的调用者\n```\n\n### 影响集分析\n\n`impact_set` 执行传递闭包查询：\n\n```\n影响集 = 直接调用者 + 间接调用者（递归向上遍历）\n```\n\n这回答了 \"如果我修改这个函数，哪些代码会受影响？\" 的问题。\n\n## 双向时态模型\n\n系统采用 bi-temporal 模型记录实体生命周期：\n\n```mermaid\ngantt\n title 双向时态模型示意\n dateFormat X\n axisFormat %s\n \n section Valid Time\n v1.0 实体存在 :0, 100\n \n section Learned Time\n 被学习 :10, 120\n 被更正 :80, 120\n```\n\n| 时间轴 | 字段 | 语义 |\n|--------|------|------|\n| 有效时间 | `valid_from` / `valid_until` | 事实本身何时为真 |\n| 学习时间 | `learned_at` / `unlearned_at` | 系统何时获知该事实 |\n\n`as_of` 查询可以回溯历史状态：\n\n- `as_of_kind='valid'` → \"日期 X 时什么为真\"\n- `as_of_kind='learned'` → \"系统日期 X 时知道什么\"\n\n## Git 感知摄取\n\n### 快照模式 vs 完整模式\n\n| 模式 | 行为 | 适用场景 |\n|------|------|----------|\n| `snapshot` | 仅摄取 HEAD | 快速初始化 |\n| `full` | 遍历每个提交 | 历史分析、时间旅行查询 |\n\n```python\nGitWalker # 纯子进程实现，无原生依赖\n# 每个实体记录其 commit_sha\n```\n\n### 差异查询\n\n```bash\nthought diff --from --to \n# 输出: 新增实体列表 / 移除实体列表\n```\n\n## 配置与初始化\n\n### 数据库初始化\n\n```bash\nthought init --db-path .thought/thought.db\n# 创建数据库文件 + 配置文件 + CLAUDE.md\n```\n\n### 嵌入器选择\n\n```python\nembedder: str = typer.Option(\n \"auto\", # 自动选择 sentence-transformers 或确定性嵌入\n)\n```\n\n## 扩展阅读\n\n| 功能 | 文档 |\n|------|------|\n| CLI 命令参考 | CHANGELOG.md |\n| 数据库后端 | SQLite 存储层 |\n| 调用图构建 | call_graph.py |\n| 演示用例 | demo.py |\n\n---\n\n\n\n## 记忆模型与检索\n\n### 相关页面\n\n相关主题：[查询系统](#page-query-system), [图形层与图遍历](#page-graph-layer), [实体与关系管理](#page-entity-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/memory.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/memory.py)\n- [src/thought/hooks/recall.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/hooks/recall.py)\n- [src/thought/layers/graph.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/graph.py)\n- [src/thought/layers/vector.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/vector.py)\n- [src/thought/layers/temporal.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/temporal.py)\n- [src/thought/layers/code.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/code.py)\n- [src/thought/ingest/code/pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/pipeline.py)\n- [src/thought/query/ask.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/query/ask.py)\n \n\n# 记忆模型与检索\n\n## 概述\n\nThought-MCP 的**记忆模型与检索系统**是一个双时态（bi-temporal）的知识图谱存储与查询引擎，旨在为 AI 代理提供持久化、可追溯的上下文记忆能力。该系统将实体（Entity）、关系（Edge）和向量嵌入（Embedding）统一存储在 SQLite 数据库中，支持时间旅行查询、自然语言查询和代码语义检索。\n\n核心设计目标：\n\n- **持久化记忆**：让 AI 代理在不同会话之间保留关键上下文\n- **双时态模型**：区分\"何时发生\"（valid_time）和\"何时学习\"（learned_at）\n- **语义检索**：结合向量相似度和图关系的混合检索\n- **代码理解**：支持函数调用图、影响分析和代码追溯\n\n资料来源：[src/thought/memory.py:1-50]()\n\n## 架构概览\n\n```mermaid\ngraph TB\n subgraph \"数据摄取层\"\n CI[代码摄取 Pipeline]\n GI[Git 历史摄取]\n HI[Hook 事件摄取]\n end\n\n subgraph \"存储层\"\n SQ[SQLite Backend]\n EM[Embedding 存储]\n end\n\n subgraph \"查询层\"\n REC[recall 召回]\n ASK[ask 自然语言]\n CODE[code 代码查询]\n GRAPH[graph 图查询]\n end\n\n CI --> SQ\n GI --> SQ\n HI --> SQ\n SQ --> EM\n REC --> EM\n ASK --> GRAPH\n CODE --> GRAPH\n GRAPH --> SQ\n```\n\n### 核心组件关系\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| `Memory` | 顶层 API 聚合器，协调各层 | `memory.py` |\n| `SQLiteBackend` | 数据库 CRUD 操作核心 | `storage/sqlite/backend.py` |\n| `VectorLayer` | 向量嵌入存储与相似度搜索 | `layers/vector.py` |\n| `GraphLayer` | 图关系查询与 PageRank | `layers/graph.py` |\n| `TemporalLayer` | 双时态时间旅行查询 | `layers/temporal.py` |\n| `CodeLayer` | 代码专用查询接口 | `layers/code.py` |\n\n资料来源：[src/thought/memory.py:50-120]()\n\n---\n\n## 双时态数据模型\n\n### 时态维度的定义\n\nThought-MCP 采用**双时态模型**（Bi-temporal Model）来区分事实的两个时间维度：\n\n```mermaid\ngraph LR\n A[事件发生] -->|valid_time| B[事实的有效期]\n C[系统学习] -->|learned_at| D[知识的入库时间]\n```\n\n**两个时间戳字段：**\n\n| 字段 | 含义 | 典型场景 |\n|------|------|----------|\n| `valid_from` / `valid_until` | 事实本身在现实世界的时间范围 | \"2024 年 1 月用户修改了密码\" |\n| `learned_at` | 系统何时将该事实记录到数据库 | \"系统在 2024 年 3 月才导入这条记录\" |\n\n这种设计允许系统回答两类时间查询：\n\n- **`as_of_kind='valid'`**：查询\"在某个时间点，什么是真实的？\"\n- **`as_of_kind='learned'`**：查询\"在某个时间点，系统知道什么？\"\n\n资料来源：[src/thought/layers/temporal.py:1-60]()\n\n### 时间旅行查询示例\n\n```cypher\n-- 查询 2024 年 1 月 1 日系统所知道的所有实体\nMATCH (e:Entity)\nWHERE e.learned_at <= datetime('2024-01-01')\n AND (e.valid_until IS NULL OR e.valid_until > datetime('2024-01-01'))\nRETURN e\nAS_OF '2024-01-01'\n```\n\nCLI 命令行支持时间旅行：\n\n```bash\nthought recall \"用户配置文件\" --as-of 2024-01-01 --as-of-kind learned\n```\n\n资料来源：[src/thought/layers/temporal.py:80-120]()\n\n---\n\n## 实体与关系模型\n\n### Entity 数据结构\n\n```python\n@dataclass\nclass Entity:\n id: str # 实体唯一标识\n type_: str # 实体类型 (function, class, module, fact, claim...)\n name: str # 实体名称\n scope: ScopeName # 作用域 (shared, agent, project)\n owner_id: str | None # 所有者\n valid_from: datetime # 有效起始时间\n valid_until: datetime | None # 有效结束时间\n learned_at: datetime # 入库时间\n source_ref: str | None # 原始来源引用\n tier: str # 热度层级 (hot, warm, cold)\n attrs: dict # 扩展属性 (signature, visibility, line_start...)\n code_file: str | None # 代码文件路径 (代码实体)\n code_language: str | None # 编程语言 (代码实体)\n code_commit_sha: str | None # Git commit SHA (代码实体)\n```\n\n资料来源：[src/thought/memory.py:100-150]()\n\n### Edge 关系类型\n\n| 关系类型 | 含义 | 适用场景 |\n|----------|------|----------|\n| `CALLS` | 函数调用关系 | 代码分析 |\n| `INHERITS_FROM` | 类继承关系 | 代码分析 |\n| `DEFINES` | 定义关系 | 代码分析 |\n| `IMPORTS` | 模块导入关系 | 代码分析 |\n| `CONTRADICTS` | 矛盾关系 | 法律/研究取证 |\n| `SUPPORTS` | 支持关系 | 学术研究 |\n| `RELATED` | 通用关联 | 通用记忆 |\n\n资料来源：[src/thought/ingest/code/typescript_extractor.py:50-100]()\n\n### SQLite 表结构\n\n```sql\nCREATE TABLE entities (\n id TEXT PRIMARY KEY,\n type_ TEXT NOT NULL,\n name TEXT NOT NULL,\n scope TEXT DEFAULT 'shared',\n owner_id TEXT,\n valid_from TIMESTAMP NOT NULL,\n valid_until TIMESTAMP,\n learned_at TIMESTAMP NOT NULL,\n source_ref TEXT,\n tier TEXT DEFAULT 'hot',\n attrs TEXT, -- JSON\n code_file TEXT,\n code_language TEXT,\n code_commit_sha TEXT\n);\n\nCREATE TABLE edges (\n id TEXT PRIMARY KEY,\n source_id TEXT NOT NULL,\n target_id TEXT NOT NULL,\n relation_type TEXT NOT NULL,\n valid_from TIMESTAMP NOT NULL,\n valid_until TIMESTAMP,\n learned_at TIMESTAMP NOT NULL,\n attrs TEXT -- JSON\n);\n\nCREATE TABLE embeddings (\n entity_id TEXT NOT NULL,\n model_name TEXT NOT NULL,\n model_version TEXT,\n dim INTEGER NOT NULL,\n vector BLOB NOT NULL,\n created_at TIMESTAMP NOT NULL,\n FOREIGN KEY (entity_id) REFERENCES entities(id)\n);\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:150-200]()\n\n---\n\n## 向量检索层\n\n### VectorLayer 功能\n\n`VectorLayer` 负责将文本语义转换为向量表示，并支持相似度搜索：\n\n```python\nclass VectorLayer:\n def __init__(self, backend: SQLiteBackend, embedder: Embedder) -> None:\n self._backend = backend\n self._embedder = embedder\n\n def search(\n self,\n query: str,\n *,\n limit: int = 10,\n scope: str = \"all\",\n owner_id: str | None = None,\n ) -> list[VectorHit]:\n \"\"\"语义相似度搜索\"\"\"\n vec = self._embedder.embed(query)\n # 余弦相似度计算\n ...\n```\n\n资料来源：[src/thought/layers/vector.py:20-80]()\n\n### 支持的 Embedder 类型\n\n| Embedder | 描述 | 配置方式 |\n|----------|------|----------|\n| `OllamaEmbedder` | Ollama 原生嵌入 API | `provider = \"ollama\"` |\n| `LMStudioEmbedder` | LM Studio 嵌入 | `provider = \"lmstudio\"` |\n| `OpenAICompatEmbedder` | OpenAI 兼容 API | `provider = \"openai-compat\"` |\n| `DeterministicEmbedder` | 确定性哈希（无外部依赖） | 自动降级 |\n\n资料来源：[src/thought/memory.py:200-250]()\n\n### 嵌入时机\n\n代码实体的嵌入发生在摄取阶段：\n\n```python\n# 在 pipeline.py 的 _write_entities 中\nembed_text_parts = [ent.name, ent.signature]\nif ent.docstring:\n embed_text_parts.append(ent.docstring)\nembed_text = \"\\n\".join(p for p in embed_text_parts if p)\n\nif embed_text.strip():\n vec = self._embedder.embed(embed_text)\n self._backend.store_embedding(\n entity_id=eid,\n model_name=self._embedder.model_name,\n model_version=self._embedder.model_version,\n dim=self._embedder.dim,\n vector=vector_to_bytes(vec),\n )\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:120-150]()\n\n---\n\n## 图查询层\n\n### GraphLayer 功能\n\n`GraphLayer` 提供基于图结构的查询能力，核心是 **Personalized PageRank** 算法：\n\n```python\nclass GraphLayer:\n def __init__(self, backend: SQLiteBackend) -> None:\n self._backend = backend\n\n def personalized_pagerank(\n self,\n seed_ids: list[str],\n *,\n damping: float = 0.85,\n iterations: int = 20,\n convergence: float = 1e-6,\n ) -> dict[str, float]:\n \"\"\"基于种子节点的 PageRank 计算\"\"\"\n ...\n```\n\n资料来源：[src/thought/layers/graph.py:30-80]()\n\n### 典型图查询\n\n#### 直接调用者查询\n\n```python\ndef callers_of(self, name: str, *, limit: int = 10) -> list[CodeHit]:\n \"\"\"查找直接调用某函数的实体，PageRank 加权排序\"\"\"\n seed_ids = self._resolve_entity_id(name)\n if not seed_ids:\n return []\n # 逆向追踪 CALLS 边\n return self._query_callers(seed_ids, limit=limit)\n```\n\n#### 影响分析查询\n\n```python\ndef impact_set(self, name: str, *, limit: int = 50) -> list[CodeHit]:\n \"\"\"传递性调用者集合：修改某函数会影响哪些代码\"\"\"\n seed_ids = self._resolve_entity_id(name)\n if not seed_ids:\n return []\n # 递归追踪所有调用链\n return self._transitive_closure(seed_ids, direction=\"incoming\")\n```\n\n资料来源：[src/thought/layers/code.py:50-120]()\n\n---\n\n## 检索 API\n\n### recall - 语义召回\n\n`recall` 是基础的语义搜索接口：\n\n```python\ndef recall(\n self,\n query: str,\n *,\n max_results: int = 10,\n scope: str = \"all\",\n owner_id: str | None = None,\n since: str | None = None,\n before: str | None = None,\n) -> list[Entity]:\n \"\"\"语义相似度召回\"\"\"\n```\n\n**特点**：\n\n- 默认返回最多 10 条结果\n- 支持时间范围过滤 (`since`, `before`)\n- 支持作用域过滤 (`scope`, `owner_id`)\n- 结合向量相似度和图关系\n\n资料来源：[src/thought/hooks/recall.py:50-100]()\n\n### ask - 自然语言查询\n\n`ask` 将自然语言转换为 Cypher 查询：\n\n```python\ndef ask(\n memory,\n question: str,\n *,\n llm_cfg: object | None = None,\n scope: str = \"all\",\n owner_id: str | None = None,\n no_fallback: bool = False,\n) -> AskResult:\n \"\"\"自然语言 → Cypher 查询\"\"\"\n```\n\n**工作流程**：\n\n```mermaid\ngraph LR\n Q[自然语言问题] --> LLM[LLM 翻译]\n LLM --> C[Cypher 查询]\n C --> V{验证通过?}\n V -->|是| EX[执行查询]\n V -->|否| FB[recall 降级]\n EX --> R[返回结果]\n FB --> R\n```\n\n**约束条件**：\n\n- 仅使用只读 Cypher 特性（MATCH, WHERE, RETURN, LIMIT）\n- 禁止使用 MERGE/CREATE/DELETE/SET\n- 支持 `AS_OF 'iso-date'` 进行时间旅行\n\n资料来源：[src/thought/query/ask.py:30-100]()\n\n### 代码专用查询\n\n`CodeLayer` 提供程序员友好的接口：\n\n| 方法 | 作用 | CLI 命令 |\n|------|------|----------|\n| `callers_of(name)` | 直接调用者 | `thought callers ` |\n| `callees_of(name)` | 直接被调用者 | `thought callees ` |\n| `impact_set(name)` | 传递性影响集合 | `thought impact ` |\n| `defines_in_file(path)` | 文件内定义 | - |\n\n资料来源：[src/thought/layers/code.py:1-50]()\n\n---\n\n## 增量扫描与工作上下文\n\n### agent_scan 增量扫描\n\n`agent_scan` 专为 AI 代理循环设计，支持增量更新：\n\n```python\ndef agent_scan(\n self,\n repo_path: str,\n *,\n agent: str | None = None,\n since: str | None = None,\n max_files: int | None = None,\n language: str | None = None,\n) -> dict:\n \"\"\"增量代码扫描\"\"\"\n # 1. 查找上次扫描的 head_sha 作为 since 起点\n # 2. 获取 Git 差异文件\n # 3. 仅处理变更/新增文件\n # 4. 退休已删除文件的实体\n # 5. 返回扫描报告\n```\n\n**返回值结构**：\n\n```python\n{\n \"scan_id\": \"...\",\n \"files_scanned\": 15,\n \"files_changed\": 3,\n \"entities_added\": 42,\n \"entities_retired\": 5,\n \"edges_added\": 38,\n \"edges_retired\": 2,\n \"duration_ms\": 1234\n}\n```\n\n资料来源：[src/thought/memory.py:150-220]()\n\n### working_context 临时上下文\n\n`working_context` 管理会话内的临时上下文：\n\n```python\ndef working_context(\n self,\n action: Literal[\"push\", \"pop\", \"peek\", \"list\"],\n *,\n text: str | None = None,\n scope: str = \"shared\",\n) -> list[str]:\n \"\"\"LIFO 栈式上下文管理\"\"\"\n```\n\n- `push`：添加上下文片段到栈顶\n- `pop`：移除并返回栈顶\n- `peek`：查看栈顶（不移除）\n- `list`：列出所有上下文\n\n资料来源：[src/thought/memory.py:220-280]()\n\n---\n\n## Git 历史感知\n\n### 快照模式 vs 完整模式\n\n```mermaid\ngraph TB\n subgraph \"snapshot 模式 (默认)\"\n F1[HEAD commit]\n F1 --> E1[实体 + HEAD SHA]\n end\n\n subgraph \"full 模式\"\n F2[所有 commits]\n F2 --> E2[每个实体 + 对应 commit SHA]\n end\n```\n\n| 模式 | 速度 | 查询能力 |\n|------|------|----------|\n| `--mode snapshot` | 快，仅 HEAD | 仅当前代码 |\n| `--mode full` | 慢，遍历全部 | 支持历史时间旅行 |\n\n资料来源：[src/thought/ingest/code/git_pipeline.py:50-100]()\n\n### 差异查询\n\n```bash\n# 对比两个 commit 之间的代码变更\nthought diff --from abc123 --to def456\n\n# 输出\n# ADDED: Entity[Foo] in bar.py\n# REMOVED: Entity[Baz] in qux.py\n```\n\n资料来源：[src/thought/ingest/code/git_pipeline.py:100-150]()\n\n---\n\n## 配置与初始化\n\n### 初始化命令\n\n```bash\nthought init --db-path .thought/thought.db --embedder auto\n```\n\n**参数说明**：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--db-path` | `.thought/thought.db` | SQLite 数据库路径 |\n| `--embedder` | `auto` | 嵌入模型选择 |\n| `--write-claude-md` | `true` | 生成 CLAUDE.md |\n| `--quick` | `false` | 跳过嵌入模型预热 |\n\n### 自动备份\n\n所有破坏性操作（flush, load）前自动备份：\n\n```\n.bak.\n```\n\n资料来源：[src/thought/cli.py:100-150]()\n\n---\n\n## 总结\n\nThought-MCP 的记忆模型与检索系统通过以下设计实现持久化 AI 记忆：\n\n1. **双时态模型**：区分事实有效期与知识入库时间，支持精确的时间旅行查询\n2. **混合存储**：结合 SQLite 图关系与向量嵌入，兼顾结构化查询与语义搜索\n3. **分层 API**：recall（语义）、ask（自然语言）、code（代码专用）满足不同场景\n4. **增量感知**：agent_scan + Git 差异追踪实现高效的增量更新\n5. **影响分析**：PageRank 加权的传递闭包计算，精确回答\"改这个会影响什么\"\n\n这套系统使 AI 代理能够在多会话环境中保持上下文连续性，同时支持深度的代码理解和追溯分析。\n\n---\n\n\n\n## 查询系统\n\n### 相关页面\n\n相关主题：[记忆模型与检索](#page-memory-model), [图形层与图遍历](#page-graph-layer)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/query/cypher.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/query/cypher.py)\n- [src/thought/query/ask.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/query/ask.py)\n- [src/thought/query/views.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/query/views.py)\n- [src/thought/router/classifier.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/router/classifier.py)\n- [src/thought/router/rules.yaml](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/router/rules.yaml)\n \n\n# 查询系统\n\n## 概述\n\n查询系统（Query System）是 thought-mcp 的核心组件之一，负责将用户的自然语言查询转换为知识图谱查询并返回结果。该系统支持多种查询类型，包括直接记忆检索（recall）、自然语言到 Cypher 查询的翻译（ask）、代码图谱查询（callers/callees/impact）等场景。\n\n查询系统的设计目标是为用户提供透明的查询接口，无需了解底层图数据库的查询语言即可完成复杂的信息检索任务。系统采用分层架构，通过路由器（Router）进行意图分类，再交由对应的查询处理器执行。\n\n资料来源：[src/thought/query/ask.py:1-15]()\n\n## 架构设计\n\n### 系统分层\n\n查询系统采用三层架构设计：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 路由层 | Router / Classifier | 解析用户意图，分类查询类型 |\n| 转换层 | Ask / Cypher | 自然语言转 Cypher，查询验证 |\n| 执行层 | Backend / Storage | 执行查询，返回结果 |\n\n```mermaid\ngraph TD\n A[用户自然语言查询] --> B[Router 意图分类]\n B --> C{查询类型}\n C -->|RECALL| D[recall 直接检索]\n C -->|CODE| E[CodeLayer 代码图谱]\n C -->|ASK| F[Ask 自然语言→Cypher]\n C -->|HYBRID| G[组合查询]\n D --> H[Backend 执行]\n E --> H\n F --> I[Cypher 验证]\n I --> H\n H --> J[返回结果]\n```\n\n资料来源：[src/thought/query/ask.py:1-15]()\n资料来源：[src/thought/router/classifier.py]()\n\n### 核心模块\n\n| 模块 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| `ask` | `src/thought/query/ask.py` | 自然语言到 Cypher 查询的翻译与执行 |\n| `cypher` | `src/thought/query/cypher.py` | Cypher 查询构建器与执行器 |\n| `views` | `src/thought/query/views.py` | 查询视图定义与数据结构 |\n| `classifier` | `src/thought/router/classifier.py` | 查询意图分类器 |\n\n资料来源：[src/thought/query/ask.py]()\n资料来源：[src/thought/query/cypher.py]()\n资料来源：[src/thought/query/views.py]()\n\n## 自然语言查询转换（Ask 模块）\n\n### Ask 模块工作流程\n\nAsk 模块是查询系统中最复杂的组件，它将自然语言问题转换为 Cypher 查询语句。其核心流程包括：\n\n1. 获取当前知识图谱的 schema 信息\n2. 构建包含约束的提示词（prompt）\n3. 调用 LLM 进行翻译\n4. 验证 Cypher 查询语法\n5. 执行查询或降级到 recall\n\n```mermaid\ngraph LR\n A[用户问题] --> B{配置了 LLM?}\n B -->|否| C[recall 降级]\n B -->|是| D[构建提示词]\n D --> E[LLM 翻译]\n E --> F{翻译成功?}\n F -->|否| C\n F -->|是| G[Cypher 验证]\n G --> H{验证通过?}\n H -->|否| C\n H -->|是| I[执行查询]\n I --> J[返回结果]\n```\n\n资料来源：[src/thought/query/ask.py:48-78]()\n\n### AskResult 数据结构\n\n```python\n@dataclass\nclass AskResult:\n cypher: str | None # 生成的 Cypher 查询\n sql: str | None # 备用的 SQL 查询\n rows: list[dict[str, Any]] | None # 查询结果行\n fallback_used: bool # 是否使用了降级策略\n fallback_reason: str | None # 降级原因\n error: str | None # 错误信息\n```\n\n资料来源：[src/thought/query/ask.py:30-37]()\n\n### Cypher 翻译约束\n\n系统对生成的 Cypher 查询有严格的约束限制：\n\n| 约束类型 | 说明 |\n|----------|------|\n| 读写限制 | 只允许使用只读操作（`MATCH`, `WHERE`, `RETURN`, `LIMIT`, `AS_OF`） |\n| 禁用操作 | 禁止使用 `MERGE`, `CREATE`, `DELETE`, `SET`, `WITH` |\n| 路径限制 | 不支持可变长度路径 |\n| Schema 限制 | 必须使用 Schema 中定义的有效实体类型和关系类型 |\n\n资料来源：[src/thought/query/ask.py:17-27]()\n\n### 提示词模板\n\nAsk 模块使用结构化的提示词模板来引导 LLM 生成正确的 Cypher 查询：\n\n```cypher\nYou translate English questions into Cypher queries against a memory database.\n\nCONSTRAINTS (any violation will be rejected):\n- Output a single Cypher query, no explanations, no markdown fences.\n- Use ONLY these read-only Cypher features:\n MATCH (var:Type {{prop:value}}) (-[:RELATION]-> (var:Type))? ...\n WHERE expr (AND expr)* using = <> < > <= >= CONTAINS \"STARTS WITH\" IN\n RETURN identlist\n LIMIT N (optional)\n AS_OF 'iso-date' (optional, for time-travel queries)\n- Use ONLY entity types and relation types from the SCHEMA below.\n- Never use MERGE / CREATE / DELETE / SET / WITH / variable-length paths.\n\nSCHEMA:\n entity types: {entity_types}\n relation types: {relation_types}\n\nQUESTION: {question}\n\nCYPHER:\n```\n\n资料来源：[src/thought/query/ask.py:16-38]()\n\n### 降级策略\n\n当 LLM 翻译失败或未配置 LLM 提供者时，系统会自动降级到 `recall` 函数执行简单的向量检索：\n\n```python\ndef ask(\n memory,\n question: str,\n *,\n llm_cfg: object | None = None,\n scope: str = \"all\",\n owner_id: str | None = None,\n no_fallback: bool = False,\n) -> AskResult:\n provider = getattr(llm_cfg, \"provider\", None) or \"none\"\n \n if provider == \"none\":\n if no_fallback:\n return AskResult(error=\"thought ask requires [llm] provider...\")\n rows = _recall_fallback(memory, question, scope=scope, owner_id=owner_id)\n return AskResult(fallback_used=True, fallback_reason=\"no LLM provider configured\")\n```\n\n资料来源：[src/thought/query/ask.py:40-60]()\n\n## 路由分类系统\n\n### 查询类型分类\n\n路由器根据用户输入的关键词和模式匹配将查询分为以下类型：\n\n| 查询类型 | 触发条件 | 处理模块 |\n|----------|----------|----------|\n| `RECALL` | 一般自然语言问题 | recall 向量检索 |\n| `CODE` | 包含代码关键词 | CodeLayer 代码分析 |\n| `CHANGE` | 涉及变更历史 | Git 历史查询 |\n| `HYBRID` | CODE + CHANGE 组合 | 组合处理 |\n| `ASK` | 需要结构化查询 | Ask Cypher 翻译 |\n\n资料来源：[src/thought/router/classifier.py]()\n资料来源：[src/thought/router/rules.yaml]()\n\n### CODE 类型识别\n\nCODE 查询类型的识别基于以下特征：\n\n| 特征类型 | 关键词示例 | 识别方式 |\n|----------|------------|----------|\n| 编程关键字 | `function`, `class`, `method`, `interface` | 精确匹配 |\n| 代码操作 | `caller`, `callee`, `impact`, `imports` | 精确匹配 |\n| 文件扩展名 | `.py`, `.ts`, `.js`, `.rs`, `.php` | 扩展名检测 |\n| 标识符模式 | `camelCase`, `snake_case` | 正则匹配 |\n| 版本引用 | `since v1.0`, `before this commit` | 模式匹配 |\n\n资料来源：[src/thought/router/classifier.py]()\n\n### 自然语言调用\n\n系统支持通过自然语言触发代码图谱查询，例如：\n\n| 自然语言 | 解析结果 |\n|----------|----------|\n| `\"who calls authenticate_user\"` | 调用者查询 |\n| `\"what does login do\"` | 被调用者查询 |\n| `\"impact of password_reset\"` | 影响分析 |\n\n资料来源：[src/thought/query/ask.py]()\n资料来源：[src/thought/router/classifier.py]()\n\n## 代码图谱查询（CodeLayer）\n\n### 功能概述\n\nCodeLayer 是代码垂直领域的专用查询接口，提供面向程序员的自然词汇操作：\n\n| 操作 | 方法名 | 说明 |\n|------|--------|------|\n| 调用者查询 | `callers_of(name)` | 谁调用了这个函数（按 PageRank 排序） |\n| 被调用查询 | `callees_of(name)` | 这个函数调用了什么（包内） |\n| 影响分析 | `impact_set(name)` | 传递性调用者集合 |\n| 文件定义 | `defines_in_file(path)` | 查找文件中定义的所有实体 |\n\n资料来源：[src/thought/layers/code.py:1-25]()\n\n### 实体解析策略\n\n调用图构建时，实体解析按以下优先级进行：\n\n```mermaid\ngraph TD\n A[解析函数调用] --> B{同文件唯一匹配?}\n B -->|是| C[直接使用]\n B -->|否| D{唯一 qualified 后缀匹配?}\n D -->|是| C\n D -->|否| E{跨文件 bare-name 匹配?}\n E -->|是| C\n E -->|否| F[创建 Stub]\n```\n\n解析优先级：\n1. 同文件唯一匹配\n2. 唯一 qualified 后缀匹配（如 `obj.method()` → `ClassName.method`）\n3. 跨文件 bare-name 匹配（顶级函数）\n\n资料来源：[src/thought/ingest/code/call_graph.py]()\n资料来源：[src/thought/ingest/code/pipeline.py]()\n\n## 查询视图与数据结构\n\n### 视图模块\n\n`views.py` 定义了查询返回的标准化数据结构，确保不同查询类型的返回格式一致：\n\n| 视图类型 | 用途 |\n|----------|------|\n| RecallResult | 向量检索结果 |\n| AskResult | Cypher 查询结果 |\n| CodeResult | 代码图谱查询结果 |\n\n资料来源：[src/thought/query/views.py]()\n\n### 实体模型\n\n```python\nclass Entity(BaseModel):\n id: str\n type: str\n name: str\n canonical_name: str\n owner_id: str | None\n scope: ScopeName\n tier: Tier\n importance: float # 0.0 - 1.0\n valid_from: datetime\n valid_until: datetime | None # None = 当前有效\n learned_at: datetime\n unlearned_at: datetime | None\n created_at: datetime\n last_accessed_at: datetime\n access_count: int\n attrs: dict[str, object]\n```\n\n资料来源：[src/thought/models.py]()\n\n## 配置与集成\n\n### LLM 提供者配置\n\n查询系统支持多种 LLM 提供者：\n\n| 提供者 | 配置值 | 说明 |\n|--------|--------|------|\n| Anthropic | `anthropic` | Claude 系列模型 |\n| Ollama | `ollama` | 本地 Ollama 服务 |\n| LM Studio | `lmstudio` | LM Studio 本地服务 |\n| OpenAI 兼容 | `openai-compat` | 通用 OpenAI 兼容接口 |\n\n配置方式：通过 `thought.toml` 中的 `[llm] provider` 字段指定。\n\n资料来源：[src/thought/query/ask.py:48-55]()\n\n### CLI 命令集成\n\n| 命令 | 查询类型 | 功能 |\n|------|----------|------|\n| `thought recall ` | RECALL | 记忆检索 |\n| `thought ask ` | ASK | 自然语言查询 |\n| `thought callers ` | CODE | 调用者分析 |\n| `thought impact ` | CODE | 影响分析 |\n| `thought diff --from --to ` | CHANGE | 变更对比 |\n\n资料来源：[src/thought/cli.py]()\n资料来源：[src/thought/layers/code.py]()\n\n## 时间旅行查询\n\n### 双时间模型\n\n系统支持双时间（bi-temporal）查询模型：\n\n| 时间维度 | 说明 | 查询参数 |\n|----------|------|----------|\n| `valid_from/valid_until` | 事实的有效期 | `as_of_kind='valid'` |\n| `learned_at/unlearned_at` | 系统认识该事实的时间 | `as_of_kind='learned'` |\n\n```cypher\nMATCH (e:Entity)\nWHERE e.valid_from <= '2024-01-01' \n AND (e.valid_until IS NULL OR e.valid_until > '2024-01-01')\nRETURN e\n```\n\n### 使用场景\n\n| 场景 | 查询方式 |\n|------|----------|\n| 查询某日期的事实状态 | `as_of='date'` + `as_of_kind='valid'` |\n| 查询系统当时的认知 | `as_of='date'` + `as_of_kind='learned'` |\n| 事实纠正追踪 | 比较 `valid` 和 `learned` 时间差异 |\n\n资料来源：[src/thought/query/cypher.py]()\n资料来源：[src/thought/cli.py]()\n\n## 错误处理与降级\n\n### 错误处理策略\n\n| 错误类型 | 处理方式 | 降级目标 |\n|----------|----------|----------|\n| LLM 提供者未配置 | 自动降级 | `recall` 向量检索 |\n| LLM 调用失败 | 自动降级 | `recall` 向量检索 |\n| Cypher 翻译错误 | 自动降级 | `recall` 向量检索 |\n| Cypher 验证失败 | 自动降级 | `recall` 向量检索 |\n| 查询执行失败 | 返回错误 | - |\n\n### 强制模式\n\n当需要精确结果而不接受降级时，可使用 `no_fallback=True` 参数：\n\n```python\nresult = ask(memory, question, no_fallback=True)\nif result.error:\n # 处理错误，不使用降级\n handle_error(result.error)\n```\n\n资料来源：[src/thought/query/ask.py:60-78]()\n\n## 最佳实践\n\n### 查询优化建议\n\n| 建议 | 说明 |\n|------|------|\n| 使用具体标识符 | 提供函数全名或类名可提高解析准确性 |\n| 限制时间范围 | 使用 `as_of` 参数减少查询范围 |\n| 利用 scope 过滤 | 适当使用 `scope='private'` 或 `scope='shared'` |\n| 组合查询 | CODE + CHANGE 组合使用 HyBRID 类型 |\n\n### 调试技巧\n\n| 问题 | 调试方法 |\n|------|----------|\n| 翻译结果不准确 | 检查 schema 中实体类型是否完整 |\n| 解析失败 | 验证函数名符合标识符模式 |\n| 性能问题 | 使用 `db size` 检查索引状态 |\n\n## 相关文档\n\n- [CLI 命令参考](../cli/commands.md) - 所有查询相关命令详解\n- [存储后端](../storage/backend.md) - 查询执行底层实现\n- [摄取管道](../ingest/pipeline.md) - 数据如何进入知识图谱\n- [路由器设计](../router/design.md) - 查询分类内部机制\n\n---\n\n\n\n## 图形层与图遍历\n\n### 相关页面\n\n相关主题：[记忆模型与检索](#page-memory-model), [查询系统](#page-query-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/layers/graph.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/graph.py)\n- [src/thought/layers/code.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/code.py)\n \n\n# 图形层与图遍历\n\n## 概述\n\n图形层（Graph Layer）是 THOUGHT 项目的核心组件之一，负责对知识库中的实体和关系进行图查询操作。它封装了底层的 SQLite 存储后端，提供面向程序员的图遍历接口，支持调用链分析、影响范围计算和代码结构查询等高级功能。\n\n图形层的设计目标是实现**语义感知的代码导航**：用户可以通过函数名、类名等标识符快速定位代码实体，分析代码间的调用关系和依赖关系，从而支持代码审查、影响分析和重构决策等场景。\n\n## 架构设计\n\n### 模块层次结构\n\n```\n┌─────────────────────────────────────┐\n│ CLI / API 层 │\n├─────────────────────────────────────┤\n│ CodeLayer (代码层) │\n│ - callers_of() │\n│ - callees_of() │\n│ - impact_set() │\n│ - defines_in_file() │\n├─────────────────────────────────────┤\n│ GraphLayer (图形层) │\n│ - 图遍历核心逻辑 │\n│ - PageRank 排序 │\n├─────────────────────────────────────┤\n│ SQLiteBackend (存储后端) │\n│ - 实体存储 │\n│ - 关系存储 │\n│ - 嵌入向量存储 │\n└─────────────────────────────────────┘\n```\n\nCodeLayer 是 GraphLayer 的上层封装，专门针对代码场景优化。GraphLayer 负责底层的图遍历实现，支持多种查询模式和排序策略。\n\n资料来源：[src/thought/layers/code.py:24-27]()\n\n### 数据模型\n\n图形层操作的核心数据模型包括：\n\n| 模型 | 说明 |\n|------|------|\n| `Entity` | 实体节点，代表代码中的函数、类、模块等 |\n| `CodeHit` | 查询结果，包含实体和相关性评分 |\n| `ScopeFilter` | 作用域过滤器，用于限定查询范围 |\n\n```python\n@dataclass(frozen=True)\nclass CodeHit:\n entity: Entity\n score: float\n```\n\n`CodeHit` 用于返回按 PageRank 评分排序的查询结果，支持 \"who calls X\" 等排名查询场景。\n\n资料来源：[src/thought/layers/code.py:21-23]()\n\n## 核心功能\n\n### 调用者查询 (callers_of)\n\n`callers_of` 方法返回直接调用指定函数的实体列表，结果按 PageRank 评分降序排列。\n\n```python\ndef callers_of(name: str, *, ...) -> list[CodeHit]\n```\n\n**使用场景**：\n\n- 分析某个函数被哪些模块调用\n- 识别关键函数的依赖方\n- 评估代码变更的影响范围\n\n该方法通过双向 PageRank 遍历（HippoRAG 风格）实现，能够发现直接和间接的调用关系。\n\n### 被调用者查询 (callees_of)\n\n`callees_of` 方法返回指定函数直接调用的其他实体列表。\n\n```python\ndef callees_of(name: str, *, ...) -> list[CodeHit]\n```\n\n**使用场景**：\n\n- 分析函数的依赖项\n- 理解函数的实现逻辑\n- 准备代码重构的影响评估\n\n### 影响集计算 (impact_set)\n\n`impact_set` 是最强大的图查询方法，计算指定实体的**传递影响集**：即所有可能受到该实体变更影响的实体集合。\n\n```python\ndef impact_set(name: str, *, ...) -> list[CodeHit]\n```\n\n该方法基于传递闭包算法，遍历指定实体的所有传递调用者路径，返回完整的受影响实体列表。\n\n### 文件内定义查询 (defines_in_file)\n\n`defines_in_file` 返回指定文件中定义的所有实体。\n\n```python\ndef defines_in_file(path: str, ...) -> list[CodeHit]\n```\n\n**返回内容**：\n\n- 文件中的所有函数定义\n- 文件中的所有类定义\n- 文件中的所有模块级实体\n\n## 图遍历实现\n\n### 实体解析机制\n\n图形层通过多层匹配策略解析实体名称：\n\n1. **精确匹配** - 按完全限定名查找\n2. **包内匹配** - 在同一作用域内查找\n3. **唯一后缀匹配** - 查找唯一的 `ClassName.method` 形式\n4. **跨文件匹配** - 查找其他文件中同名的顶级函数\n\n资料来源：[src/thought/ingest/code/call_graph.py:1-40]()\n\n### 作用域过滤\n\n实体查询支持细粒度的作用域控制：\n\n```python\n@dataclass\nclass ScopeFilter:\n scope: ScopeName\n owner_id: str | None\n code_file: str | None\n code_commit_sha: str | None\n```\n\n| 过滤条件 | 用途 |\n|----------|------|\n| `scope` | 多租户隔离，默认为 \"shared\" |\n| `owner_id` | 用户级隔离 |\n| `code_file` | 文件级隔离 |\n| `code_commit_sha` | Git 版本隔离 |\n\n### 双时态查询支持\n\n图形层支持双时态查询，能够查询知识库在特定时间点的状态：\n\n- `valid_from` / `valid_until` - 实体有效时间窗口\n- `as_of_kind='valid'` - 查询历史上某时刻的事实\n- `as_of_kind='learned'` - 查询系统在某时刻的知识状态\n\n资料来源：[src/thought/cli.py:1-50]()\n\n## 与其他模块的集成\n\n### 代码提取器集成\n\n图形层与代码提取器（Code Extractor）紧密配合：\n\n```\n代码文件 → 语言提取器 → CodeEntity/CodeEdge → SQLiteBackend → GraphLayer\n```\n\n| 提取器 | 支持语言 |\n|--------|----------|\n| `python_extractor` | Python |\n| `typescript_extractor` | TypeScript/JavaScript |\n| `rust_extractor` | Rust |\n| `go_extractor` | Go |\n| `java_extractor` | Java |\n| `php_extractor` | PHP |\n\n每个提取器生成 `CodeEntity` 和 `CodeEdge`，存储到后端后可通过图形层查询。\n\n资料来源：[src/thought/ingest/code/ast_extractor.py:1-50]()\n\n### 存储后端集成\n\nGraphLayer 依赖 `SQLiteBackend` 提供数据访问：\n\n```python\nclass CodeLayer:\n def __init__(self, backend: SQLiteBackend) -> None:\n self._backend = backend\n self._graph = GraphLayer(backend)\n```\n\n存储后端管理实体、关系和嵌入向量的持久化，图形层在此基础上实现图遍历算法。\n\n## 查询流程图\n\n```mermaid\ngraph TD\n A[CLI 命令] --> B[CodeLayer 方法]\n B --> C{查询类型}\n C -->|callers| D[GraphLayer 遍历调用者]\n C -->|callees| E[GraphLayer 遍历被调用者]\n C -->|impact| F[GraphLayer 计算传递闭包]\n C -->|defines| G[GraphLayer 查询文件内实体]\n D --> H[应用 PageRank 排序]\n E --> H\n F --> H\n G --> H\n H --> I[返回 CodeHit 列表]\n```\n\n## CLI 命令接口\n\n图形层功能通过 CLI 命令暴露：\n\n| 命令 | 功能 |\n|------|------|\n| `thought callers ` | 查询调用者，PageRank 排名 |\n| `thought impact ` | 计算传递影响集 |\n| `thought defines ` | 查询文件内定义 |\n\n## 配置与扩展\n\n### 嵌入模型配置\n\n图形层使用嵌入模型为实体生成语义向量，支持配置：\n\n| 选项 | 说明 |\n|------|------|\n| `auto` | 自动选择 sentence-transformers 或确定性嵌入器 |\n| `sentence-transformers` | 使用预训练模型 |\n| `deterministic` | 使用确定性哈希（无需外部依赖） |\n\n### 图查询性能优化\n\n- **部分索引** - `code_file`、`code_commit_sha` 等字段建立部分索引\n- **身份唯一性** - 实体唯一性包含 `(code_file, code_commit_sha)`\n- **批量写入** - 单个文件的所有写入在同一事务内完成\n\n## 总结\n\n图形层是 THOUGHT 项目实现代码智能导航的核心基础设施。它通过封装 GraphLayer 提供语义感知的图遍历能力，支持调用链分析、影响范围计算等高级功能。与代码提取器和存储后端的紧密集成，使得用户能够对代码库进行深度的结构化分析和探索。\n\n---\n\n\n\n## Agent集成与适配器\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [配置管理](#page-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/adapters/claude_sdk.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/adapters/claude_sdk.py)\n- [src/thought/hooks/install.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/hooks/install.py)\n- [src/thought/demo.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/demo.py)\n- [src/thought/cli.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/cli.py)\n- [src/thought/ingest/code/pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/pipeline.py)\n \n\n# Agent集成与适配器\n\nthought-mcp 提供了完整的 Agent 集成层，使 AI Agent 能够将项目知识库（Knowledge Base, KB）作为持久化记忆系统使用。该集成层包含两个核心组件：**Claude SDK 适配器**和**Claude Code Hook 系统**。\n\n## 1. 系统概述\n\nAgent 集成模块让 AI Agent 在执行任务时能够：\n\n- 检索与当前任务相关的上下文知识\n- 将学习到的新知识持久化到知识库\n- 增量扫描代码仓库以更新实体信息\n- 通过钩子机制在交互会话的各个阶段自动触发记忆操作\n\n这种设计使 Agent 具备长期记忆能力，避免每次会话都需要重新加载上下文信息。\n\n## 2. Claude SDK 适配器\n\n### 2.1 核心类：ThoughtMemoryProvider\n\n`ThoughtMemoryProvider` 是专为 Claude Agent SDK 设计的即插即用记忆适配器，位于 `src/thought/adapters/claude_sdk.py`。\n\n资料来源：[src/thought/adapters/claude_sdk.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/adapters/claude_sdk.py)\n\n该类实现了四个核心方法，完整覆盖 Agent 工作循环：\n\n| 方法名 | 功能描述 | 返回值 |\n|--------|----------|--------|\n| `context_for(target, role)` | 获取指定角色和目标的工作上下文字典 | `dict` |\n| `render_context(target)` | 生成纯文本形式的系统提示增强内容 | `str` |\n| `record(content)` | 将 Agent 学到的知识持久化到知识库 | 无 |\n| `scan(repo_path)` | 对仓库进行增量扫描，更新实体信息 | 无 |\n\n### 2.2 工作流程\n\n```mermaid\ngraph TD\n A[Agent 启动] --> B{选择集成方式}\n B --> C[context_for
获取工作上下文]\n B --> D[render_context
生成提示增强]\n C --> E[Agent 执行任务]\n D --> E\n E --> F[record
持久化新知识]\n E --> G[scan
增量扫描代码]\n F --> H[知识库更新]\n G --> H\n```\n\n### 2.3 使用场景\n\n在 `src/thought/demo.py` 中，Code 受众场景演示了 Agent 身份注册和工作上下文获取的完整流程：\n\n资料来源：[src/thought/demo.py:28-32](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/demo.py#L28-L32)\n\n```python\naudiences = {\n \"code\": Agent/developer flow — the 14-stage code-vertical\n walkthrough including agent identity, thought scan,\n working_context, 4 new-language extractors, and the\n Claude Agent SDK adapter.\n}\n```\n\n### 2.4 上下文检索机制\n\n`context_for` 方法根据传入的 `target`（目标实体）和 `role`（角色）返回经过筛选的上下文信息。上下文内容来源于知识库的嵌入向量搜索，确保返回的信息与当前任务高度相关。\n\n## 3. Claude Code Hook 系统\n\nHook 系统通过事件钩子实现 Claude Code 编辑器与 thought-mcp 的深度集成。\n\n资料来源：[src/thought/hooks/install.py:20-27](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/hooks/install.py#L20-L27)\n\n### 3.1 钩子类型与触发时机\n\n| 钩子类型 | Claude Code 事件 | 触发命令 | 用途 |\n|----------|------------------|----------|------|\n| `recall` | `UserPromptSubmit` | `thought hook recall` | 用户提交提示时检索相关记忆 |\n| `write` | `Stop` | `thought hook write` | 会话结束时保存学习到的知识 |\n| `context` | `SessionStart` | `thought hook context` | 会话启动时加载上下文 |\n\n### 3.2 安装机制\n\nHook 安装器 (`src/thought/hooks/install.py`) 采用幂等设计，通过修改 `.claude/settings.json` 文件注册钩子：\n\n资料来源：[src/thought/hooks/install.py:1-20](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/hooks/install.py#L1-L20)\n\n```python\n_HOOK_SPEC: dict[HookKind, tuple[str, str]] = {\n \"recall\": (\"UserPromptSubmit\", \"thought hook recall\"),\n \"write\": (\"Stop\", \"thought hook write\"),\n \"context\": (\"SessionStart\", \"thought hook context\"),\n}\n```\n\n#### 安装结果状态\n\n| 状态值 | 含义 |\n|--------|------|\n| `installed` | 首次安装成功 |\n| `already_present` | 钩子已存在，无需重复安装 |\n| `error` | 安装过程出错 |\n\n### 3.3 幂等性保障\n\n安装器在写入配置文件前会自动备份原始文件：\n\n```mermaid\ngraph LR\n A[读取 settings.json] --> B{检查钩子存在}\n B -->|不存在| C[备份为 .bak 文件]\n C --> D[合并钩子配置]\n D --> E[写入 settings.json]\n B -->|已存在| F[返回 already_present]\n```\n\n备份文件命名为 `.thought.bak`，确保配置修改可回滚。\n\n### 3.4 作用域支持\n\n支持两种安装作用域：\n\n- **项目级 (`project`)**：安装到 `.claude/settings.json`，随仓库共享\n- **用户级 (`user`)**：安装到用户主目录，跨项目生效\n\n资料来源：[src/thought/hooks/install.py:34-39](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/hooks/install.py#L34-L39)\n\n## 4. 集成架构图\n\n```mermaid\ngraph TD\n subgraph Claude_Code\n A[用户提示] --> B[UserPromptSubmit 事件]\n A --> C[SessionStart 事件]\n A --> D[Stop 事件]\n end\n\n subgraph Hook_System\n B --> E[recall 钩子]\n C --> F[context 钩子]\n D --> G[write 钩子]\n end\n\n subgraph Thought_KB\n H[SQLite 数据库]\n I[嵌入向量存储]\n J[实体/边图结构]\n end\n\n E --> H\n F --> H\n G --> H\n H --> I\n H --> J\n\n subgraph Agent_SDK\n K[ThoughtMemoryProvider]\n K --> H\n K --> L[Agent 上下文]\n end\n```\n\n## 5. 代码管道集成\n\nAgent 集成与代码摄取管道紧密配合。当 Agent 通过 `scan()` 方法触发增量扫描时，后端调用 `CodePipeline` 进行代码解析：\n\n资料来源：[src/thought/ingest/code/pipeline.py:60-80](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/pipeline.py#L60-L80)\n\n### 5.1 增量扫描流程\n\n```mermaid\ngraph TD\n A[scan(repo_path)] --> B[遍历代码文件]\n B --> C{检测语言}\n C --> D[Python Extractor]\n C --> E[TypeScript Extractor]\n C --> F[Go Extractor]\n C --> G[Rust Extractor]\n C --> H[Java Extractor]\n C --> I[PHP Extractor]\n D --> J[提取实体与边]\n E --> J\n F --> J\n G --> J\n H --> J\n I --> J\n J --> K[Upsert 到知识库]\n K --> L[存储嵌入向量]\n```\n\n### 5.2 支持的语言\n\n系统通过 `ast_extractor.py` 的注册机制支持以下语言：\n\n资料来源：[src/thought/ingest/code/ast_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/ast_extractor.py)\n\n| 语言 | 提取器模块 | 实体类型 |\n|------|------------|----------|\n| Python | `python_extractor` | module, class, function, method |\n| TypeScript | `typescript_extractor` | module, class, function, method |\n| Go | `go_extractor` | module, function, method |\n| Rust | `rust_extractor` | module, function, impl method |\n| Java | `java_extractor` | class, method |\n| PHP | `php_extractor` | class, method |\n\n## 6. 初始化与配置\n\n在 CLI 初始化命令中，系统提供了 Agent 集成的自动配置选项：\n\n资料来源：[src/thought/cli.py:45-60](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/cli.py#L45-L60)\n\n```python\n@app.command()\ndef init(\n config: Path = typer.Option(\"thought.toml\"),\n db_path: str = typer.Option(\".thought/thought.db\"),\n embedder: str = typer.Option(\"auto\"),\n write_claude_md: bool = typer.Option(\n True, \"--write-claude-md/--no-claude-md\",\n help=\"Drop a CLAUDE.md so MCP clients learn how to use the tool.\"\n ),\n quick: bool = typer.Option(False, \"--quick\"),\n) -> None:\n```\n\n### 配置参数说明\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `config` | `thought.toml` | 配置文件路径 |\n| `db_path` | `.thought/thought.db` | SQLite 数据库路径 |\n| `embedder` | `auto` | 向量化模型选择 |\n| `write_claude_md` | `True` | 自动生成 MCP 客户端使用文档 |\n| `quick` | `False` | 跳过首次嵌入器预热 |\n\n## 7. 最佳实践\n\n### 7.1 集成检查清单\n\n- [ ] 使用 `thought init` 完成基础配置\n- [ ] 通过 `thought hooks install` 注册 Claude Code 钩子\n- [ ] 在 Agent 启动时调用 `context_for()` 加载工作上下文\n- [ ] 任务完成后调用 `record()` 保存新知识\n- [ ] 代码变更后调用 `scan()` 更新实体索引\n\n### 7.2 注意事项\n\n1. **幂等性**：Hook 安装器支持重复运行，不会产生重复配置\n2. **备份机制**：配置修改前自动备份，确保可回滚\n3. **作用域选择**：建议使用项目级作用域 (`project`) 以便团队共享\n4. **嵌入优化**：首次初始化会预热嵌入模型，可使用 `--quick` 跳过\n\n## 8. 相关命令\n\n| 命令 | 功能 |\n|------|------|\n| `thought init` | 初始化数据库和配置文件 |\n| `thought hooks install` | 安装 Claude Code 事件钩子 |\n| `thought hooks list` | 列出已安装的钩子 |\n| `thought hooks uninstall` | 卸载钩子 |\n| `thought recall` | 检索相关记忆 |\n| `thought scan ` | 扫描代码仓库更新实体 |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：RNBBarrett/thought-mcp\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | host_targets=mcp_host, claude, claude_code, chatgpt\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | no_demo; severity=medium\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | release_recency=unknown\n\n\n",
"markdown_key": "thought-mcp",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1238261514",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/RNBBarrett/thought-mcp"
},
{
"evidence_id": "art_8d2c2921d2514add891eadc2ade2f9ab",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/RNBBarrett/thought-mcp#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "thought-mcp 说明书",
"toc": [
"https://github.com/RNBBarrett/thought-mcp 项目说明书",
"目录",
"项目概述",
"简介",
"核心定位",
"系统架构",
"核心功能模块",
"使用场景与演示",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": false,
"repo_commit": null,
"repo_inspection_error": null,
"repo_inspection_files": [],
"repo_inspection_verified": false,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# thought-mcp - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 thought-mcp 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install 'thought-mcp[all]'` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install thought-mcp` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0005` supported 0.86\n- `curl http://localhost:11434/api/tags` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `curl http://localhost:1234/v1/models` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `pip install --upgrade thought-mcp # pull the new package` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `pip install pysqlite3-binary` 证据：`README.md` Claim：`clm_0009` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、宿主 AI 上下文\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0010` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0011` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：127\n- 重要文件覆盖：11/127\n- 证据索引条目：10\n- 角色 / Skill 条目：5\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 thought-mcp 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 thought-mcp 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 thought-mcp 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 5 个角色 / Skill / 项目文档条目。\n\n- **THOUGHT**（project_doc）：! PyPI https://img.shields.io/pypi/v/thought-mcp.svg https://pypi.org/project/thought-mcp/ ! Python https://img.shields.io/pypi/pyversions/thought-mcp.svg https://pypi.org/project/thought-mcp/ ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg LICENSE ! CI https://github.com/RNBBarrett/thought-mcp/actions/workflows/ci.yml/badge.svg https://github.com/RNBBarrett/thought-mcp/actions/workflows/ci.yml !… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Contributing to thought-mcp**（project_doc）：Thanks for picking this up. The project is small enough that one focused PR per topic is the right shape. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Ablation study — marginal contribution of Tier A techniques**（project_doc）：Ablation study — marginal contribution of Tier A techniques 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/ablation.md`\n- **Comparison harness — measured results**（project_doc）：Comparison harness — measured results 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/comparison.md`\n- **Changelog**（project_doc）：All notable changes to thought-mcp are documented here. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n\n## 证据索引\n\n- 共索引 10 条证据。\n\n- **THOUGHT**（documentation）：! PyPI https://img.shields.io/pypi/v/thought-mcp.svg https://pypi.org/project/thought-mcp/ ! Python https://img.shields.io/pypi/pyversions/thought-mcp.svg https://pypi.org/project/thought-mcp/ ! License: MIT https://img.shields.io/badge/License-MIT-yellow.svg LICENSE ! CI https://github.com/RNBBarrett/thought-mcp/actions/workflows/ci.yml/badge.svg https://github.com/RNBBarrett/thought-mcp/actions/workflows/ci.yml ! Docker https://github.com/RNBBarrett/thought-mcp/actions/workflows/docker.yml/badge.svg https://github.com/RNBBarrett/thought-mcp/actions/workflows/docker.yml ! GHCR https://img.shields.io/badge/ghcr.io-thought--mcp-blue?logo=docker https://github.com/RNBBarrett/thought-mcp/pkgs/… 证据：`README.md`\n- **Contributing to thought-mcp**（documentation）：Thanks for picking this up. The project is small enough that one focused PR per topic is the right shape. 证据：`CONTRIBUTING.md`\n- **License**（source_file）：Copyright c 2026 Richard Barrett and THOUGHT contributors 证据：`LICENSE`\n- **Ablation study — marginal contribution of Tier A techniques**（documentation）：Ablation study — marginal contribution of Tier A techniques 证据：`docs/ablation.md`\n- **Comparison harness — measured results**（documentation）：Comparison harness — measured results 证据：`docs/comparison.md`\n- **Changelog**（documentation）：All notable changes to thought-mcp are documented here. 证据：`CHANGELOG.md`\n- **.dockerignore**（source_file）：.venv/ pycache / .pyc .pyo .pytest cache/ .mypy cache/ .ruff cache/ .coverage htmlcov/ build/ dist/ .egg-info/ .db .db-journal .thought/ .cache/ models/ .git/ .github/ docs/ tests/perf/.tmp/ plan.md 证据：`.dockerignore`\n- **Build artifacts**（source_file）：Build artifacts build/ dist/ .egg-info/ .egg pycache / .py cod $py.class .pytest cache/ .ruff cache/ .mypy cache/ .coverage htmlcov/ coverage.xml .tox/ .nox/ 证据：`.gitignore`\n- **---- build stage ---------------------------------------------------------**（source_file）：---- build stage --------------------------------------------------------- FROM python:${PYTHON VERSION}-slim AS build WORKDIR /src RUN pip install --no-cache-dir --upgrade pip build COPY pyproject.toml README.md LICENSE ./ COPY src ./src RUN python -m build --wheel --outdir /wheels 证据：`Dockerfile`\n- **The MCP server can't start without these — they're not really optional**（source_file）：build-system requires = \"hatchling =1.24\" build-backend = \"hatchling.build\" 证据：`pyproject.toml`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `CONTRIBUTING.md`, `LICENSE`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `CONTRIBUTING.md`, `LICENSE`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, src/thought/__init__.py\n- **安装与快速开始**：importance `high`\n - source_paths: pyproject.toml, src/thought/cli.py, Dockerfile\n- **系统架构**：importance `high`\n - source_paths: src/thought/server.py, src/thought/storage/base.py, src/thought/ingest/pipeline.py, src/thought/layers/__init__.py, src/thought/router/dispatcher.py\n- **配置管理**：importance `medium`\n - source_paths: src/thought/config.py, src/thought/embeddings/__init__.py, src/thought/models.py\n- **代码摄取与解析**：importance `high`\n - source_paths: src/thought/ingest/code/pipeline.py, src/thought/ingest/code/python_extractor.py, src/thought/ingest/code/typescript_extractor.py, src/thought/ingest/code/go_extractor.py, src/thought/ingest/code/rust_extractor.py\n- **实体与关系管理**：importance `high`\n - source_paths: src/thought/ingest/entities.py, src/thought/ingest/code/types.py, src/thought/layers/code.py\n- **记忆模型与检索**：importance `high`\n - source_paths: src/thought/memory.py, src/thought/hooks/recall.py, src/thought/layers/graph.py, src/thought/layers/vector.py, src/thought/layers/temporal.py\n- **查询系统**：importance `high`\n - source_paths: src/thought/query/cypher.py, src/thought/query/ask.py, src/thought/query/views.py, src/thought/router/classifier.py, src/thought/router/rules.yaml\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | host_targets=mcp_host, claude, claude_code, chatgpt\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：RNBBarrett/thought-mcp\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude, claude_code, chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在安全注意事项（medium）：用户安装前需要知道权限边界和敏感操作。 建议检查：转成明确权限清单和安全审查提示。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/RNBBarrett/thought-mcp 项目说明书\n\n生成时间：2026-05-16 09:07:15 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [安装与快速开始](#page-installation)\n- [系统架构](#page-architecture)\n- [配置管理](#page-configuration)\n- [代码摄取与解析](#page-code-ingestion)\n- [实体与关系管理](#page-entity-management)\n- [记忆模型与检索](#page-memory-model)\n- [查询系统](#page-query-system)\n- [图形层与图遍历](#page-graph-layer)\n- [Agent集成与适配器](#page-agent-integration)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [安装与快速开始](#page-installation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CHANGELOG.md](https://github.com/RNBBarrett/thought-mcp/blob/main/CHANGELOG.md)\n- [src/thought/demo.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/demo.py)\n- [src/thought/cli.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/cli.py)\n- [src/thought/models.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/models.py)\n- [src/thought/layers/code.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/code.py)\n- [src/thought/ingest/code/types.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/types.py)\n- [src/thought/ingest/code/pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/pipeline.py)\n- [src/thought/ingest/code/python_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/python_extractor.py)\n- [src/thought/ingest/code/git_pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/git_pipeline.py)\n- [CONTRIBUTING.md](https://github.com/RNBBarrett/thought-mcp/blob/main/CONTRIBUTING.md)\n \n\n# 项目概述\n\n## 简介\n\n**thought-mcp** 是一个本地AI记忆工具（Local-AI Memory Tool），旨在为开发者提供完整的知识库管理、代码理解、本地大语言模型集成和自然语言查询能力。该项目通过 SQLite 作为底层存储，结合向量嵌入技术和 Cypher 图查询语言，实现了一个功能完备的个人知识管理系统。\n\n资料来源：[CHANGELOG.md:1-15]()\n\n## 核心定位\n\nthought-mcp 扮演着**开发者第二大脑**的角色，它将代码库、知识文档、工作会话等信息统一纳入管理范围。与传统的笔记工具不同，thought-mcp 具有以下独特优势：\n\n- **代码感知**：原生支持多种编程语言的 AST 解析，能够理解代码结构、依赖关系和调用图\n- **时间旅行**：采用双时态模型（Bi-temporal Model），支持 `valid_time` 和 `learned_time` 两种时间维度\n- **本地优先**：完全运行在本地环境，支持 Ollama、LM Studio 等本地 LLM 和 embedding 服务\n- **图数据库能力**：通过 Cypher 查询语言实现复杂的知识图谱查询\n\n资料来源：[src/thought/layers/code.py:1-20]()\n\n## 系统架构\n\nthought-mcp 采用分层架构设计，各层职责明确：\n\n```mermaid\ngraph TD\n subgraph \"表示层\"\n CLI[CLI 命令行]\n MCP[MCP 服务器]\n TUI[图形界面 TUI]\n end\n \n subgraph \"应用层\"\n Router[路由层]\n Ask[自然语言查询]\n Demo[演示模块]\n end\n \n subgraph \"领域层\"\n CodeLayer[代码层]\n GraphLayer[图查询层]\n MemoryLayer[记忆层]\n end\n \n subgraph \"摄入层\"\n Ingest[代码摄入]\n GitIngest[Git历史摄入]\n ProseIngest[文本摄入]\n end\n \n subgraph \"存储层\"\n SQLite[(SQLite)]\n Backend[存储后端]\n WAL[WAL检查点]\n end\n \n CLI --> Router\n MCP --> Router\n Router --> Ask\n Ask --> GraphLayer\n CodeLayer --> GraphLayer\n Ingest --> Backend\n GitIngest --> Backend\n Backend --> SQLite\n```\n\n### 各层职责\n\n| 层次 | 组件 | 职责 | 源码位置 |\n|------|------|------|----------|\n| 表示层 | `cli.py` | 命令行入口，处理用户输入 | `src/thought/cli.py` |\n| 表示层 | MCP 服务器 | 提供 Model Context Protocol 接口 | `src/thought/server/` |\n| 应用层 | `ask` 命令 | 自然语言转 Cypher 查询 | `src/thought/cli.py` |\n| 领域层 | `CodeLayer` | 代码特定查询封装 | `src/thought/layers/code.py` |\n| 领域层 | `GraphLayer` | 图查询操作核心 | `src/thought/layers/graph.py` |\n| 存储层 | `SQLiteBackend` | 数据库操作封装 | `src/thought/storage/sqlite/backend.py` |\n\n资料来源：[src/thought/cli.py:1-35]()\n资料来源：[src/thought/layers/code.py:1-30]()\n\n## 核心功能模块\n\n### 1. CLI 命令行工具\n\n`thought` CLI 是用户与系统交互的主要入口，提供以下命令：\n\n| 命令 | 功能 | 源码位置 |\n|------|------|----------|\n| `thought init` | 初始化数据库和配置 | `src/thought/cli.py` |\n| `thought serve` | 启动 MCP 服务器 | `src/thought/cli.py` |\n| `thought ingest` | 摄入实体信息 | `src/thought/cli.py` |\n| `thought recall` | 召回相关记忆 | `src/thought/cli.py` |\n| `thought ask` | 自然语言查询 | `src/thought/cli.py` |\n| `thought callers` | 查找调用者（PageRank排序） | `CHANGELOG.md` |\n| `thought impact` | 计算变更影响范围 | `CHANGELOG.md` |\n| `thought diff` | 比较两个提交间的差异 | `CHANGELOG.md` |\n| `thought schema` | 查看实体类型统计 | `src/thought/cli.py` |\n| `thought db flush/backup/load/inspect` | 数据库生命周期管理 | `CHANGELOG.md` |\n\n资料来源：[src/thought/cli.py:15-30]()\n\n### 2. 代码理解引擎\n\nthought-mcp 的代码理解能力基于多语言 AST 解析器，支持以下编程语言：\n\n| 语言 | 提取器 | 源码位置 |\n|------|--------|----------|\n| Python | `python_extractor.py` | `src/thought/ingest/code/python_extractor.py` |\n| TypeScript | `typescript_extractor.py` | `src/thought/ingest/code/typescript_extractor.py` |\n| Rust | `rust_extractor.py` | `src/thought/ingest/code/rust_extractor.py` |\n| PHP | `php_extractor.py` | `src/thought/ingest/code/php_extractor.py` |\n\n每个语言提取器都能识别以下代码实体类型：\n\n```mermaid\ngraph TD\n subgraph \"代码实体类型\"\n Module[模块/命名空间]\n Class[类定义]\n Function[函数]\n Method[方法]\n File[文件]\n Import[导入关系]\n end\n \n subgraph \"代码边类型\"\n DEFINES[DEFINES - 定义关系]\n IMPORTS[IMPORTS - 导入关系]\n INHERITS_FROM[INHERITS_FROM - 继承关系]\n OVERRIDES[OVERRIDES - 重写关系]\n CALLS[CALLS - 调用关系]\n end\n \n Class --> DEFINES\n Class --> INHERITS_FROM\n Module --> IMPORTS\n```\n\n资料来源：[src/thought/ingest/code/types.py:1-50]()\n资料来源：[src/thought/ingest/code/python_extractor.py:1-50]()\n\n### 3. 数据模型\n\nthought-mcp 使用双时态数据模型记录实体和边的生命周期：\n\n#### Entity 实体模型\n\n```python\nclass Entity(BaseModel):\n id: str\n type: str\n name: str\n canonical_name: str\n owner_id: str | None = None\n scope: ScopeName # shared | private\n tier: Tier # hot | warm | cold\n importance: float # 0.0 ~ 1.0\n valid_from: datetime # 事实生效时间\n valid_until: datetime | None # 事实失效时间\n learned_at: datetime # 系统学习时间\n unlearned_at: datetime | None\n created_at: datetime\n last_accessed_at: datetime\n access_count: int = 0\n attrs: dict[str, object]\n```\n\n资料来源：[src/thought/models.py:1-80]()\n\n#### 双时态模型说明\n\n| 时间维度 | 字段 | 含义 | 使用场景 |\n|----------|------|------|----------|\n| 有效时间 | `valid_from` / `valid_until` | 事实本身在现实世界生效的时间段 | 查询\"某代码在某个时间点是否存在\" |\n| 学习时间 | `learned_at` / `unlearned_at` | 系统何时获知该事实 | 查询\"系统在某个时间点知道什么\" |\n\n这种设计允许用户进行真正的\"时间旅行\"查询：\n\n- `as_of_kind='valid'` — \"在 X 日期，什么是真实现实？\"\n- `as_of_kind='learned'` — \"在 X 日期，系统知道什么？\"\n\n资料来源：[src/thought/cli.py:1-30]()\n\n### 4. Git 历史感知摄入\n\n`thought ingest-git` 命令支持两种摄入模式：\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| `snapshot` (默认) | 仅摄入 HEAD 提交 | 快速初始化 |\n| `full` | 遍历每个提交，记录每个实体的提交SHA | 完整历史追溯 |\n\n```mermaid\ngraph LR\n A[Git仓库] --> B[GitWalker]\n B --> C[逐提交遍历]\n C --> D{摄入模式}\n D -->|snapshot| E[仅HEAD]\n D -->|full| F[所有提交]\n E --> G[(SQLite KB)]\n F --> G\n```\n\n`GitWalker` 使用纯 Python subprocess 实现，不依赖 `pygit2` 等本地库。\n\n资料来源：[src/thought/ingest/code/git_pipeline.py:1-50]()\n\n### 5. 本地 LLM 集成\n\nthought-mcp 支持多种本地 LLM 提供商：\n\n| 提供商 | Embedder 类 | 特点 |\n|--------|-------------|------|\n| Ollama | `OllamaEmbedder` | 使用原生 `/api/embed` 接口，支持批量操作 |\n| LM Studio | `LMStudioEmbedder` | OpenAI 兼容接口 |\n| 任意 OpenAI 兼容服务器 | `OpenAICompatEmbedder` | 通用兼容层 |\n\n配置通过 `thought.toml` 文件管理：\n\n```toml\n[llm]\nprovider = \"ollama\" # anthropic | ollama | lmstudio | openai-compat | openai\n\n[embedding]\nmodel = \"nomic-embed-text\" # 或其他 embedding 模型\n```\n\n资料来源：[CHANGELOG.md:1-50]()\n\n### 6. Cypher 图查询\n\nv0.4.0 引入的 Cypher 查询子集允许直接查询知识图谱：\n\n```cypher\n// 查找某个函数的所有调用者\nMATCH (caller)-[:CALLS]->(target {name: 'authenticate_user'})\nRETURN caller\n\n// 查找继承链\nMATCH (child)-[:INHERITS_FROM*]->(parent)\nWHERE child.name = 'MyClass'\nRETURN parent\n```\n\n**当前限制**：Cypher 子集是**只读**的，写操作仍需通过 `remember` / `ingest` / 自动写入钩子。\n\n资料来源：[CHANGELOG.md:1-80]()\n\n## 使用场景与演示\n\n`thought demo` 命令提供内置的演示功能，针对不同用户群体：\n\n| 受众 | 演示内容 | 源码位置 |\n|------|----------|----------|\n| `code` | Agent/开发者流程，14阶段代码分析演示 | `src/thought/demo.py` |\n| `writer` | 小说家/论文作者，矛盾检测，时间旅行查询 | `src/thought/demo.py` |\n| `legal` | 调查员/律师，证词矛盾图分析 | `src/thought/demo.py` |\n| `researcher` | 学术研究，引用关系分析 | `src/thought/demo.py` |\n| `all` | 运行所有受众演示 | `src/thought/demo.py` |\n\n资料来源：[src/thought/demo.py:1-50]()\n\n## 技术栈概览\n\n| 组件 | 技术选型 | 用途 |\n|------|----------|------|\n| 数据库 | SQLite + WAL 模式 | 持久化存储 |\n| 向量检索 | sentence-transformers / Ollama embed | 语义搜索 |\n| 图查询 | Cypher 子集 | 复杂关系查询 |\n| AST 解析 | tree-sitter | 多语言代码解析 |\n| CLI | Typer + Rich | 命令行界面 |\n| 协议 | MCP (Model Context Protocol) | AI 助手集成 |\n\n资料来源：[src/thought/ingest/code/python_extractor.py:1-30]()\n\n## 版本路线图\n\n| 版本 | 主题 | 资料来源 |\n|------|------|----------|\n| v0.5 | 写作垂直领域，代码理解增强 | `CHANGELOG.md` |\n| v0.6 | 写作功能完善（小说/学术写作） | `CHANGELOG.md` |\n| v0.7 | 调查领域（法律/合规/取证） | `CHANGELOG.md` |\n| v0.8 | 平台功能（图TUI/基准测试/联邦同步） | `CHANGELOG.md` |\n\n资料来源：[CHANGELOG.md:1-100]()\n\n## 开发规范\n\n项目遵循以下开发准则：\n\n1. **测试策略**：使用真实 SQLite 数据库测试，不使用 mock，确保测试与生产环境一致\n2. **代码风格**：显式优于巧妙，注释说明\"为什么\"而非\"做什么\"\n3. **PR 规范**：一个 PR 一个主题，必须有测试，必须更新 CHANGELOG\n4. **类型注解**：新代码应清晰标注类型\n5. **Linting**：提交前必须通过 `ruff check src tests`\n\n资料来源：[CONTRIBUTING.md:1-50]()\n\n## 总结\n\nthought-mcp 是一个功能完备的本地 AI 记忆工具，通过以下核心能力为开发者提供知识管理服务：\n\n- **多语言代码理解**：支持 Python、TypeScript、Rust、PHP 等语言的 AST 解析\n- **双时态模型**：支持事实的有效时间和系统学习时间的独立追踪\n- **本地优先**：无需云服务，完全运行在本地环境\n- **图查询能力**：通过 Cypher 子集实现复杂关系查询\n- **灵活摄入**：支持代码、文本、Git 历史等多种数据源的摄入\n\n---\n\n\n\n## 安装与快速开始\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [配置管理](#page-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/RNBBarrett/thought-mcp/blob/main/pyproject.toml)\n- [src/thought/cli.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/cli.py)\n- [src/thought/demo.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/demo.py)\n- [src/thought/ingest/code/pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/pipeline.py)\n- [src/thought/ingest/code/git_walker.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/git_walker.py)\n- [src/thought/layers/code.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/code.py)\n- [CONTRIBUTING.md](https://github.com/RNBBarrett/thought-mcp/blob/main/CONTRIBUTING.md)\n \n\n# 安装与快速开始\n\n本页面介绍 thought-mcp 的完整安装流程和快速上手指南。thought-mcp 是一个本地AI记忆工具，通过 SQLite 数据库存储知识库，支持代码图谱查询、Git历史感知摄取和多语言代码解析。\n\n## 系统要求\n\n在开始安装前，请确保环境满足以下要求：\n\n| 组件 | 最低版本 | 说明 |\n|------|---------|------|\n| Python | 3.10+ | 项目主语言 |\n| Git | 任意版本 | 用于代码仓库摄取 |\n| pip / uv | 最新版本 | 包管理器 |\n\n可选依赖项：\n\n| 组件 | 用途 | 安装方式 |\n|------|------|---------|\n| sentence-transformers | 语义向量嵌入 | 可选，未安装时使用确定性嵌入器 |\n| Ollama / LM Studio | 本地LLM集成 | 支持OpenAI兼容API |\n| tree-sitter | AST代码解析 | 自动安装 |\n\n## 安装方式\n\n### 方式一：pip 安装（推荐）\n\n```bash\npip install thought-mcp\n```\n\n### 方式二：源码安装\n\n```bash\ngit clone https://github.com/RNBBarrett/thought-mcp.git\ncd thought-mcp\npip install -e .\n```\n\n### 方式三：Docker 部署\n\n项目根目录包含 Dockerfile，支持容器化部署：\n\n```bash\ndocker build -t thought-mcp .\ndocker run thought-mcp thought --help\n```\n\n资料来源：[src/thought/cli.py:1-25]()\n\n## 初始化项目\n\n安装完成后，需要初始化 thought-mcp 来创建数据库和配置文件：\n\n```bash\nthought init\n```\n\n### init 命令参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--config` | `thought.toml` | 配置文件路径 |\n| `--db-path` | `.thought/thought.db` | SQLite 数据库路径 |\n| `--embedder` | `auto` | 嵌入器选择：`auto`、`sentence-transformers` 或 `deterministic` |\n| `--write-claude-md` | `True` | 是否生成 CLAUDE.md 供 MCP 客户端使用 |\n| `--quick` | `False` | 跳过首次运行的嵌入器预热 |\n\n初始化过程会执行以下操作：\n\n1. 创建 `.thought` 目录\n2. 初始化 SQLite 数据库文件\n3. 生成 `thought.toml` 配置文件\n4. 可选：写入 `CLAUDE.md` 提示文件\n\n资料来源：[src/thought/cli.py:50-85]()\n\n## 核心命令速查\n\n初始化完成后，可以使用以下核心命令：\n\n| 命令 | 功能 |\n|------|------|\n| `thought ingest TEXT` | 从命令行一次性摄取文本 |\n| `thought recall QUERY` | 自然语言查询知识库 |\n| `thought serve` | 启动 MCP 服务器 |\n| `thought stats` | 查看知识库统计信息 |\n| `thought doctor` | 环境健康检查 |\n\n## 快速开始示例\n\n### 步骤一：验证安装\n\n```bash\nthought doctor\n```\n\n此命令会检查环境依赖是否正确安装，包括数据库访问、嵌入器配置等。\n\n### 步骤二：知识摄取\n\n**摄取文本：**\n```bash\nthought ingest \"今天学习了Python的装饰器模式\"\n```\n\n**摄取文件：**\n```bash\nthought ingest --file ./src/main.py\n```\n\n**批量摄取（glob模式）：**\n```bash\nthought ingest --glob \"**/*.py\"\n```\n\n**从标准输入摄取：**\n```bash\ncat files.txt | thought ingest --stdin\n```\n\n资料来源：[src/thought/cli.py:100-120]()\n\n### 步骤三：查询召回\n\n```bash\nthought recall \"Python装饰器\"\n```\n\nrecall 命令返回最多 10 条匹配结果，支持以下高级参数：\n\n| 参数 | 说明 |\n|------|------|\n| `--as-of` | 时间旅行查询，指定历史时间点 |\n| `--scope` | 作用域过滤 |\n\n### 步骤四：运行演示\n\n项目内置多种场景演示：\n\n```bash\nthought demo [audience]\n```\n\n| audience 参数 | 说明 |\n|---------------|------|\n| `code` | Agent/开发者流程，包含 14 阶段代码垂直演示 |\n| `writer` | 小说家/论文作者场景，演示双时态模型 |\n| `legal` | 法律调查场景，演示矛盾检测 |\n| `researcher` | 学术研究场景，Cypher 查询演示 |\n| `all` | 运行所有场景 |\n\n资料来源：[src/thought/demo.py:1-45]()\n\n## 代码仓库摄取\n\nthought-mcp 支持深入分析代码仓库，建立代码知识图谱：\n\n### 基本摄取\n\n```bash\nthought ingest-git ./my-project\n```\n\n### 高级选项\n\n| 参数 | 可选值 | 说明 |\n|------|--------|------|\n| `--mode` | `snapshot`（默认）、`full` | 快照模式仅摄取HEAD，全量模式遍历所有提交 |\n| `--language` | `python`、`typescript`、`rust`、`php` 等 | 指定语言覆盖自动检测 |\n| `--skip-call-graph` | - | 跳过调用图构建 |\n\n摄取流程架构：\n\n```mermaid\ngraph TD\n A[git仓库] --> B[GitWalker遍历]\n B --> C{--mode参数}\n C -->|snapshot| D[仅获取HEAD]\n C -->|full| E[遍历所有提交]\n D --> F[代码文件解析]\n E --> F\n F --> G[语言提取器]\n G --> H[CodeEntity + CodeEdge]\n H --> I[CallGraph构建]\n I --> J[SQLite存储]\n```\n\n摄取完成后，可使用以下代码查询命令：\n\n| 命令 | 功能 |\n|------|------|\n| `thought callers ` | 查询直接调用者，按 PageRank 排序 |\n| `thought impact ` | 变更影响分析，查询传递调用者 |\n| `thought diff --from SHA1 --to SHA2` | 对比两次提交间的实体差异 |\n\n资料来源：[src/thought/ingest/code/git_walker.py:1-35]()\n\n## MCP 服务器模式\n\n启动 MCP 服务器供 AI 助手集成使用：\n\n```bash\nthought serve\n```\n\n### 传输方式\n\n| 方式 | 命令 | 说明 |\n|------|------|------|\n| stdio（默认） | `thought serve` | 标准输入输出通信 |\n| HTTP | `thought serve --transport streamable-http` | HTTP 协议通信 |\n\n服务器启动后会持续运行，等待 MCP 客户端连接。\n\n## 配置说明\n\n初始化后生成的 `thought.toml` 配置文件结构：\n\n```toml\n[database]\npath = \".thought/thought.db\"\n\n[embedder]\ntype = \"auto\" # auto | sentence-transformers | deterministic\n\n[server]\ntransport = \"stdio\"\n```\n\n### 嵌入器配置\n\n| 类型 | 说明 | 依赖 |\n|------|------|------|\n| `auto` | 自动检测sentence-transformers可用性 | 可选安装 |\n| `sentence-transformers` | 语义向量嵌入 | pip install sentence-transformers |\n| `deterministic` | 基于文本哈希的确定性嵌入 | 无外部依赖 |\n\n当设置 `auto` 时，系统会通过 `importlib.util.find_spec` 检测 sentence-transformers 是否可用，若未安装则回退到确定性嵌入器。\n\n资料来源：[src/thought/ingest/code/pipeline.py:40-60]()\n\n## 故障排除\n\n### doctor 命令检查项\n\n`thought doctor` 会验证以下项目：\n\n- Python 版本兼容性\n- 数据库文件可访问性\n- 嵌入器配置有效性\n- 必要的目录权限\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 嵌入器加载失败 | 使用 `--embedder deterministic` 降级使用 |\n| Git仓库检测失败 | 确认目录包含 `.git` 目录 |\n| 数据库锁定 | 检查是否有其他进程正在访问 |\n\n## 下一步\n\n安装完成后，建议继续阅读以下文档：\n\n- [使用指南]() - 深入了解 recall、caller、impact 等高级命令\n- [代码图谱分析]() - 理解调用图构建和代码实体关系\n- [开发指南](CONTRIBUTING.md) - 参与项目开发的代码规范\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [查询系统](#page-query-system), [图形层与图遍历](#page-graph-layer)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/server.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/server.py)\n- [src/thought/storage/base.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/storage/base.py)\n- [src/thought/ingest/pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/pipeline.py)\n- [src/thought/layers/__init__.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/__init__.py)\n- [src/thought/router/dispatcher.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/router/dispatcher.py)\n \n\n# 系统架构\n\n## 概述\n\nthought-mcp 是一个基于 SQLite 的本地 AI 记忆工具，采用分层架构设计，核心功能围绕知识库（Knowledge Base）管理、代码实体解析、自然语言查询路由三大模块展开。系统通过 MCP（Model Context Protocol）协议对外提供服务，支持本地 LLM 集成和双时态（bi-temporal）数据模型。资料来源：[src/thought/layers/__init__.py](src/thought/layers/__init__.py)\n\n## 核心架构分层\n\n系统采用四层架构模型，每一层职责明确，通过标准化接口进行通信：\n\n| 层级 | 模块 | 职责 |\n|------|------|------|\n| 接口层 | CLI / MCP Server | 用户交互、命令解析 |\n| 路由层 | Router / Dispatcher | 查询分类、自然语言转 Cypher |\n| 业务层 | Layers (Graph, Code, Recall) | 图查询、代码分析、实体检索 |\n| 存储层 | SQLite Backend | 数据持久化、向量存储 |\n\n```mermaid\ngraph TD\n A[CLI / MCP Client] --> B[Router / Dispatcher]\n B --> C{C 查询类型}\n C -->|CODE| D[CodeLayer]\n C -->|GRAPH| E[GraphLayer]\n C -->|RECALL| F[RecallLayer]\n C -->|ASK| G[AskModule]\n D --> H[SQLite Backend]\n E --> H\n F --> H\n G --> H\n H --> I[(SQLite DB)]\n```\n\n资料来源：[src/thought/router/dispatcher.py](src/thought/router/dispatcher.py)\n\n## 存储层架构\n\n### SQLite Backend\n\n存储层是整个系统的基础，采用 SQLite 作为主数据库，支持向量嵌入存储和双时态数据模型。Backend 提供了实体的创建、更新、查询以及嵌入向量存储的核心接口。资料来源：[src/thought/storage/base.py](src/thought/storage/base.py)\n\n#### 核心数据模型\n\n系统定义了两种核心数据模型：\n\n**Entity（实体）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | str | 实体唯一标识符 |\n| type | str | 实体类型（function, class, method 等） |\n| name | str | 实体名称 |\n| canonical_name | str | 规范化名称 |\n| scope | ScopeName | 作用域（shared/private） |\n| tier | Tier | 热数据层级（hot/cold） |\n| valid_from | datetime | 有效起始时间 |\n| valid_until | datetime \\| None | 有效结束时间（双时态） |\n| code_file | str \\| None | 代码文件路径 |\n| code_language | str \\| None | 编程语言 |\n| code_commit_sha | str \\| None | Git 提交 SHA |\n\n**Edge（关系）**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| id | str | 关系唯一标识符 |\n| source_id | str | 源实体 ID |\n| target_id | str | 目标实体 ID |\n| relation_type | str | 关系类型（CALLS, IMPORTS, DEFINES 等） |\n\n资料来源：[src/thought/models.py](src/thought/models.py)\n\n### 存储层核心接口\n\nBackend 提供了以下核心方法来管理实体和关系：\n\n- `upsert_entity()` - 创建或更新实体，身份包含 `(code_file, code_commit_sha)` 以区分同名方法\n- `find_code_entity()` - 通过规范化名称快速查找代码实体\n- `store_embedding()` - 存储嵌入向量\n- `query_similar()` - 相似度检索\n\n资料来源：[src/thought/storage/base.py](src/thought/storage/base.py)\n\n## 摄入层架构\n\n### 摄入管道\n\n摄入管道负责将外部数据（代码、文档、法律文本等）转换为统一的实体-关系模型并存储到知识库中。Pipeline 是摄入管道的核心调度器，支持文件级别的原子性写入。资料来源：[src/thought/ingest/pipeline.py](src/thought/ingest/pipeline.py)\n\n```mermaid\ngraph LR\n A[Source File] --> B[Language Detection]\n B --> C[Language Extractor]\n C --> D[Entities + Edges]\n D --> E[Backend upsert]\n E --> F[Embedding]\n F --> G[(Knowledge Base)]\n```\n\n### 多语言代码解析器\n\n系统为每种支持的编程语言实现了专门的提取器，所有提取器遵循统一的接口规范：\n\n```python\ndef extract(source: str, file_path: str) -> tuple[list[CodeEntity], list[CodeEdge]]\n```\n\n**支持的编程语言及提取器：**\n\n| 语言 | 提取器文件 | 提取的实体类型 |\n|------|-----------|---------------|\n| Python | python_extractor.py | module, function, class, method, import |\n| TypeScript | typescript_extractor.py | module, function, class, method, import, export, inheritance |\n| PHP | php_extractor.py | module, function, class, method, import |\n| Rust | rust_extractor.py | module, function, struct, impl, method |\n\n资料来源：[src/thought/ingest/code/python_extractor.py](src/thought/ingest/code/python_extractor.py)\n\n### 调用图构建\n\n`build_call_graph` 模块负责解析代码中的函数调用关系，支持多级解析策略：\n\n1. **文件内匹配** - 在同一文件中查找被调用函数定义\n2. **唯一qualified后缀匹配** - `obj.method()` 匹配唯一的 `ClassName.method`\n3. **跨文件裸名称匹配** - 查找其他文件中定义的顶级函数\n4. **Stub创建** - 当找不到定义时，创建占位实体\n\n资料来源：[src/thought/ingest/code/call_graph.py](src/thought/ingest/code/call_graph.py)\n\n### Git 历史感知摄入\n\n`GitWalker` 支持两种摄入模式：\n\n- **snapshot 模式（默认）** - 仅摄入 HEAD 提交内容\n- **full 模式** - 遍历每个提交，关联实体与对应提交 SHA\n\n这种设计支持双时态查询，可以查询特定时间点的代码状态。资料来源：[src/thought/ingest/code/git_pipeline.py](src/thought/ingest/code/git_pipeline.py)\n\n## 业务层架构\n\n### Layer 模块\n\n`Layers` 模块封装了针对不同数据类型的图查询操作，提供领域特定的查询接口。资料来源：[src/thought/layers/__init__.py](src/thought/layers/__init__.py)\n\n#### GraphLayer\n\n通用的图查询层，提供基础的实体和关系查询能力，支持作用域过滤（shared/private/all）。\n\n#### CodeLayer\n\n代码专用查询层，提供程序员友好的接口：\n\n| 方法 | 功能 |\n|------|------|\n| `callers_of(name)` | 查询直接调用者，按 PageRank 排序 |\n| `callees_of(name)` | 查询调用的函数（同包内） |\n| `impact_set(name)` | 传递性影响集合（变更会影响哪些代码） |\n| `defines_in_file(path)` | 查询文件中定义的所有实体 |\n\n资料来源：[src/thought/layers/code.py](src/thought/layers/code.py)\n\n### 查询路由器\n\n`Router/Dispatcher` 是系统的查询入口点，负责将用户查询分类到对应的处理器：\n\n**查询类型分类：**\n\n| 查询类型 | 触发关键词 | 处理器 |\n|----------|-----------|--------|\n| CODE | function, class, caller, callee, file extensions, camelCase/snake_case |\n| CHANGE | changed, added, removed, since, before |\n| RECALL | 记忆相关查询 |\n| ASK | 自然语言问题 |\n\n**路由组合：**\n\n- CODE × CHANGE → HYBRID（如 \"auth.middleware 自 v1.0 以来的变更\"）\n- 支持 `as_of` 时间旅行查询\n\n资料来源：[src/thought/router/dispatcher.py](src/thought/router/dispatcher.py)\n\n### 自然语言查询模块\n\n`Ask` 模块将自然语言问题翻译为 Cypher 查询语句：\n\n```mermaid\ngraph TD\n A[Natural Language Question] --> B[LLM Provider]\n B --> C[Cypher Query]\n C --> D[Parser Validation]\n D -->|Valid| E[Execute Query]\n D -->|Invalid| F[Recall Fallback]\n```\n\n翻译过程遵循以下约束：\n- 仅使用只读 Cypher 特性（MATCH, WHERE, RETURN, LIMIT）\n- 禁止使用写操作（MERGE, CREATE, DELETE, SET）\n- 支持 AS_OF 时间旅行语法\n\n资料来源：[src/thought/query/ask.py](src/thought/query/ask.py)\n\n## MCP 服务器架构\n\n### Server 组件\n\nMCP 服务器通过 `server.py` 实现，提供标准化的工具接口供 MCP 客户端调用。服务器封装了 CLI 的核心功能，暴露为 MCP 工具。资料来源：[src/thought/server.py](src/thought/server.py)\n\n```mermaid\ngraph TD\n A[MCP Client] --> B[Server Handler]\n B --> C[Router]\n B --> D[Ingest Pipeline]\n B --> E[Recall Layer]\n B --> F[Code Layer]\n```\n\n## 数据库生命周期管理\n\n系统提供完整的数据库管理命令：\n\n| 命令 | 功能 |\n|------|------|\n| `thought db size` | 查看磁盘使用情况和实体/关系数量 |\n| `thought db flush` | 清空知识库（支持时间范围过滤） |\n| `thought db backup` | 在线备份快照 |\n| `thought db load` | 加载备份文件（支持合并模式） |\n| `thought db inspect` | 预览备份文件内容 |\n\n所有破坏性操作前自动备份到 `.bak.`。资料来源：[src/thought/cli.py](src/thought/cli.py)\n\n## 本地 LLM 集成\n\n系统支持连接本地 LLM 提供者：\n\n- **Ollama** - 原生 `/api/embed` 端点（批量）\n- **LM Studio** - OpenAI 兼容接口\n- **任意 OpenAI 兼容服务器**\n\n自动嵌入选择器会探测 `sentence_transformers` 包是否可用，不可用时自动降级到确定性嵌入器。资料来源：[src/thought/storage/sqlite/backend.py](src/thought/storage/sqlite/backend.py)\n\n## CLI 命令体系\n\n系统提供丰富的命令行接口：\n\n| 命令类别 | 主要命令 |\n|----------|----------|\n| 初始化 | `thought init` |\n| 数据摄入 | `thought ingest-code`, `thought ingest-git`, `thought ingest-prose` |\n| 查询 | `thought recall`, `thought ask`, `thought callers`, `thought impact` |\n| 代码分析 | `thought diff --from --to ` |\n| 数据库 | `thought db size/flush/backup/load` |\n| 客户端 | `thought install` (Cline/Claude Code/Cursor) |\n\n资料来源：[src/thought/cli.py](src/thought/cli.py)\n\n---\n\n\n\n## 配置管理\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [Agent集成与适配器](#page-agent-integration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/cli.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/cli.py)\n- [src/thought/hooks/install.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/hooks/install.py)\n- [src/thought/clients.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/clients.py)\n- [src/thought/storage/sqlite/backend.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/storage/sqlite/backend.py)\n- [src/thought/ingest/code/git_pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/git_pipeline.py)\n- [src/thought/layers/code.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/code.py)\n \n\n# 配置管理\n\n## 概述\n\n配置管理是 thought-mcp 系统的核心基础设施，负责管理数据库连接、嵌入器选择、CLI 参数配置以及多客户端（MCP Server）集成配置。系统通过 TOML 格式的配置文件、环境变量和命令行参数三层配置机制，为用户提供灵活的定制能力。\n\n配置管理模块贯穿整个应用生命周期，包括初始化阶段（`thought init`）、运行阶段（各 CLI 命令）以及客户端集成阶段（Claude Code Hooks、MCP Server 安装）。资料来源：[src/thought/cli.py:50-80]()\n\n## 配置架构\n\nthought-mcp 采用分层配置架构，核心组件包括：\n\n```mermaid\ngraph TD\n A[用户配置] --> B[CLI 参数]\n A --> C[TOML 配置文件]\n A --> D[环境变量]\n B --> E[Config 对象]\n C --> E\n D --> E\n E --> F[SQLiteBackend]\n E --> G[Embedder]\n E --> H[HookInstall]\n E --> I[ClientInstall]\n```\n\n### 配置层级\n\n| 层级 | 来源 | 优先级 | 典型用途 |\n|------|------|--------|----------|\n| CLI 参数 | 命令行传入 | 最高 | 临时覆盖、脚本自动化 |\n| TOML 配置 | `thought.toml` | 中 | 持久化项目级配置 |\n| 环境变量 | 系统环境 | 最低 | 容器化部署默认值 |\n\n资料来源：[src/thought/cli.py:50-72]()\n\n## CLI 初始化配置\n\n`thought init` 命令是配置管理的入口点，负责创建数据库文件、配置文件和 Agent 面向文档。\n\n### 命令签名\n\n```python\n@app.command()\ndef init(\n config: Path = typer.Option(\"thought.toml\", help=\"Path to config file.\"),\n db_path: str = typer.Option(\".thought/thought.db\", help=\"SQLite database path.\"),\n embedder: str = typer.Option(\n \"auto\", help=\"'auto' picks sentence-transformers if available, else deterministic.\",\n ),\n write_claude_md: bool = typer.Option(\n True, \"--write-claude-md/--no-claude-md\",\n help=\"Drop a CLAUDE.md so MCP clients learn how to use the tool.\",\n ),\n quick: bool = typer.Option(\n False, \"--quick\", help=\"Skip first-run embedder warmup.\",\n ),\n) -> None:\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `config` | Path | `thought.toml` | TOML 配置文件路径 |\n| `db_path` | str | `.thought/thought.db` | SQLite 数据库文件路径 |\n| `embedder` | str | `auto` | 嵌入器选择：`auto`、`sentence-transformers`、`deterministic` |\n| `write_claude_md` | bool | `True` | 是否生成 CLAUDE.md 供 MCP 客户端学习 |\n| `quick` | bool | `False` | 是否跳过嵌入器首次预热 |\n\n资料来源：[src/thought/cli.py:52-68]()\n\n### 配置初始化流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant CLI as thought init\n participant FS as 文件系统\n participant TOML as TOML 解析器\n participant DB as SQLiteBackend\n\n User->>CLI: thought init --config thought.toml\n CLI->>FS: 检查配置文件\n FS-->>CLI: 配置文件不存在\n CLI->>FS: 创建目录结构 (.thought/)\n CLI->>FS: 创建 thought.toml\n Note over CLI: 使用 POSIX 风格路径分隔符
避免 Windows 路径解析问题\n CLI->>DB: 初始化数据库\n CLI->>FS: 写入 CLAUDE.md (可选)\n CLI-->>User: 配置完成\n```\n\n初始化时，系统会自动创建父目录（`parents=True`），确保数据库路径有效。TOML 配置文件采用 POSIX 风格路径分隔符，以兼容 Windows 系统。资料来源：[src/thought/cli.py:74-78]()\n\n## 嵌入器配置\n\n嵌入器（Embedder）是 thought-mcp 向量检索能力的核心，负责将文本转换为高维向量。\n\n### 嵌入器自动选择机制\n\n```python\n# 伪代码示例\nif embedder == \"auto\":\n if importlib.util.find_spec(\"sentence_transformers\"):\n return OllamaEmbedder() # 或 SentenceTransformerEmbedder\n else:\n return DeterministicEmbedder()\n```\n\n系统通过 `importlib.util.find_spec` 检测 `sentence_transformers` 包是否可用，自动选择最优嵌入器实现。这种设计确保了：\n\n1. 在安装了 `sentence-transformers` 的环境中自动使用高质量嵌入器\n2. 在未安装可选依赖时优雅降级到确定性嵌入器\n3. 避免因可选依赖缺失导致的运行时错误\n\n资料来源：[src/thought/cli.py:95-102]()\n\n### 嵌入器配置参数\n\n| 参数 | 说明 | 可选值 |\n|------|------|--------|\n| `model_name` | 嵌入模型名称 | 字符串 |\n| `model_version` | 模型版本 | 字符串 |\n| `dim` | 向量维度 | 整数 |\n| `batch_size` | 批处理大小 | 整数 |\n\n嵌入器配置存储在数据库的 `embeddings` 表中，每个实体可关联多个嵌入向量。资料来源：[src/thought/storage/sqlite/backend.py:1-50]()\n\n## 数据库配置\n\n### 数据库路径配置\n\n数据库路径通过 `db_path` 参数指定，默认为 `.thought/thought.db`。初始化时会自动创建父目录：\n\n```python\nPath(db_path).parent.mkdir(parents=True, exist_ok=True)\n```\n\n### 数据库后端配置\n\n`SQLiteBackend` 类管理所有数据库操作，包括：\n\n- 连接管理（读写、只读模式）\n- 事务控制\n- 实体与关系存储\n- 向量嵌入存储\n- 代码实体索引\n\n```mermaid\ngraph TD\n A[应用程序] --> B[SQLiteBackend]\n B --> C[主数据库文件]\n B --> D[WAL 文件]\n B --> E[SHM 文件]\n B --> F[entities 表]\n B --> G[edges 表]\n B --> H[embeddings 表]\n B --> I[applied_migrations 表]\n```\n\n资料来源：[src/thought/storage/sqlite/backend.py:1-100]()\n\n### 数据库生命周期命令\n\n| 命令 | 功能 |\n|------|------|\n| `thought db size` | 显示数据库磁盘占用及实体/关系计数 |\n| `thought db flush` | 清空知识库，支持按时间范围过滤 |\n| `thought db backup` | 在线备份数据库快照 |\n| `thought db load` | 原子级替换或合并数据库 |\n| `thought db inspect` | 检查备份文件内容 |\n\n## Hook 配置管理\n\nHook 系统允许 thought-mcp 与 Claude Code 深度集成，在特定事件触发时自动执行记忆操作。\n\n### 支持的 Hook 类型\n\n| Hook 类型 | 触发事件 | 命令 | 说明 |\n|-----------|----------|------|------|\n| `recall` | UserPromptSubmit | `thought hook recall` | 用户提交提示时召回相关记忆 |\n| `write` | Stop | `thought hook write` | 会话结束时自动保存上下文 |\n| `context` | SessionStart | `thought hook context` | 会话开始时注入相关上下文 |\n\n### Hook 安装范围\n\n```python\ndef settings_path(*, scope: Literal[\"project\", \"user\"] = \"project\") -> Path:\n \"\"\"Return the ``.claude/settings.json`` path for the requested scope.\"\"\"\n if scope == \"project\":\n return Path.cwd() / \".claude\" / \"settings.json\"\n```\n\n- **项目级别**（默认）：`.claude/settings.json`，随代码库版本控制\n- **用户级别**：用户主目录下的全局配置\n\n资料来源：[src/thought/hooks/install.py:40-50]()\n\n### Hook 安装结果\n\n```python\n@dataclass(frozen=True)\nclass HookInstallResult:\n kind: HookKind\n path: Path\n status: Literal[\"installed\", \"already_present\", \"error\"]\n detail: str = \"\"\n```\n\n安装状态含义：\n\n- `installed`：新安装成功\n- `already_present`：Hook 已存在且配置匹配\n- `error`：安装失败（详情在 `detail` 中）\n\n## MCP 客户端配置\n\nMCP（Model Context Protocol）客户端配置允许将 thought-mcp 作为服务器集成到各种 IDE 和工具中。\n\n### 支持的客户端\n\n| 客户端 | 配置文件 |\n|--------|----------|\n| Claude Code | `.claude/settings.json` |\n| Cursor | `cursor.settings.json` |\n| VS Code | `vscode-mcp.json` |\n| 其他 | 根据 `_PATH_FNS` 映射 |\n\n### 服务器配置块\n\n```python\ndef server_block() -> dict:\n \"\"\"Generate the MCP server configuration block.\"\"\"\n return {\n \"command\": \"uv\",\n \"args\": [\"run\", \"thought\", \"mcp\"],\n \"env\": {\n \"THOUGHT_DB_PATH\": str(DB_PATH),\n },\n }\n```\n\n### 客户端安装流程\n\n```mermaid\ngraph TD\n A[install call] --> B{配置文件存在?}\n B -->|否| C[创建空配置对象]\n B -->|是| D[读取现有配置]\n D --> E{JSON 有效?}\n E -->|否| F[返回错误]\n E -->|是| G[合并服务器配置]\n C --> G\n G --> H{需要备份?}\n H -->|是| I[创建 .thought.bak 备份]\n H -->|否| J[写入配置文件]\n I --> J\n J --> K[返回安装结果]\n```\n\n安装过程会备份原配置文件（后缀 `.thought.bak`），确保配置可回滚。资料来源：[src/thought/clients.py:60-90]()\n\n## TOML 配置文件格式\n\n### 配置文件位置\n\n默认搜索顺序：\n1. 当前目录的 `thought.toml`\n2. 用户指定路径（通过 `--config` 参数）\n\n### 典型配置示例\n\n```toml\n# thought.toml\n[database]\npath = \".thought/thought.db\"\n\n[embedder]\ntype = \"auto\" # 或 \"sentence-transformers\", \"deterministic\"\nmodel_name = \"all-MiniLM-L6-v2\"\n\n[hooks]\nrecall = true\nwrite = true\ncontext = false\n\n[client]\nserver_name = \"thought\"\n```\n\n### 路径格式规范\n\n```python\n# 确保 TOML 中使用 POSIX 风格路径分隔符\n# 避免 Windows 路径如 C:\\Users\\...\\thought.db 在 TOML 解析时出现问题\n```\n\n资料来源：[src/thought/cli.py:77-78]()\n\n## 代码图谱配置\n\n代码图谱是 thought-mcp 的核心功能之一，支持通过 Git 历史追踪代码实体变化。\n\n### Git 摄入配置\n\n```python\nclass GitIngestReport:\n head_sha: str # 当前 HEAD 提交 SHA\n mode: str # \"snapshot\" 或 \"full\"\n commits_visited: int # 访问的提交数\n files_ingested: int # 摄入的文件数\n call_edges: int # 创建的调用关系边数\n```\n\n### Git 摄入模式\n\n| 模式 | 说明 | 适用场景 |\n|------|------|----------|\n| `snapshot`（默认） | 仅摄入 HEAD，快速初始化 | 首次摄入、日常使用 |\n| `full` | 遍历所有提交，完整历史 | 历史分析、时间旅行查询 |\n\n```bash\n# 快照模式（默认）\nthought ingest-git \n\n# 全量模式\nthought ingest-git --mode full\n```\n\n资料来源：[src/thought/ingest/code/git_pipeline.py:80-95]()\n\n### 代码实体存储配置\n\n每个代码实体存储以下元数据：\n\n| 字段 | 说明 |\n|------|------|\n| `code_file` | 代码文件相对路径 |\n| `code_language` | 编程语言（python, typescript, rust, php） |\n| `code_commit_sha` | 所在提交的 SHA |\n\n这些字段支持按代码文件和提交进行精确查询。资料来源：[src/thought/layers/code.py:30-50]()\n\n## 环境变量配置\n\n### 支持的环境变量\n\n| 变量名 | 说明 | 默认值 |\n|--------|------|--------|\n| `THOUGHT_DB_PATH` | 数据库文件路径 | `.thought/thought.db` |\n| `THOUGHT_CONFIG` | 配置文件路径 | `thought.toml` |\n\n环境变量在配置层级中优先级最低，可被 CLI 参数和 TOML 配置覆盖。\n\n## 配置验证与错误处理\n\n### 常见配置错误\n\n| 错误类型 | 原因 | 解决方案 |\n|----------|------|----------|\n| 数据库路径无效 | 父目录不存在 | 使用 `--db-path` 指定有效路径 |\n| TOML 解析失败 | 语法错误 | 检查配置文件格式 |\n| 嵌入器初始化失败 | 缺少可选依赖 | 安装 `sentence-transformers` 或使用 `auto` |\n| Hook 安装失败 | 权限不足 | 检查 `.claude` 目录写入权限 |\n\n### 备份与恢复\n\n系统自动执行以下备份：\n\n1. **数据库备份**：执行 `db flush` 前自动备份到 `.bak.`\n2. **配置文件备份**：安装 Hook/Client 前备份原配置到 `.thought.bak`\n\n```python\n# 自动备份示例\nif backup:\n shutil.copy(path, f\"{path}.thought.bak\")\n```\n\n## 配置最佳实践\n\n### 项目级配置\n\n- 使用默认的 `thought.toml` 配置文件\n- 将 `.thought/` 目录添加到 `.gitignore`\n- 通过 `.claude/settings.json` 版本控制 Hook 配置\n\n### 生产环境配置\n\n- 使用绝对路径指定数据库位置\n- 启用 `db backup` 定期备份\n- 生产环境建议显式指定嵌入器类型而非 `auto`\n\n### 团队协作\n\n- 项目级 Hook 配置应纳入版本控制\n- 数据库文件不应提交到代码仓库\n- 使用 `thought db inspect` 验证备份文件后再加载\n\n## 相关命令参考\n\n| 命令 | 功能 |\n|------|------|\n| `thought init` | 初始化配置和数据库 |\n| `thought db size` | 查看配置状态 |\n| `thought db backup` | 备份配置数据 |\n| `thought hook install` | 安装 Claude Code Hooks |\n| `thought client install` | 安装 MCP 客户端配置 |\n| `thought config show` | 显示当前配置 |\n\n---\n\n\n\n## 代码摄取与解析\n\n### 相关页面\n\n相关主题：[实体与关系管理](#page-entity-management), [图形层与图遍历](#page-graph-layer)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/ingest/code/pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/pipeline.py)\n- [src/thought/ingest/code/python_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/python_extractor.py)\n- [src/thought/ingest/code/typescript_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/typescript_extractor.py)\n- [src/thought/ingest/code/rust_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/rust_extractor.py)\n- [src/thought/ingest/code/php_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/php_extractor.py)\n- [src/thought/ingest/code/call_graph.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/call_graph.py)\n- [src/thought/ingest/code/git_pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/git_pipeline.py)\n \n\n# 代码摄取与解析\n\n## 概述\n\n代码摄取与解析是 thought-mcp 项目的核心子系统，负责将源代码文件解析为结构化的实体（Entity）和关系边（Edge），并存储到知识库中。该系统支持多种编程语言的 AST 解析、调用图构建、嵌入向量生成，以及 Git 历史感知的增量摄取。\n\n**核心职责：**\n\n- 使用 tree-sitter 解析多种语言的源代码\n- 提取函数、类、方法、模块等代码实体\n- 构建实体间的调用关系（Call Graph）\n- 生成语义嵌入向量以支持 VIBE 检索\n- 支持 Git 历史感知的多快照摄取\n\n资料来源：[src/thought/ingest/code/pipeline.py:1-50]()\n\n## 系统架构\n\n```mermaid\ngraph TD\n A[代码文件] --> B[语言检测]\n B --> C[对应语言 Extractor]\n C --> D[CodeEntity 列表]\n C --> E[CodeEdge 列表]\n D --> F[upsert_entity]\n E --> G[build_call_graph]\n G --> H[upsert_edge]\n F --> I[嵌入向量生成]\n I --> J[store_embedding]\n D --> K[source_id 生成]\n J --> L[(SQLite KB)]\n H --> L\n K --> F\n K --> G\n```\n\n### 核心组件\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| CodePipeline | `pipeline.py` | 主编排器，协调摄取流程 |\n| PythonExtractor | `python_extractor.py` | Python AST 解析 |\n| TypeScriptExtractor | `typescript_extractor.py` | TypeScript/JavaScript 解析 |\n| RustExtractor | `rust_extractor.py` | Rust AST 解析 |\n| PHPExtractor | `php_extractor.py` | PHP AST 解析 |\n| CallGraphBuilder | `call_graph.py` | 调用关系构建 |\n| GitPipeline | `git_pipeline.py` | Git 历史感知摄取 |\n| GitWalker | `git_walker.py` | Git 仓库遍历 |\n\n资料来源：[src/thought/ingest/code/pipeline.py:1-100]()\n\n## 语言支持与检测\n\n### 支持的语言\n\n系统通过文件扩展名自动检测编程语言：\n\n| 语言 | 扩展名 | Extractor |\n|------|--------|-----------|\n| Python | `.py` | PythonExtractor |\n| TypeScript | `.ts`, `.tsx` | TypeScriptExtractor |\n| Rust | `.rs` | RustExtractor |\n| PHP | `.php` | PHPExtractor |\n\n语言检测逻辑位于 `detect_language()` 函数，通过文件扩展名匹配对应的提取器。\n\n资料来源：[src/thought/ingest/code/pipeline.py:150-180]()\n\n## 实体提取流程\n\n### 通用提取模式\n\n每种语言的提取器遵循统一的接口模式：\n\n```python\ndef extract(source: str, file_path: str) -> tuple[list[CodeEntity], list[CodeEdge]]:\n parser = _get_parser()\n source_bytes = source.encode(\"utf-8\")\n tree = parser.parse(source_bytes)\n root = tree.root_node\n \n # 1. 创建模块实体\n entities.append(CodeEntity(...))\n \n # 2. 遍历 AST 节点\n _walk_module(root, ...)\n \n return entities, edges\n```\n\n所有提取器返回类型一致的 `CodeEntity` 列表和 `CodeEdge` 列表，确保下游处理逻辑统一。\n\n资料来源：[src/thought/ingest/code/python_extractor.py:80-100]()\n\n### 提取的实体类型\n\n| 实体类型 | 说明 | 典型属性 |\n|----------|------|----------|\n| `module` | 模块/文件 | `signature`, `docstring`, `visibility` |\n| `class` | 类定义 | `signature`, `docstring`, `visibility` |\n| `function` | 函数定义 | `signature`, `docstring`, `visibility` |\n| `method` | 类方法 | `signature`, `visibility`, `class` 属性 |\n| `import` | 导入语句 | `from_import` 属性 |\n\n资料来源：[src/thought/ingest/code/python_extractor.py:1-50]()\n\n### Python 提取器\n\nPython 提取器使用 tree-sitter-python 解析器，处理以下 AST 节点类型：\n\n- `module` → 模块实体\n- `class_definition` → 类实体\n- `function_definition` → 函数/方法实体\n- `import_statement` / `import_from_statement` → 导入边\n- `decorated_definition` → 装饰器处理\n\nPython 内置函数（`len`, `sum`, `.append` 等）被过滤，不生成实体，避免污染影响图。\n\n资料来源：[src/thought/ingest/code/python_extractor.py:50-80]()\n\n### TypeScript 提取器\n\nTypeScript 提取器额外处理：\n\n- **继承关系** (`INHERITS_FROM`)：解析 `extends` 和 `implements` 子句\n- **导出语句** (`export_statement`)：支持 `export class` / `export function` 递归解析\n\n```typescript\nclass Foo extends Bar implements Baz {}\n// 生成 INHERITS_FROM 边: Foo → Bar\n```\n\n资料来源：[src/thought/ingest/code/typescript_extractor.py:1-80]()\n\n### Rust 提取器\n\nRust 提取器处理 `function_item` 节点，并记录 `impl_type` 属性以关联方法与类型：\n\n```rust\nimpl TypeName {\n fn method(&self) {}\n}\n// 方法实体的 attrs 包含 {\"impl_type\": \"TypeName\"}\n```\n\n资料来源：[src/thought/ingest/code/rust_extractor.py:1-60]()\n\n### PHP 提取器\n\nPHP 提取器使用递归扫描处理嵌套结构：\n\n```php\n # 获取提交时的文件列表\ngit show : # 获取文件在特定提交的内容\n```\n\n资料来源：[src/thought/ingest/code/git_walker.py:1-50]()\n\n### Bi-temporal 模型\n\n摄取时记录 `code_commit_sha`，支持 bi-temporal 查询：\n\n- `valid_from` / `valid_until`：实体的有效时间范围\n- `as_of_kind='valid'`：查询特定日期的代码状态\n- `as_of_kind='learned'`：查询系统在该日期学到的知识\n\n```python\neid = self._backend.upsert_entity(\n code_commit_sha=commit_sha, # 关联到特定提交\n ...\n)\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:100-150]()\n\n## 嵌入向量生成\n\n### VIBE 检索支持\n\n为每个代码实体生成嵌入向量，支持通过意图（而非精确名称）检索：\n\n```python\nembed_text_parts = [ent.name, ent.signature]\nif ent.docstring:\n embed_text_parts.append(ent.docstring)\nembed_text = \"\\n\".join(p for p in embed_text_parts if p)\nvec = self._embedder.embed(embed_text)\nself._backend.store_embedding(\n entity_id=eid,\n model_name=self._embedder.model_name,\n model_version=self._embedder.model_version,\n dim=self._embedder.dim,\n vector=vector_to_bytes(vec),\n)\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:120-140]()\n\n### 自动嵌入器选择\n\n系统支持自动选择嵌入器：\n\n- 优先使用 `sentence-transformers`（如已安装）\n- 回退到确定性嵌入器（`auto` 模式）\n\n```python\n# auto embedder selector\nif importlib.util.find_spec(\"sentence_transformers\") is not None:\n return SentenceTransformerEmbedder()\nreturn DeterministicEmbedder()\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:150-180]()\n\n## 事务与存储\n\n### 原子性保证\n\n每个文件的摄取在单个事务中完成：\n\n```python\nself._backend.begin()\ntry:\n name_to_id, embeddings_created = self._write_entities(...)\n edge_ids, unresolved = self._write_edges(...)\n self._backend.commit()\nexcept Exception:\n self._backend.rollback()\n raise\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:180-220]()\n\n### 实体唯一性\n\n实体的唯一标识包含 `(code_file, code_commit_sha)`，确保同一函数在不同文件或不同提交中不会合并：\n\n```python\n# upsert_entity identity now includes (code_file, code_commit_sha)\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:60-80]()\n\n## 增量扫描\n\n### ScanLog\n\n系统维护 `scan_log` 表记录扫描历史，支持增量摄取：\n\n```python\ndef scan(repo_path: str, agent: str | None = None, since: str | None = None, max_files: int | None = None, note: str | None = None):\n \"\"\"Incremental code-scan primitive. Walks repo_path, ingests changed/new files,\n records a row in scan_log so the next call picks up where this one left off.\"\"\"\n```\n\n每次扫描后记录时间戳，下次调用时跳过已处理的变更。\n\n资料来源：[src/thought/server.py:1-50]()\n\n## 配置与使用\n\n### CLI 命令\n\n| 命令 | 说明 |\n|------|------|\n| `thought ingest-git ` | Git 历史摄取 |\n| `thought ingest-code ` | 单文件/目录摄取 |\n| `thought callers ` | 查询直接调用者 |\n| `thought impact ` | 查询影响集合 |\n| `thought diff --from --to ` | 提交间差异 |\n\n### 初始化配置\n\n```python\n@app.command()\ndef init(\n config: Path = typer.Option(\"thought.toml\"),\n db_path: str = typer.Option(\".thought/thought.db\"),\n embedder: str = typer.Option(\"auto\"),\n write_claude_md: bool = typer.Option(True),\n quick: bool = typer.Option(False),\n):\n```\n\n资料来源：[src/thought/cli.py:1-50]()\n\n## 数据模型\n\n### CodeEntity\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `name` | str | 实体名称 |\n| `type_` | str | 实体类型（module/class/function/method） |\n| `language` | str | 编程语言 |\n| `file_path` | str | 文件路径 |\n| `line_start` | int | 起始行号 |\n| `line_end` | int | 结束行号 |\n| `signature` | str | 函数签名 |\n| `docstring` | str | 文档字符串 |\n| `visibility` | str | 可见性（public/private） |\n| `attrs` | dict | 额外属性 |\n\n### CodeEdge\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `source_name` | str | 源实体名称 |\n| `target_name` | str | 目标实体名称 |\n| `relation_type` | str | 关系类型（CALLS/DEFINES/IMPORTS） |\n| `line_number` | int | 关联代码行号 |\n| `attrs` | dict | 额外属性（如 `from_import`） |\n\n资料来源：[src/thought/ingest/code/python_extractor.py:20-50]()\n\n## 扩展新的语言\n\n要添加新的语言支持，需实现以下步骤：\n\n1. **创建提取器文件**：如 `newlang_extractor.py`\n2. **实现 `extract()` 函数**：返回 `list[CodeEntity]` 和 `list[CodeEdge]`\n3. **注册语言检测**：在 `pipeline.py` 的 `detect_language()` 中添加扩展名映射\n4. **安装 tree-sitter 语法**：确保 tree-sitter-{lang} 可用\n\n```python\ndef extract(source: str, file_path: str) -> tuple[list[CodeEntity], list[CodeEdge]]:\n parser = _get_parser()\n source_bytes = source.encode(\"utf-8\")\n tree = parser.parse(source_bytes)\n root = tree.root_node\n # ... 遍历 AST，生成实体和边\n return entities, edges\n\n---\n\n\n\n## 实体与关系管理\n\n### 相关页面\n\n相关主题：[代码摄取与解析](#page-code-ingestion), [记忆模型与检索](#page-memory-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/ingest/code/types.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/types.py)\n- [src/thought/ingest/code/python_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/python_extractor.py)\n- [src/thought/ingest/code/typescript_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/typescript_extractor.py)\n- [src/thought/ingest/code/rust_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/rust_extractor.py)\n- [src/thought/ingest/code/call_graph.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/call_graph.py)\n- [src/thought/ingest/code/pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/pipeline.py)\n- [src/thought/layers/code.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/code.py)\n- [src/thought/models.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/models.py)\n \n\n# 实体与关系管理\n\n## 概述\n\n实体与关系管理是 thought-mcp 的核心子系统，负责从代码库中提取结构化实体（函数、类、模块、方法等）及其关系（CALLS、IMPORTS、DEFINES、INHERITS_FROM 等），并将这些信息持久化到知识库中供后续查询使用。\n\n该系统基于树形语法解析器（tree-sitter）实现多语言代码解析，采用双向时态数据模型记录实体的生命周期，并通过 PageRank 算法实现智能调用链分析。\n\n资料来源：[src/thought/ingest/code/types.py:1-50]()\n\n## 核心数据模型\n\n### CodeEntity 代码实体\n\n`CodeEntity` 是代码提取阶段产生的中间数据结构，代表代码库中的一个可识别元素：\n\n```python\n@dataclass\nclass CodeEntity:\n name: str # 实体名称\n type_: str # 实体类型 (function, class, method, module...)\n language: str # 编程语言 (python, typescript, rust...)\n file_path: str # 文件路径\n line_start: int # 起始行号\n line_end: int # 结束行号\n signature: str | None = None # 函数/方法签名\n docstring: str | None = None # 文档字符串\n visibility: str = \"public\" # 可见性 (public, private, protected)\n attrs: dict[str, object] = field(default_factory=dict) # 扩展属性\n```\n\n资料来源：[src/thought/ingest/code/types.py:10-22]()\n\n### CodeEdge 代码关系\n\n`CodeEdge` 描述两个代码实体之间的关系：\n\n```python\n@dataclass\nclass CodeEdge:\n source_name: str # 源实体名称\n target_name: str # 目标实体名称\n relation_type: str # 关系类型\n line_number: int | None = None # 定义行号\n attrs: dict[str, object] = field(default_factory=dict) # 扩展属性\n```\n\n资料来源：[src/thought/ingest/code/types.py:24-31]()\n\n### Entity 与 Edge (存储模型)\n\n存储层使用 pydantic 模型定义实体和边的结构：\n\n```python\nclass Entity(BaseModel):\n id: str\n type: str\n name: str\n canonical_name: str\n scope: ScopeName # shared | private\n tier: Tier # hot | warm | cold\n importance: float = Field(ge=0.0, le=1.0)\n valid_from: datetime # 有效起始时间（双向时态）\n valid_until: datetime | None = None # 有效结束时间（NULL 表示当前有效）\n learned_at: datetime # 系统学习时间\n code_file: str | None = None # 代码文件路径\n code_language: str | None = None # 代码语言\n code_commit_sha: str | None = None # Git 提交 SHA\n access_count: int = 0\n attrs: dict[str, object] = Field(default_factory=dict)\n```\n\n资料来源：[src/thought/models.py:58-76]()\n\n## 实体类型分类\n\n| 类型 | 描述 | 示例 |\n|------|------|------|\n| `function` | 函数定义 | Python `def func()` |\n| `class` | 类定义 | Python `class Foo:` |\n| `method` | 类方法 | Rust `fn method(&self)` |\n| `module` | 模块/文件 | 每个代码文件 |\n| `interface` | 接口定义 | TypeScript `interface Foo` |\n| `struct` | 结构体 | Rust `struct Foo` |\n\n资料来源：[src/thought/ingest/code/python_extractor.py:40-48]()\n\n## 关系类型分类\n\n| 关系类型 | 描述 | 方向 |\n|----------|------|------|\n| `CALLS` | 函数调用关系 | source → target |\n| `DEFINES` | 定义关系 | class/module → method/function |\n| `INHERITS_FROM` | 继承关系 | 子类 → 父类 |\n| `IMPORTS` | 导入关系 | 模块 → 被导入模块 |\n| `CONTRADICTS` | 矛盾关系 | 用于事实校正 |\n\n资料来源：[src/thought/ingest/code/typescript_extractor.py:80-90]()\n\n## 多语言代码提取架构\n\n### 提取器注册表\n\n系统通过懒加载方式注册各语言的提取器：\n\n```python\n_LOADERS = {\n \"python\": _python_extractor,\n \"typescript\": _typescript_extractor,\n \"go\": _go_extractor,\n \"rust\": _rust_extractor,\n \"java\": _java_extractor,\n \"php\": _php_extractor,\n}\n```\n\n资料来源：[src/thought/ingest/code/ast_extractor.py:30-44]()\n\n### Python 提取器\n\nPython 提取器使用 tree-sitter-python 解析代码 AST：\n\n1. **模块实体**：为每个文件创建模块节点\n2. **函数扫描**：遍历 `function_definition` 节点\n3. **类扫描**：遍历 `class_definition` 节点\n4. **继承关系**：从类定义的 `base_clause` 提取父类\n5. **导入关系**：处理 `import_statement` 和 `import_from_statement`\n\n```python\ndef extract(source: str, file_path: str) -> tuple[list[CodeEntity], list[CodeEdge]]:\n parser = _get_parser()\n tree = parser.parse(source_bytes)\n # 创建模块实体，遍历 AST 提取函数/类/导入\n```\n\n资料来源：[src/thought/ingest/code/python_extractor.py:50-72]()\n\n### TypeScript 提取器\n\nTypeScript 提取器扩展了 Python 提取器的模式，增加了：\n\n- **可见性修饰符**：从 `accessibility_modifier` 节点提取\n- **接口支持**：处理 `interface_declaration`\n- **类型别名**：处理 `type_alias_declaration`\n- **命名空间**：处理 `namespace_declaration`\n\n```python\n# 继承关系提取\nfor hc in heritage.named_children:\n if hc.type == \"extends_clause\":\n parent = _text(v, source_bytes)\n out_edges.append(CodeEdge(\n source_name=class_name,\n target_name=parent,\n relation_type=\"INHERITS_FROM\",\n ))\n```\n\n资料来源：[src/thought/ingest/code/typescript_extractor.py:60-90]()\n\n### Rust 提取器\n\nRust 提取器处理特有的语言结构：\n\n- **结构体**：从 `struct_item` 节点提取\n- **impl 块**：关联方法与类型\n- **可见性**：从 `visibility` 节点提取（`pub`, `pub(crate)` 等）\n\n```python\nout_entities.append(CodeEntity(\n name=qualified,\n type_=\"method\",\n language=\"rust\",\n attrs={\"impl_type\": type_name}, # 关联 impl 块\n))\n```\n\n资料来源：[src/thought/ingest/code/rust_extractor.py:40-50]()\n\n### 语言支持矩阵\n\n```mermaid\ngraph LR\n A[源代码文件] --> B{语言检测}\n B -->|Python| C[python_extractor]\n B -->|TypeScript| D[typescript_extractor]\n B -->|Rust| E[rust_extractor]\n B -->|Go| F[go_extractor]\n B -->|Java| G[java_extractor]\n B -->|PHP| H[php_extractor]\n \n C --> I[CodeEntity + CodeEdge]\n D --> I\n E --> I\n F --> I\n G --> I\n H --> I\n```\n\n## 调用图构建\n\n调用图是理解代码依赖关系的关键组件。系统通过静态分析构建 CALLS 关系。\n\n### 解析策略\n\ncall_graph.py 实现三层解析策略：\n\n```mermaid\ngraph TD\n A[调用表达式] --> B{方法调用?}\n B -->|是| C[尝试同文件匹配]\n B -->|否| D{有qualifier?}\n \n C --> E[1. 同文件精确匹配]\n D --> F[Qualified 匹配]\n \n E --> G{找到?}\n F --> H[2. Qualified 后缀匹配]\n G -->|否| I[3. 跨文件裸名匹配]\n G -->|是| J[建立 CALLS 边]\n \n H --> K{唯一匹配?}\n I --> L[建立 CALLS 边]\n K -->|是| J\n```\n\n1. **同文件方法调用**：直接通过方法名匹配当前文件的类方法\n2. **唯一 Qualified 后缀匹配**：查找 `ClassName.method` 格式的唯一匹配\n3. **跨文件裸名匹配**：在其他文件中查找同名函数\n\n资料来源：[src/thought/ingest/code/call_graph.py:60-90]()\n\n### 解析示例\n\n```python\n# 解析 obj.method() 调用\ntarget_name = _resolve_method_call(node, source_bytes, file_path, backend, ...)\n# 目标名称可能为:\n# - \"ClassName.method\" (qualified)\n# - \"function_name\" (bare)\n```\n\n## 存储管道\n\n### 实体写入流程\n\n```mermaid\ngraph TD\n A[CodeEntity 列表] --> B[计算规范名称]\n B --> C[upsert_entity]\n C --> D[生成 embedding]\n D --> E[store_embedding]\n \n F[Entity ID 映射] <-- G[name_to_id 字典]\n E --> G\n```\n\n```python\ndef _write_entities(self, entities, scope, owner_id, source_id, commit_sha, language, now):\n eid = self._backend.upsert_entity(\n type_=ent.type_,\n name=ent.name,\n scope=scope,\n valid_from=now,\n code_file=ent.file_path,\n code_language=language,\n code_commit_sha=commit_sha,\n )\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:80-110]()\n\n### 身份去重策略\n\n实体标识包含 `(name, code_file, code_commit_sha)` 三元组，确保同名函数在不同文件或不同提交中不会合并：\n\n```python\n# upsert_entity 身份: (name, code_file, code_commit_sha)\n# 这允许:\n# - auth.py::authenticate (v1.0)\n# - auth.py::authenticate (v2.0) # 视为不同实体\n```\n\n## 代码查询层\n\n### CodeLayer 接口\n\n`CodeLayer` 提供程序员友好的查询接口：\n\n| 方法 | 功能 |\n|------|------|\n| `callers_of(name)` | 谁调用了这个函数？（直接调用者，按 PageRank 排序）|\n| `callees_of(name)` | 这个函数调用了什么？（直接调用，限包内）|\n| `impact_set(name)` | 变更这个的影响范围（传递调用者，PageRank 排序）|\n| `defines_in_file(path)` | 文件中定义的所有实体 |\n\n资料来源：[src/thought/layers/code.py:20-35]()\n\n### Personalized PageRank 查询\n\n系统使用 HippoRAG 风格的双向 PageRank 遍历进行调用者排名：\n\n```python\ndef callers_of(self, name: str) -> list[CodeHit]:\n entity_id = self._resolve_entity_id(name)\n # 执行 PPR 查询，返回按重要性排序的调用者\n```\n\n### 影响集分析\n\n`impact_set` 执行传递闭包查询：\n\n```\n影响集 = 直接调用者 + 间接调用者（递归向上遍历）\n```\n\n这回答了 \"如果我修改这个函数，哪些代码会受影响？\" 的问题。\n\n## 双向时态模型\n\n系统采用 bi-temporal 模型记录实体生命周期：\n\n```mermaid\ngantt\n title 双向时态模型示意\n dateFormat X\n axisFormat %s\n \n section Valid Time\n v1.0 实体存在 :0, 100\n \n section Learned Time\n 被学习 :10, 120\n 被更正 :80, 120\n```\n\n| 时间轴 | 字段 | 语义 |\n|--------|------|------|\n| 有效时间 | `valid_from` / `valid_until` | 事实本身何时为真 |\n| 学习时间 | `learned_at` / `unlearned_at` | 系统何时获知该事实 |\n\n`as_of` 查询可以回溯历史状态：\n\n- `as_of_kind='valid'` → \"日期 X 时什么为真\"\n- `as_of_kind='learned'` → \"系统日期 X 时知道什么\"\n\n## Git 感知摄取\n\n### 快照模式 vs 完整模式\n\n| 模式 | 行为 | 适用场景 |\n|------|------|----------|\n| `snapshot` | 仅摄取 HEAD | 快速初始化 |\n| `full` | 遍历每个提交 | 历史分析、时间旅行查询 |\n\n```python\nGitWalker # 纯子进程实现，无原生依赖\n# 每个实体记录其 commit_sha\n```\n\n### 差异查询\n\n```bash\nthought diff --from --to \n# 输出: 新增实体列表 / 移除实体列表\n```\n\n## 配置与初始化\n\n### 数据库初始化\n\n```bash\nthought init --db-path .thought/thought.db\n# 创建数据库文件 + 配置文件 + CLAUDE.md\n```\n\n### 嵌入器选择\n\n```python\nembedder: str = typer.Option(\n \"auto\", # 自动选择 sentence-transformers 或确定性嵌入\n)\n```\n\n## 扩展阅读\n\n| 功能 | 文档 |\n|------|------|\n| CLI 命令参考 | CHANGELOG.md |\n| 数据库后端 | SQLite 存储层 |\n| 调用图构建 | call_graph.py |\n| 演示用例 | demo.py |\n\n---\n\n\n\n## 记忆模型与检索\n\n### 相关页面\n\n相关主题：[查询系统](#page-query-system), [图形层与图遍历](#page-graph-layer), [实体与关系管理](#page-entity-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/memory.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/memory.py)\n- [src/thought/hooks/recall.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/hooks/recall.py)\n- [src/thought/layers/graph.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/graph.py)\n- [src/thought/layers/vector.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/vector.py)\n- [src/thought/layers/temporal.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/temporal.py)\n- [src/thought/layers/code.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/code.py)\n- [src/thought/ingest/code/pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/pipeline.py)\n- [src/thought/query/ask.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/query/ask.py)\n \n\n# 记忆模型与检索\n\n## 概述\n\nThought-MCP 的**记忆模型与检索系统**是一个双时态（bi-temporal）的知识图谱存储与查询引擎，旨在为 AI 代理提供持久化、可追溯的上下文记忆能力。该系统将实体（Entity）、关系（Edge）和向量嵌入（Embedding）统一存储在 SQLite 数据库中，支持时间旅行查询、自然语言查询和代码语义检索。\n\n核心设计目标：\n\n- **持久化记忆**：让 AI 代理在不同会话之间保留关键上下文\n- **双时态模型**：区分\"何时发生\"（valid_time）和\"何时学习\"（learned_at）\n- **语义检索**：结合向量相似度和图关系的混合检索\n- **代码理解**：支持函数调用图、影响分析和代码追溯\n\n资料来源：[src/thought/memory.py:1-50]()\n\n## 架构概览\n\n```mermaid\ngraph TB\n subgraph \"数据摄取层\"\n CI[代码摄取 Pipeline]\n GI[Git 历史摄取]\n HI[Hook 事件摄取]\n end\n\n subgraph \"存储层\"\n SQ[SQLite Backend]\n EM[Embedding 存储]\n end\n\n subgraph \"查询层\"\n REC[recall 召回]\n ASK[ask 自然语言]\n CODE[code 代码查询]\n GRAPH[graph 图查询]\n end\n\n CI --> SQ\n GI --> SQ\n HI --> SQ\n SQ --> EM\n REC --> EM\n ASK --> GRAPH\n CODE --> GRAPH\n GRAPH --> SQ\n```\n\n### 核心组件关系\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| `Memory` | 顶层 API 聚合器，协调各层 | `memory.py` |\n| `SQLiteBackend` | 数据库 CRUD 操作核心 | `storage/sqlite/backend.py` |\n| `VectorLayer` | 向量嵌入存储与相似度搜索 | `layers/vector.py` |\n| `GraphLayer` | 图关系查询与 PageRank | `layers/graph.py` |\n| `TemporalLayer` | 双时态时间旅行查询 | `layers/temporal.py` |\n| `CodeLayer` | 代码专用查询接口 | `layers/code.py` |\n\n资料来源：[src/thought/memory.py:50-120]()\n\n---\n\n## 双时态数据模型\n\n### 时态维度的定义\n\nThought-MCP 采用**双时态模型**（Bi-temporal Model）来区分事实的两个时间维度：\n\n```mermaid\ngraph LR\n A[事件发生] -->|valid_time| B[事实的有效期]\n C[系统学习] -->|learned_at| D[知识的入库时间]\n```\n\n**两个时间戳字段：**\n\n| 字段 | 含义 | 典型场景 |\n|------|------|----------|\n| `valid_from` / `valid_until` | 事实本身在现实世界的时间范围 | \"2024 年 1 月用户修改了密码\" |\n| `learned_at` | 系统何时将该事实记录到数据库 | \"系统在 2024 年 3 月才导入这条记录\" |\n\n这种设计允许系统回答两类时间查询：\n\n- **`as_of_kind='valid'`**：查询\"在某个时间点，什么是真实的？\"\n- **`as_of_kind='learned'`**：查询\"在某个时间点，系统知道什么？\"\n\n资料来源：[src/thought/layers/temporal.py:1-60]()\n\n### 时间旅行查询示例\n\n```cypher\n-- 查询 2024 年 1 月 1 日系统所知道的所有实体\nMATCH (e:Entity)\nWHERE e.learned_at <= datetime('2024-01-01')\n AND (e.valid_until IS NULL OR e.valid_until > datetime('2024-01-01'))\nRETURN e\nAS_OF '2024-01-01'\n```\n\nCLI 命令行支持时间旅行：\n\n```bash\nthought recall \"用户配置文件\" --as-of 2024-01-01 --as-of-kind learned\n```\n\n资料来源：[src/thought/layers/temporal.py:80-120]()\n\n---\n\n## 实体与关系模型\n\n### Entity 数据结构\n\n```python\n@dataclass\nclass Entity:\n id: str # 实体唯一标识\n type_: str # 实体类型 (function, class, module, fact, claim...)\n name: str # 实体名称\n scope: ScopeName # 作用域 (shared, agent, project)\n owner_id: str | None # 所有者\n valid_from: datetime # 有效起始时间\n valid_until: datetime | None # 有效结束时间\n learned_at: datetime # 入库时间\n source_ref: str | None # 原始来源引用\n tier: str # 热度层级 (hot, warm, cold)\n attrs: dict # 扩展属性 (signature, visibility, line_start...)\n code_file: str | None # 代码文件路径 (代码实体)\n code_language: str | None # 编程语言 (代码实体)\n code_commit_sha: str | None # Git commit SHA (代码实体)\n```\n\n资料来源：[src/thought/memory.py:100-150]()\n\n### Edge 关系类型\n\n| 关系类型 | 含义 | 适用场景 |\n|----------|------|----------|\n| `CALLS` | 函数调用关系 | 代码分析 |\n| `INHERITS_FROM` | 类继承关系 | 代码分析 |\n| `DEFINES` | 定义关系 | 代码分析 |\n| `IMPORTS` | 模块导入关系 | 代码分析 |\n| `CONTRADICTS` | 矛盾关系 | 法律/研究取证 |\n| `SUPPORTS` | 支持关系 | 学术研究 |\n| `RELATED` | 通用关联 | 通用记忆 |\n\n资料来源：[src/thought/ingest/code/typescript_extractor.py:50-100]()\n\n### SQLite 表结构\n\n```sql\nCREATE TABLE entities (\n id TEXT PRIMARY KEY,\n type_ TEXT NOT NULL,\n name TEXT NOT NULL,\n scope TEXT DEFAULT 'shared',\n owner_id TEXT,\n valid_from TIMESTAMP NOT NULL,\n valid_until TIMESTAMP,\n learned_at TIMESTAMP NOT NULL,\n source_ref TEXT,\n tier TEXT DEFAULT 'hot',\n attrs TEXT, -- JSON\n code_file TEXT,\n code_language TEXT,\n code_commit_sha TEXT\n);\n\nCREATE TABLE edges (\n id TEXT PRIMARY KEY,\n source_id TEXT NOT NULL,\n target_id TEXT NOT NULL,\n relation_type TEXT NOT NULL,\n valid_from TIMESTAMP NOT NULL,\n valid_until TIMESTAMP,\n learned_at TIMESTAMP NOT NULL,\n attrs TEXT -- JSON\n);\n\nCREATE TABLE embeddings (\n entity_id TEXT NOT NULL,\n model_name TEXT NOT NULL,\n model_version TEXT,\n dim INTEGER NOT NULL,\n vector BLOB NOT NULL,\n created_at TIMESTAMP NOT NULL,\n FOREIGN KEY (entity_id) REFERENCES entities(id)\n);\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:150-200]()\n\n---\n\n## 向量检索层\n\n### VectorLayer 功能\n\n`VectorLayer` 负责将文本语义转换为向量表示，并支持相似度搜索：\n\n```python\nclass VectorLayer:\n def __init__(self, backend: SQLiteBackend, embedder: Embedder) -> None:\n self._backend = backend\n self._embedder = embedder\n\n def search(\n self,\n query: str,\n *,\n limit: int = 10,\n scope: str = \"all\",\n owner_id: str | None = None,\n ) -> list[VectorHit]:\n \"\"\"语义相似度搜索\"\"\"\n vec = self._embedder.embed(query)\n # 余弦相似度计算\n ...\n```\n\n资料来源：[src/thought/layers/vector.py:20-80]()\n\n### 支持的 Embedder 类型\n\n| Embedder | 描述 | 配置方式 |\n|----------|------|----------|\n| `OllamaEmbedder` | Ollama 原生嵌入 API | `provider = \"ollama\"` |\n| `LMStudioEmbedder` | LM Studio 嵌入 | `provider = \"lmstudio\"` |\n| `OpenAICompatEmbedder` | OpenAI 兼容 API | `provider = \"openai-compat\"` |\n| `DeterministicEmbedder` | 确定性哈希（无外部依赖） | 自动降级 |\n\n资料来源：[src/thought/memory.py:200-250]()\n\n### 嵌入时机\n\n代码实体的嵌入发生在摄取阶段：\n\n```python\n# 在 pipeline.py 的 _write_entities 中\nembed_text_parts = [ent.name, ent.signature]\nif ent.docstring:\n embed_text_parts.append(ent.docstring)\nembed_text = \"\\n\".join(p for p in embed_text_parts if p)\n\nif embed_text.strip():\n vec = self._embedder.embed(embed_text)\n self._backend.store_embedding(\n entity_id=eid,\n model_name=self._embedder.model_name,\n model_version=self._embedder.model_version,\n dim=self._embedder.dim,\n vector=vector_to_bytes(vec),\n )\n```\n\n资料来源：[src/thought/ingest/code/pipeline.py:120-150]()\n\n---\n\n## 图查询层\n\n### GraphLayer 功能\n\n`GraphLayer` 提供基于图结构的查询能力，核心是 **Personalized PageRank** 算法：\n\n```python\nclass GraphLayer:\n def __init__(self, backend: SQLiteBackend) -> None:\n self._backend = backend\n\n def personalized_pagerank(\n self,\n seed_ids: list[str],\n *,\n damping: float = 0.85,\n iterations: int = 20,\n convergence: float = 1e-6,\n ) -> dict[str, float]:\n \"\"\"基于种子节点的 PageRank 计算\"\"\"\n ...\n```\n\n资料来源：[src/thought/layers/graph.py:30-80]()\n\n### 典型图查询\n\n#### 直接调用者查询\n\n```python\ndef callers_of(self, name: str, *, limit: int = 10) -> list[CodeHit]:\n \"\"\"查找直接调用某函数的实体，PageRank 加权排序\"\"\"\n seed_ids = self._resolve_entity_id(name)\n if not seed_ids:\n return []\n # 逆向追踪 CALLS 边\n return self._query_callers(seed_ids, limit=limit)\n```\n\n#### 影响分析查询\n\n```python\ndef impact_set(self, name: str, *, limit: int = 50) -> list[CodeHit]:\n \"\"\"传递性调用者集合：修改某函数会影响哪些代码\"\"\"\n seed_ids = self._resolve_entity_id(name)\n if not seed_ids:\n return []\n # 递归追踪所有调用链\n return self._transitive_closure(seed_ids, direction=\"incoming\")\n```\n\n资料来源：[src/thought/layers/code.py:50-120]()\n\n---\n\n## 检索 API\n\n### recall - 语义召回\n\n`recall` 是基础的语义搜索接口：\n\n```python\ndef recall(\n self,\n query: str,\n *,\n max_results: int = 10,\n scope: str = \"all\",\n owner_id: str | None = None,\n since: str | None = None,\n before: str | None = None,\n) -> list[Entity]:\n \"\"\"语义相似度召回\"\"\"\n```\n\n**特点**：\n\n- 默认返回最多 10 条结果\n- 支持时间范围过滤 (`since`, `before`)\n- 支持作用域过滤 (`scope`, `owner_id`)\n- 结合向量相似度和图关系\n\n资料来源：[src/thought/hooks/recall.py:50-100]()\n\n### ask - 自然语言查询\n\n`ask` 将自然语言转换为 Cypher 查询：\n\n```python\ndef ask(\n memory,\n question: str,\n *,\n llm_cfg: object | None = None,\n scope: str = \"all\",\n owner_id: str | None = None,\n no_fallback: bool = False,\n) -> AskResult:\n \"\"\"自然语言 → Cypher 查询\"\"\"\n```\n\n**工作流程**：\n\n```mermaid\ngraph LR\n Q[自然语言问题] --> LLM[LLM 翻译]\n LLM --> C[Cypher 查询]\n C --> V{验证通过?}\n V -->|是| EX[执行查询]\n V -->|否| FB[recall 降级]\n EX --> R[返回结果]\n FB --> R\n```\n\n**约束条件**：\n\n- 仅使用只读 Cypher 特性（MATCH, WHERE, RETURN, LIMIT）\n- 禁止使用 MERGE/CREATE/DELETE/SET\n- 支持 `AS_OF 'iso-date'` 进行时间旅行\n\n资料来源：[src/thought/query/ask.py:30-100]()\n\n### 代码专用查询\n\n`CodeLayer` 提供程序员友好的接口：\n\n| 方法 | 作用 | CLI 命令 |\n|------|------|----------|\n| `callers_of(name)` | 直接调用者 | `thought callers ` |\n| `callees_of(name)` | 直接被调用者 | `thought callees ` |\n| `impact_set(name)` | 传递性影响集合 | `thought impact ` |\n| `defines_in_file(path)` | 文件内定义 | - |\n\n资料来源：[src/thought/layers/code.py:1-50]()\n\n---\n\n## 增量扫描与工作上下文\n\n### agent_scan 增量扫描\n\n`agent_scan` 专为 AI 代理循环设计，支持增量更新：\n\n```python\ndef agent_scan(\n self,\n repo_path: str,\n *,\n agent: str | None = None,\n since: str | None = None,\n max_files: int | None = None,\n language: str | None = None,\n) -> dict:\n \"\"\"增量代码扫描\"\"\"\n # 1. 查找上次扫描的 head_sha 作为 since 起点\n # 2. 获取 Git 差异文件\n # 3. 仅处理变更/新增文件\n # 4. 退休已删除文件的实体\n # 5. 返回扫描报告\n```\n\n**返回值结构**：\n\n```python\n{\n \"scan_id\": \"...\",\n \"files_scanned\": 15,\n \"files_changed\": 3,\n \"entities_added\": 42,\n \"entities_retired\": 5,\n \"edges_added\": 38,\n \"edges_retired\": 2,\n \"duration_ms\": 1234\n}\n```\n\n资料来源：[src/thought/memory.py:150-220]()\n\n### working_context 临时上下文\n\n`working_context` 管理会话内的临时上下文：\n\n```python\ndef working_context(\n self,\n action: Literal[\"push\", \"pop\", \"peek\", \"list\"],\n *,\n text: str | None = None,\n scope: str = \"shared\",\n) -> list[str]:\n \"\"\"LIFO 栈式上下文管理\"\"\"\n```\n\n- `push`：添加上下文片段到栈顶\n- `pop`：移除并返回栈顶\n- `peek`：查看栈顶（不移除）\n- `list`：列出所有上下文\n\n资料来源：[src/thought/memory.py:220-280]()\n\n---\n\n## Git 历史感知\n\n### 快照模式 vs 完整模式\n\n```mermaid\ngraph TB\n subgraph \"snapshot 模式 (默认)\"\n F1[HEAD commit]\n F1 --> E1[实体 + HEAD SHA]\n end\n\n subgraph \"full 模式\"\n F2[所有 commits]\n F2 --> E2[每个实体 + 对应 commit SHA]\n end\n```\n\n| 模式 | 速度 | 查询能力 |\n|------|------|----------|\n| `--mode snapshot` | 快，仅 HEAD | 仅当前代码 |\n| `--mode full` | 慢，遍历全部 | 支持历史时间旅行 |\n\n资料来源：[src/thought/ingest/code/git_pipeline.py:50-100]()\n\n### 差异查询\n\n```bash\n# 对比两个 commit 之间的代码变更\nthought diff --from abc123 --to def456\n\n# 输出\n# ADDED: Entity[Foo] in bar.py\n# REMOVED: Entity[Baz] in qux.py\n```\n\n资料来源：[src/thought/ingest/code/git_pipeline.py:100-150]()\n\n---\n\n## 配置与初始化\n\n### 初始化命令\n\n```bash\nthought init --db-path .thought/thought.db --embedder auto\n```\n\n**参数说明**：\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `--db-path` | `.thought/thought.db` | SQLite 数据库路径 |\n| `--embedder` | `auto` | 嵌入模型选择 |\n| `--write-claude-md` | `true` | 生成 CLAUDE.md |\n| `--quick` | `false` | 跳过嵌入模型预热 |\n\n### 自动备份\n\n所有破坏性操作（flush, load）前自动备份：\n\n```\n.bak.\n```\n\n资料来源：[src/thought/cli.py:100-150]()\n\n---\n\n## 总结\n\nThought-MCP 的记忆模型与检索系统通过以下设计实现持久化 AI 记忆：\n\n1. **双时态模型**：区分事实有效期与知识入库时间，支持精确的时间旅行查询\n2. **混合存储**：结合 SQLite 图关系与向量嵌入，兼顾结构化查询与语义搜索\n3. **分层 API**：recall（语义）、ask（自然语言）、code（代码专用）满足不同场景\n4. **增量感知**：agent_scan + Git 差异追踪实现高效的增量更新\n5. **影响分析**：PageRank 加权的传递闭包计算，精确回答\"改这个会影响什么\"\n\n这套系统使 AI 代理能够在多会话环境中保持上下文连续性，同时支持深度的代码理解和追溯分析。\n\n---\n\n\n\n## 查询系统\n\n### 相关页面\n\n相关主题：[记忆模型与检索](#page-memory-model), [图形层与图遍历](#page-graph-layer)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/query/cypher.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/query/cypher.py)\n- [src/thought/query/ask.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/query/ask.py)\n- [src/thought/query/views.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/query/views.py)\n- [src/thought/router/classifier.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/router/classifier.py)\n- [src/thought/router/rules.yaml](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/router/rules.yaml)\n \n\n# 查询系统\n\n## 概述\n\n查询系统（Query System）是 thought-mcp 的核心组件之一，负责将用户的自然语言查询转换为知识图谱查询并返回结果。该系统支持多种查询类型，包括直接记忆检索（recall）、自然语言到 Cypher 查询的翻译（ask）、代码图谱查询（callers/callees/impact）等场景。\n\n查询系统的设计目标是为用户提供透明的查询接口，无需了解底层图数据库的查询语言即可完成复杂的信息检索任务。系统采用分层架构，通过路由器（Router）进行意图分类，再交由对应的查询处理器执行。\n\n资料来源：[src/thought/query/ask.py:1-15]()\n\n## 架构设计\n\n### 系统分层\n\n查询系统采用三层架构设计：\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 路由层 | Router / Classifier | 解析用户意图，分类查询类型 |\n| 转换层 | Ask / Cypher | 自然语言转 Cypher，查询验证 |\n| 执行层 | Backend / Storage | 执行查询，返回结果 |\n\n```mermaid\ngraph TD\n A[用户自然语言查询] --> B[Router 意图分类]\n B --> C{查询类型}\n C -->|RECALL| D[recall 直接检索]\n C -->|CODE| E[CodeLayer 代码图谱]\n C -->|ASK| F[Ask 自然语言→Cypher]\n C -->|HYBRID| G[组合查询]\n D --> H[Backend 执行]\n E --> H\n F --> I[Cypher 验证]\n I --> H\n H --> J[返回结果]\n```\n\n资料来源：[src/thought/query/ask.py:1-15]()\n资料来源：[src/thought/router/classifier.py]()\n\n### 核心模块\n\n| 模块 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| `ask` | `src/thought/query/ask.py` | 自然语言到 Cypher 查询的翻译与执行 |\n| `cypher` | `src/thought/query/cypher.py` | Cypher 查询构建器与执行器 |\n| `views` | `src/thought/query/views.py` | 查询视图定义与数据结构 |\n| `classifier` | `src/thought/router/classifier.py` | 查询意图分类器 |\n\n资料来源：[src/thought/query/ask.py]()\n资料来源：[src/thought/query/cypher.py]()\n资料来源：[src/thought/query/views.py]()\n\n## 自然语言查询转换（Ask 模块）\n\n### Ask 模块工作流程\n\nAsk 模块是查询系统中最复杂的组件，它将自然语言问题转换为 Cypher 查询语句。其核心流程包括：\n\n1. 获取当前知识图谱的 schema 信息\n2. 构建包含约束的提示词（prompt）\n3. 调用 LLM 进行翻译\n4. 验证 Cypher 查询语法\n5. 执行查询或降级到 recall\n\n```mermaid\ngraph LR\n A[用户问题] --> B{配置了 LLM?}\n B -->|否| C[recall 降级]\n B -->|是| D[构建提示词]\n D --> E[LLM 翻译]\n E --> F{翻译成功?}\n F -->|否| C\n F -->|是| G[Cypher 验证]\n G --> H{验证通过?}\n H -->|否| C\n H -->|是| I[执行查询]\n I --> J[返回结果]\n```\n\n资料来源：[src/thought/query/ask.py:48-78]()\n\n### AskResult 数据结构\n\n```python\n@dataclass\nclass AskResult:\n cypher: str | None # 生成的 Cypher 查询\n sql: str | None # 备用的 SQL 查询\n rows: list[dict[str, Any]] | None # 查询结果行\n fallback_used: bool # 是否使用了降级策略\n fallback_reason: str | None # 降级原因\n error: str | None # 错误信息\n```\n\n资料来源：[src/thought/query/ask.py:30-37]()\n\n### Cypher 翻译约束\n\n系统对生成的 Cypher 查询有严格的约束限制：\n\n| 约束类型 | 说明 |\n|----------|------|\n| 读写限制 | 只允许使用只读操作（`MATCH`, `WHERE`, `RETURN`, `LIMIT`, `AS_OF`） |\n| 禁用操作 | 禁止使用 `MERGE`, `CREATE`, `DELETE`, `SET`, `WITH` |\n| 路径限制 | 不支持可变长度路径 |\n| Schema 限制 | 必须使用 Schema 中定义的有效实体类型和关系类型 |\n\n资料来源：[src/thought/query/ask.py:17-27]()\n\n### 提示词模板\n\nAsk 模块使用结构化的提示词模板来引导 LLM 生成正确的 Cypher 查询：\n\n```cypher\nYou translate English questions into Cypher queries against a memory database.\n\nCONSTRAINTS (any violation will be rejected):\n- Output a single Cypher query, no explanations, no markdown fences.\n- Use ONLY these read-only Cypher features:\n MATCH (var:Type {{prop:value}}) (-[:RELATION]-> (var:Type))? ...\n WHERE expr (AND expr)* using = <> < > <= >= CONTAINS \"STARTS WITH\" IN\n RETURN identlist\n LIMIT N (optional)\n AS_OF 'iso-date' (optional, for time-travel queries)\n- Use ONLY entity types and relation types from the SCHEMA below.\n- Never use MERGE / CREATE / DELETE / SET / WITH / variable-length paths.\n\nSCHEMA:\n entity types: {entity_types}\n relation types: {relation_types}\n\nQUESTION: {question}\n\nCYPHER:\n```\n\n资料来源：[src/thought/query/ask.py:16-38]()\n\n### 降级策略\n\n当 LLM 翻译失败或未配置 LLM 提供者时，系统会自动降级到 `recall` 函数执行简单的向量检索：\n\n```python\ndef ask(\n memory,\n question: str,\n *,\n llm_cfg: object | None = None,\n scope: str = \"all\",\n owner_id: str | None = None,\n no_fallback: bool = False,\n) -> AskResult:\n provider = getattr(llm_cfg, \"provider\", None) or \"none\"\n \n if provider == \"none\":\n if no_fallback:\n return AskResult(error=\"thought ask requires [llm] provider...\")\n rows = _recall_fallback(memory, question, scope=scope, owner_id=owner_id)\n return AskResult(fallback_used=True, fallback_reason=\"no LLM provider configured\")\n```\n\n资料来源：[src/thought/query/ask.py:40-60]()\n\n## 路由分类系统\n\n### 查询类型分类\n\n路由器根据用户输入的关键词和模式匹配将查询分为以下类型：\n\n| 查询类型 | 触发条件 | 处理模块 |\n|----------|----------|----------|\n| `RECALL` | 一般自然语言问题 | recall 向量检索 |\n| `CODE` | 包含代码关键词 | CodeLayer 代码分析 |\n| `CHANGE` | 涉及变更历史 | Git 历史查询 |\n| `HYBRID` | CODE + CHANGE 组合 | 组合处理 |\n| `ASK` | 需要结构化查询 | Ask Cypher 翻译 |\n\n资料来源：[src/thought/router/classifier.py]()\n资料来源：[src/thought/router/rules.yaml]()\n\n### CODE 类型识别\n\nCODE 查询类型的识别基于以下特征：\n\n| 特征类型 | 关键词示例 | 识别方式 |\n|----------|------------|----------|\n| 编程关键字 | `function`, `class`, `method`, `interface` | 精确匹配 |\n| 代码操作 | `caller`, `callee`, `impact`, `imports` | 精确匹配 |\n| 文件扩展名 | `.py`, `.ts`, `.js`, `.rs`, `.php` | 扩展名检测 |\n| 标识符模式 | `camelCase`, `snake_case` | 正则匹配 |\n| 版本引用 | `since v1.0`, `before this commit` | 模式匹配 |\n\n资料来源：[src/thought/router/classifier.py]()\n\n### 自然语言调用\n\n系统支持通过自然语言触发代码图谱查询，例如：\n\n| 自然语言 | 解析结果 |\n|----------|----------|\n| `\"who calls authenticate_user\"` | 调用者查询 |\n| `\"what does login do\"` | 被调用者查询 |\n| `\"impact of password_reset\"` | 影响分析 |\n\n资料来源：[src/thought/query/ask.py]()\n资料来源：[src/thought/router/classifier.py]()\n\n## 代码图谱查询（CodeLayer）\n\n### 功能概述\n\nCodeLayer 是代码垂直领域的专用查询接口，提供面向程序员的自然词汇操作：\n\n| 操作 | 方法名 | 说明 |\n|------|--------|------|\n| 调用者查询 | `callers_of(name)` | 谁调用了这个函数（按 PageRank 排序） |\n| 被调用查询 | `callees_of(name)` | 这个函数调用了什么（包内） |\n| 影响分析 | `impact_set(name)` | 传递性调用者集合 |\n| 文件定义 | `defines_in_file(path)` | 查找文件中定义的所有实体 |\n\n资料来源：[src/thought/layers/code.py:1-25]()\n\n### 实体解析策略\n\n调用图构建时，实体解析按以下优先级进行：\n\n```mermaid\ngraph TD\n A[解析函数调用] --> B{同文件唯一匹配?}\n B -->|是| C[直接使用]\n B -->|否| D{唯一 qualified 后缀匹配?}\n D -->|是| C\n D -->|否| E{跨文件 bare-name 匹配?}\n E -->|是| C\n E -->|否| F[创建 Stub]\n```\n\n解析优先级：\n1. 同文件唯一匹配\n2. 唯一 qualified 后缀匹配（如 `obj.method()` → `ClassName.method`）\n3. 跨文件 bare-name 匹配（顶级函数）\n\n资料来源：[src/thought/ingest/code/call_graph.py]()\n资料来源：[src/thought/ingest/code/pipeline.py]()\n\n## 查询视图与数据结构\n\n### 视图模块\n\n`views.py` 定义了查询返回的标准化数据结构，确保不同查询类型的返回格式一致：\n\n| 视图类型 | 用途 |\n|----------|------|\n| RecallResult | 向量检索结果 |\n| AskResult | Cypher 查询结果 |\n| CodeResult | 代码图谱查询结果 |\n\n资料来源：[src/thought/query/views.py]()\n\n### 实体模型\n\n```python\nclass Entity(BaseModel):\n id: str\n type: str\n name: str\n canonical_name: str\n owner_id: str | None\n scope: ScopeName\n tier: Tier\n importance: float # 0.0 - 1.0\n valid_from: datetime\n valid_until: datetime | None # None = 当前有效\n learned_at: datetime\n unlearned_at: datetime | None\n created_at: datetime\n last_accessed_at: datetime\n access_count: int\n attrs: dict[str, object]\n```\n\n资料来源：[src/thought/models.py]()\n\n## 配置与集成\n\n### LLM 提供者配置\n\n查询系统支持多种 LLM 提供者：\n\n| 提供者 | 配置值 | 说明 |\n|--------|--------|------|\n| Anthropic | `anthropic` | Claude 系列模型 |\n| Ollama | `ollama` | 本地 Ollama 服务 |\n| LM Studio | `lmstudio` | LM Studio 本地服务 |\n| OpenAI 兼容 | `openai-compat` | 通用 OpenAI 兼容接口 |\n\n配置方式：通过 `thought.toml` 中的 `[llm] provider` 字段指定。\n\n资料来源：[src/thought/query/ask.py:48-55]()\n\n### CLI 命令集成\n\n| 命令 | 查询类型 | 功能 |\n|------|----------|------|\n| `thought recall ` | RECALL | 记忆检索 |\n| `thought ask ` | ASK | 自然语言查询 |\n| `thought callers ` | CODE | 调用者分析 |\n| `thought impact ` | CODE | 影响分析 |\n| `thought diff --from --to ` | CHANGE | 变更对比 |\n\n资料来源：[src/thought/cli.py]()\n资料来源：[src/thought/layers/code.py]()\n\n## 时间旅行查询\n\n### 双时间模型\n\n系统支持双时间（bi-temporal）查询模型：\n\n| 时间维度 | 说明 | 查询参数 |\n|----------|------|----------|\n| `valid_from/valid_until` | 事实的有效期 | `as_of_kind='valid'` |\n| `learned_at/unlearned_at` | 系统认识该事实的时间 | `as_of_kind='learned'` |\n\n```cypher\nMATCH (e:Entity)\nWHERE e.valid_from <= '2024-01-01' \n AND (e.valid_until IS NULL OR e.valid_until > '2024-01-01')\nRETURN e\n```\n\n### 使用场景\n\n| 场景 | 查询方式 |\n|------|----------|\n| 查询某日期的事实状态 | `as_of='date'` + `as_of_kind='valid'` |\n| 查询系统当时的认知 | `as_of='date'` + `as_of_kind='learned'` |\n| 事实纠正追踪 | 比较 `valid` 和 `learned` 时间差异 |\n\n资料来源：[src/thought/query/cypher.py]()\n资料来源：[src/thought/cli.py]()\n\n## 错误处理与降级\n\n### 错误处理策略\n\n| 错误类型 | 处理方式 | 降级目标 |\n|----------|----------|----------|\n| LLM 提供者未配置 | 自动降级 | `recall` 向量检索 |\n| LLM 调用失败 | 自动降级 | `recall` 向量检索 |\n| Cypher 翻译错误 | 自动降级 | `recall` 向量检索 |\n| Cypher 验证失败 | 自动降级 | `recall` 向量检索 |\n| 查询执行失败 | 返回错误 | - |\n\n### 强制模式\n\n当需要精确结果而不接受降级时，可使用 `no_fallback=True` 参数：\n\n```python\nresult = ask(memory, question, no_fallback=True)\nif result.error:\n # 处理错误，不使用降级\n handle_error(result.error)\n```\n\n资料来源：[src/thought/query/ask.py:60-78]()\n\n## 最佳实践\n\n### 查询优化建议\n\n| 建议 | 说明 |\n|------|------|\n| 使用具体标识符 | 提供函数全名或类名可提高解析准确性 |\n| 限制时间范围 | 使用 `as_of` 参数减少查询范围 |\n| 利用 scope 过滤 | 适当使用 `scope='private'` 或 `scope='shared'` |\n| 组合查询 | CODE + CHANGE 组合使用 HyBRID 类型 |\n\n### 调试技巧\n\n| 问题 | 调试方法 |\n|------|----------|\n| 翻译结果不准确 | 检查 schema 中实体类型是否完整 |\n| 解析失败 | 验证函数名符合标识符模式 |\n| 性能问题 | 使用 `db size` 检查索引状态 |\n\n## 相关文档\n\n- [CLI 命令参考](../cli/commands.md) - 所有查询相关命令详解\n- [存储后端](../storage/backend.md) - 查询执行底层实现\n- [摄取管道](../ingest/pipeline.md) - 数据如何进入知识图谱\n- [路由器设计](../router/design.md) - 查询分类内部机制\n\n---\n\n\n\n## 图形层与图遍历\n\n### 相关页面\n\n相关主题：[记忆模型与检索](#page-memory-model), [查询系统](#page-query-system)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/layers/graph.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/graph.py)\n- [src/thought/layers/code.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/layers/code.py)\n \n\n# 图形层与图遍历\n\n## 概述\n\n图形层（Graph Layer）是 THOUGHT 项目的核心组件之一，负责对知识库中的实体和关系进行图查询操作。它封装了底层的 SQLite 存储后端，提供面向程序员的图遍历接口，支持调用链分析、影响范围计算和代码结构查询等高级功能。\n\n图形层的设计目标是实现**语义感知的代码导航**：用户可以通过函数名、类名等标识符快速定位代码实体，分析代码间的调用关系和依赖关系，从而支持代码审查、影响分析和重构决策等场景。\n\n## 架构设计\n\n### 模块层次结构\n\n```\n┌─────────────────────────────────────┐\n│ CLI / API 层 │\n├─────────────────────────────────────┤\n│ CodeLayer (代码层) │\n│ - callers_of() │\n│ - callees_of() │\n│ - impact_set() │\n│ - defines_in_file() │\n├─────────────────────────────────────┤\n│ GraphLayer (图形层) │\n│ - 图遍历核心逻辑 │\n│ - PageRank 排序 │\n├─────────────────────────────────────┤\n│ SQLiteBackend (存储后端) │\n│ - 实体存储 │\n│ - 关系存储 │\n│ - 嵌入向量存储 │\n└─────────────────────────────────────┘\n```\n\nCodeLayer 是 GraphLayer 的上层封装，专门针对代码场景优化。GraphLayer 负责底层的图遍历实现，支持多种查询模式和排序策略。\n\n资料来源：[src/thought/layers/code.py:24-27]()\n\n### 数据模型\n\n图形层操作的核心数据模型包括：\n\n| 模型 | 说明 |\n|------|------|\n| `Entity` | 实体节点，代表代码中的函数、类、模块等 |\n| `CodeHit` | 查询结果，包含实体和相关性评分 |\n| `ScopeFilter` | 作用域过滤器，用于限定查询范围 |\n\n```python\n@dataclass(frozen=True)\nclass CodeHit:\n entity: Entity\n score: float\n```\n\n`CodeHit` 用于返回按 PageRank 评分排序的查询结果，支持 \"who calls X\" 等排名查询场景。\n\n资料来源：[src/thought/layers/code.py:21-23]()\n\n## 核心功能\n\n### 调用者查询 (callers_of)\n\n`callers_of` 方法返回直接调用指定函数的实体列表，结果按 PageRank 评分降序排列。\n\n```python\ndef callers_of(name: str, *, ...) -> list[CodeHit]\n```\n\n**使用场景**：\n\n- 分析某个函数被哪些模块调用\n- 识别关键函数的依赖方\n- 评估代码变更的影响范围\n\n该方法通过双向 PageRank 遍历（HippoRAG 风格）实现，能够发现直接和间接的调用关系。\n\n### 被调用者查询 (callees_of)\n\n`callees_of` 方法返回指定函数直接调用的其他实体列表。\n\n```python\ndef callees_of(name: str, *, ...) -> list[CodeHit]\n```\n\n**使用场景**：\n\n- 分析函数的依赖项\n- 理解函数的实现逻辑\n- 准备代码重构的影响评估\n\n### 影响集计算 (impact_set)\n\n`impact_set` 是最强大的图查询方法，计算指定实体的**传递影响集**：即所有可能受到该实体变更影响的实体集合。\n\n```python\ndef impact_set(name: str, *, ...) -> list[CodeHit]\n```\n\n该方法基于传递闭包算法，遍历指定实体的所有传递调用者路径，返回完整的受影响实体列表。\n\n### 文件内定义查询 (defines_in_file)\n\n`defines_in_file` 返回指定文件中定义的所有实体。\n\n```python\ndef defines_in_file(path: str, ...) -> list[CodeHit]\n```\n\n**返回内容**：\n\n- 文件中的所有函数定义\n- 文件中的所有类定义\n- 文件中的所有模块级实体\n\n## 图遍历实现\n\n### 实体解析机制\n\n图形层通过多层匹配策略解析实体名称：\n\n1. **精确匹配** - 按完全限定名查找\n2. **包内匹配** - 在同一作用域内查找\n3. **唯一后缀匹配** - 查找唯一的 `ClassName.method` 形式\n4. **跨文件匹配** - 查找其他文件中同名的顶级函数\n\n资料来源：[src/thought/ingest/code/call_graph.py:1-40]()\n\n### 作用域过滤\n\n实体查询支持细粒度的作用域控制：\n\n```python\n@dataclass\nclass ScopeFilter:\n scope: ScopeName\n owner_id: str | None\n code_file: str | None\n code_commit_sha: str | None\n```\n\n| 过滤条件 | 用途 |\n|----------|------|\n| `scope` | 多租户隔离，默认为 \"shared\" |\n| `owner_id` | 用户级隔离 |\n| `code_file` | 文件级隔离 |\n| `code_commit_sha` | Git 版本隔离 |\n\n### 双时态查询支持\n\n图形层支持双时态查询，能够查询知识库在特定时间点的状态：\n\n- `valid_from` / `valid_until` - 实体有效时间窗口\n- `as_of_kind='valid'` - 查询历史上某时刻的事实\n- `as_of_kind='learned'` - 查询系统在某时刻的知识状态\n\n资料来源：[src/thought/cli.py:1-50]()\n\n## 与其他模块的集成\n\n### 代码提取器集成\n\n图形层与代码提取器（Code Extractor）紧密配合：\n\n```\n代码文件 → 语言提取器 → CodeEntity/CodeEdge → SQLiteBackend → GraphLayer\n```\n\n| 提取器 | 支持语言 |\n|--------|----------|\n| `python_extractor` | Python |\n| `typescript_extractor` | TypeScript/JavaScript |\n| `rust_extractor` | Rust |\n| `go_extractor` | Go |\n| `java_extractor` | Java |\n| `php_extractor` | PHP |\n\n每个提取器生成 `CodeEntity` 和 `CodeEdge`，存储到后端后可通过图形层查询。\n\n资料来源：[src/thought/ingest/code/ast_extractor.py:1-50]()\n\n### 存储后端集成\n\nGraphLayer 依赖 `SQLiteBackend` 提供数据访问：\n\n```python\nclass CodeLayer:\n def __init__(self, backend: SQLiteBackend) -> None:\n self._backend = backend\n self._graph = GraphLayer(backend)\n```\n\n存储后端管理实体、关系和嵌入向量的持久化，图形层在此基础上实现图遍历算法。\n\n## 查询流程图\n\n```mermaid\ngraph TD\n A[CLI 命令] --> B[CodeLayer 方法]\n B --> C{查询类型}\n C -->|callers| D[GraphLayer 遍历调用者]\n C -->|callees| E[GraphLayer 遍历被调用者]\n C -->|impact| F[GraphLayer 计算传递闭包]\n C -->|defines| G[GraphLayer 查询文件内实体]\n D --> H[应用 PageRank 排序]\n E --> H\n F --> H\n G --> H\n H --> I[返回 CodeHit 列表]\n```\n\n## CLI 命令接口\n\n图形层功能通过 CLI 命令暴露：\n\n| 命令 | 功能 |\n|------|------|\n| `thought callers ` | 查询调用者，PageRank 排名 |\n| `thought impact ` | 计算传递影响集 |\n| `thought defines ` | 查询文件内定义 |\n\n## 配置与扩展\n\n### 嵌入模型配置\n\n图形层使用嵌入模型为实体生成语义向量，支持配置：\n\n| 选项 | 说明 |\n|------|------|\n| `auto` | 自动选择 sentence-transformers 或确定性嵌入器 |\n| `sentence-transformers` | 使用预训练模型 |\n| `deterministic` | 使用确定性哈希（无需外部依赖） |\n\n### 图查询性能优化\n\n- **部分索引** - `code_file`、`code_commit_sha` 等字段建立部分索引\n- **身份唯一性** - 实体唯一性包含 `(code_file, code_commit_sha)`\n- **批量写入** - 单个文件的所有写入在同一事务内完成\n\n## 总结\n\n图形层是 THOUGHT 项目实现代码智能导航的核心基础设施。它通过封装 GraphLayer 提供语义感知的图遍历能力，支持调用链分析、影响范围计算等高级功能。与代码提取器和存储后端的紧密集成，使得用户能够对代码库进行深度的结构化分析和探索。\n\n---\n\n\n\n## Agent集成与适配器\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [配置管理](#page-configuration)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/thought/adapters/claude_sdk.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/adapters/claude_sdk.py)\n- [src/thought/hooks/install.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/hooks/install.py)\n- [src/thought/demo.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/demo.py)\n- [src/thought/cli.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/cli.py)\n- [src/thought/ingest/code/pipeline.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/pipeline.py)\n \n\n# Agent集成与适配器\n\nthought-mcp 提供了完整的 Agent 集成层，使 AI Agent 能够将项目知识库（Knowledge Base, KB）作为持久化记忆系统使用。该集成层包含两个核心组件：**Claude SDK 适配器**和**Claude Code Hook 系统**。\n\n## 1. 系统概述\n\nAgent 集成模块让 AI Agent 在执行任务时能够：\n\n- 检索与当前任务相关的上下文知识\n- 将学习到的新知识持久化到知识库\n- 增量扫描代码仓库以更新实体信息\n- 通过钩子机制在交互会话的各个阶段自动触发记忆操作\n\n这种设计使 Agent 具备长期记忆能力，避免每次会话都需要重新加载上下文信息。\n\n## 2. Claude SDK 适配器\n\n### 2.1 核心类：ThoughtMemoryProvider\n\n`ThoughtMemoryProvider` 是专为 Claude Agent SDK 设计的即插即用记忆适配器，位于 `src/thought/adapters/claude_sdk.py`。\n\n资料来源：[src/thought/adapters/claude_sdk.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/adapters/claude_sdk.py)\n\n该类实现了四个核心方法，完整覆盖 Agent 工作循环：\n\n| 方法名 | 功能描述 | 返回值 |\n|--------|----------|--------|\n| `context_for(target, role)` | 获取指定角色和目标的工作上下文字典 | `dict` |\n| `render_context(target)` | 生成纯文本形式的系统提示增强内容 | `str` |\n| `record(content)` | 将 Agent 学到的知识持久化到知识库 | 无 |\n| `scan(repo_path)` | 对仓库进行增量扫描，更新实体信息 | 无 |\n\n### 2.2 工作流程\n\n```mermaid\ngraph TD\n A[Agent 启动] --> B{选择集成方式}\n B --> C[context_for
获取工作上下文]\n B --> D[render_context
生成提示增强]\n C --> E[Agent 执行任务]\n D --> E\n E --> F[record
持久化新知识]\n E --> G[scan
增量扫描代码]\n F --> H[知识库更新]\n G --> H\n```\n\n### 2.3 使用场景\n\n在 `src/thought/demo.py` 中，Code 受众场景演示了 Agent 身份注册和工作上下文获取的完整流程：\n\n资料来源：[src/thought/demo.py:28-32](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/demo.py#L28-L32)\n\n```python\naudiences = {\n \"code\": Agent/developer flow — the 14-stage code-vertical\n walkthrough including agent identity, thought scan,\n working_context, 4 new-language extractors, and the\n Claude Agent SDK adapter.\n}\n```\n\n### 2.4 上下文检索机制\n\n`context_for` 方法根据传入的 `target`（目标实体）和 `role`（角色）返回经过筛选的上下文信息。上下文内容来源于知识库的嵌入向量搜索，确保返回的信息与当前任务高度相关。\n\n## 3. Claude Code Hook 系统\n\nHook 系统通过事件钩子实现 Claude Code 编辑器与 thought-mcp 的深度集成。\n\n资料来源：[src/thought/hooks/install.py:20-27](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/hooks/install.py#L20-L27)\n\n### 3.1 钩子类型与触发时机\n\n| 钩子类型 | Claude Code 事件 | 触发命令 | 用途 |\n|----------|------------------|----------|------|\n| `recall` | `UserPromptSubmit` | `thought hook recall` | 用户提交提示时检索相关记忆 |\n| `write` | `Stop` | `thought hook write` | 会话结束时保存学习到的知识 |\n| `context` | `SessionStart` | `thought hook context` | 会话启动时加载上下文 |\n\n### 3.2 安装机制\n\nHook 安装器 (`src/thought/hooks/install.py`) 采用幂等设计，通过修改 `.claude/settings.json` 文件注册钩子：\n\n资料来源：[src/thought/hooks/install.py:1-20](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/hooks/install.py#L1-L20)\n\n```python\n_HOOK_SPEC: dict[HookKind, tuple[str, str]] = {\n \"recall\": (\"UserPromptSubmit\", \"thought hook recall\"),\n \"write\": (\"Stop\", \"thought hook write\"),\n \"context\": (\"SessionStart\", \"thought hook context\"),\n}\n```\n\n#### 安装结果状态\n\n| 状态值 | 含义 |\n|--------|------|\n| `installed` | 首次安装成功 |\n| `already_present` | 钩子已存在，无需重复安装 |\n| `error` | 安装过程出错 |\n\n### 3.3 幂等性保障\n\n安装器在写入配置文件前会自动备份原始文件：\n\n```mermaid\ngraph LR\n A[读取 settings.json] --> B{检查钩子存在}\n B -->|不存在| C[备份为 .bak 文件]\n C --> D[合并钩子配置]\n D --> E[写入 settings.json]\n B -->|已存在| F[返回 already_present]\n```\n\n备份文件命名为 `.thought.bak`，确保配置修改可回滚。\n\n### 3.4 作用域支持\n\n支持两种安装作用域：\n\n- **项目级 (`project`)**：安装到 `.claude/settings.json`，随仓库共享\n- **用户级 (`user`)**：安装到用户主目录，跨项目生效\n\n资料来源：[src/thought/hooks/install.py:34-39](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/hooks/install.py#L34-L39)\n\n## 4. 集成架构图\n\n```mermaid\ngraph TD\n subgraph Claude_Code\n A[用户提示] --> B[UserPromptSubmit 事件]\n A --> C[SessionStart 事件]\n A --> D[Stop 事件]\n end\n\n subgraph Hook_System\n B --> E[recall 钩子]\n C --> F[context 钩子]\n D --> G[write 钩子]\n end\n\n subgraph Thought_KB\n H[SQLite 数据库]\n I[嵌入向量存储]\n J[实体/边图结构]\n end\n\n E --> H\n F --> H\n G --> H\n H --> I\n H --> J\n\n subgraph Agent_SDK\n K[ThoughtMemoryProvider]\n K --> H\n K --> L[Agent 上下文]\n end\n```\n\n## 5. 代码管道集成\n\nAgent 集成与代码摄取管道紧密配合。当 Agent 通过 `scan()` 方法触发增量扫描时，后端调用 `CodePipeline` 进行代码解析：\n\n资料来源：[src/thought/ingest/code/pipeline.py:60-80](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/pipeline.py#L60-L80)\n\n### 5.1 增量扫描流程\n\n```mermaid\ngraph TD\n A[scan(repo_path)] --> B[遍历代码文件]\n B --> C{检测语言}\n C --> D[Python Extractor]\n C --> E[TypeScript Extractor]\n C --> F[Go Extractor]\n C --> G[Rust Extractor]\n C --> H[Java Extractor]\n C --> I[PHP Extractor]\n D --> J[提取实体与边]\n E --> J\n F --> J\n G --> J\n H --> J\n I --> J\n J --> K[Upsert 到知识库]\n K --> L[存储嵌入向量]\n```\n\n### 5.2 支持的语言\n\n系统通过 `ast_extractor.py` 的注册机制支持以下语言：\n\n资料来源：[src/thought/ingest/code/ast_extractor.py](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/ingest/code/ast_extractor.py)\n\n| 语言 | 提取器模块 | 实体类型 |\n|------|------------|----------|\n| Python | `python_extractor` | module, class, function, method |\n| TypeScript | `typescript_extractor` | module, class, function, method |\n| Go | `go_extractor` | module, function, method |\n| Rust | `rust_extractor` | module, function, impl method |\n| Java | `java_extractor` | class, method |\n| PHP | `php_extractor` | class, method |\n\n## 6. 初始化与配置\n\n在 CLI 初始化命令中，系统提供了 Agent 集成的自动配置选项：\n\n资料来源：[src/thought/cli.py:45-60](https://github.com/RNBBarrett/thought-mcp/blob/main/src/thought/cli.py#L45-L60)\n\n```python\n@app.command()\ndef init(\n config: Path = typer.Option(\"thought.toml\"),\n db_path: str = typer.Option(\".thought/thought.db\"),\n embedder: str = typer.Option(\"auto\"),\n write_claude_md: bool = typer.Option(\n True, \"--write-claude-md/--no-claude-md\",\n help=\"Drop a CLAUDE.md so MCP clients learn how to use the tool.\"\n ),\n quick: bool = typer.Option(False, \"--quick\"),\n) -> None:\n```\n\n### 配置参数说明\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `config` | `thought.toml` | 配置文件路径 |\n| `db_path` | `.thought/thought.db` | SQLite 数据库路径 |\n| `embedder` | `auto` | 向量化模型选择 |\n| `write_claude_md` | `True` | 自动生成 MCP 客户端使用文档 |\n| `quick` | `False` | 跳过首次嵌入器预热 |\n\n## 7. 最佳实践\n\n### 7.1 集成检查清单\n\n- [ ] 使用 `thought init` 完成基础配置\n- [ ] 通过 `thought hooks install` 注册 Claude Code 钩子\n- [ ] 在 Agent 启动时调用 `context_for()` 加载工作上下文\n- [ ] 任务完成后调用 `record()` 保存新知识\n- [ ] 代码变更后调用 `scan()` 更新实体索引\n\n### 7.2 注意事项\n\n1. **幂等性**：Hook 安装器支持重复运行，不会产生重复配置\n2. **备份机制**：配置修改前自动备份，确保可回滚\n3. **作用域选择**：建议使用项目级作用域 (`project`) 以便团队共享\n4. **嵌入优化**：首次初始化会预热嵌入模型，可使用 `--quick` 跳过\n\n## 8. 相关命令\n\n| 命令 | 功能 |\n|------|------|\n| `thought init` | 初始化数据库和配置文件 |\n| `thought hooks install` | 安装 Claude Code 事件钩子 |\n| `thought hooks list` | 列出已安装的钩子 |\n| `thought hooks uninstall` | 卸载钩子 |\n| `thought recall` | 检索相关记忆 |\n| `thought scan ` | 扫描代码仓库更新实体 |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：RNBBarrett/thought-mcp\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | host_targets=mcp_host, claude, claude_code, chatgpt\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | no_demo; severity=medium\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：RNBBarrett/thought-mcp\n\n摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | host_targets=mcp_host, claude, claude_code, chatgpt\n\n## 2. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 6. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | no_demo; severity=medium\n\n## 7. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | issue_or_pr_quality=unknown\n\n## 8. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1238261514 | https://github.com/RNBBarrett/thought-mcp | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# thought-mcp - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 thought-mcp 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code / chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Local MCP memory server for LLMs. Bi-temporal graph + vector + Cypher queries + auto-write/auto-recall hooks for Claude Code. Works with Ollama, LM Studio, Anthropic, OpenAI. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与快速开始。围绕“安装与快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-code-ingestion：代码摄取与解析。围绕“代码摄取与解析”模拟一次用户任务，不展示安装或运行结果。\n5. page-entity-management：实体与关系管理。围绕“实体与关系管理”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-code-ingestion\n输入：用户提供的“代码摄取与解析”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-entity-management\n输入：用户提供的“实体与关系管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-code-ingestion：Step 4 必须围绕“代码摄取与解析”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-entity-management：Step 5 必须围绕“实体与关系管理”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/RNBBarrett/thought-mcp\n- https://github.com/RNBBarrett/thought-mcp#readme\n- README.md\n- src/thought/__init__.py\n- pyproject.toml\n- src/thought/cli.py\n- Dockerfile\n- src/thought/server.py\n- src/thought/storage/base.py\n- src/thought/ingest/pipeline.py\n- src/thought/layers/__init__.py\n- src/thought/router/dispatcher.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 thought-mcp 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：RNBBarrett/thought-mcp\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install thought-mcp\n```\n\n来源：https://github.com/RNBBarrett/thought-mcp#readme\n\n## 来源\n\n- repo: https://github.com/RNBBarrett/thought-mcp\n- docs: https://github.com/RNBBarrett/thought-mcp#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_1115cfafb5dd48f8842d7e45e3fc9b07"
}