# https://github.com/forloopcodes/contextplus 项目说明书 生成时间：2026-06-28 12:58:05 UTC ## 目录 - [Architecture & Overview](#page-1) - [Discovery & Analysis Tools](#page-2) - [Embedding Providers & Configuration](#page-3) - [Memory Graph & Code Operations](#page-4) ## Architecture & Overview ### 相关页面 相关主题：[Discovery & Analysis Tools](#page-2), [Embedding Providers & Configuration](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [src/index.ts](https://github.com/forloopcodes/contextplus/blob/main/src/index.ts) - [src/core/hub.ts](https://github.com/forloopcodes/contextplus/blob/main/src/core/hub.ts) - [src/tools/semantic-identifiers.ts](https://github.com/forloopcodes/contextplus/blob/main/src/tools/semantic-identifiers.ts) - [src/tools/propose-commit.ts](https://github.com/forloopcodes/contextplus/blob/main/src/tools/propose-commit.ts) - [README.md](https://github.com/forloopcodes/contextplus/blob/main/README.md) - [INSTRUCTIONS.md](https://github.com/forloopcodes/contextplus/blob/main/INSTRUCTIONS.md) - [agent-instructions.md](https://github.com/forloopcodes/contextplus/blob/main/agent-instructions.md)
# Architecture & Overview ## 项目目的与范围 Context+ 是一个面向 AI 代理的 MCP (Model Context Protocol) 服务器,定位于"大规模工程的语义智能"——通过融合 RAG (Retrieval-Augmented Generation)、Tree-sitter AST、光谱聚类 (Spectral Clustering) 与 Obsidian 风格的双向链接,将庞大的代码库转化为可搜索、可分层的特性图谱,以追求 99% 的检索准确率。资料来源:[README.md:1-7]() 系统通过 stdio 传输方式启动,并通过一个 CLI 参数接收目标工程根目录 (默认为 `process.cwd()`),随后注册 17 个 MCP 工具供宿主代理调用。资料来源:[src/index.ts:43-44]() ## 系统架构 Context+ 整体上分为四层:**入口层 (Entry Point)**、**核心层 (Core Layer)**、**工具层 (Tools Layer)** 与 **Git 层 (Git Layer)**,并以本地持久化的内存图谱作为长期记忆,辅以 Ollama 驱动的嵌入与聚类模型。入口 `src/index.ts` 负责装配 `McpServer`、注册工具、加载内嵌的 `agent-instructions.md` 资源,并通过 `contextplus://instructions` URI 暴露给宿主。资料来源:[src/index.ts:25-45](),[INSTRUCTIONS.md:30-44]() 核心层承担跨工具的共享能力: - `hub.ts` 解析 Obsidian 风格的 `[[wikilink]]` 链接与 `@linked-to` 跨链标签,用于构建特性中心 (Feature Hub) 与孤立文件检测。资料来源:[src/core/hub.ts:6-58]() - `memory-graph.ts` 维护带 JSON 持久化、衰减评分 (`e^(-λt)`) 与自动相似边的属性图谱。资料来源:[INSTRUCTIONS.md:42-44]() - `embedding-tracker.ts` 与 `process-lifecycle.ts` 协同管理实时嵌入刷新、批处理上限 (硬性封顶 5-10) 与进程空闲关机。资料来源:[src/index.ts:27-31]() 工具层由 17 个 MCP 端点组成,横跨**发现 (Discovery)**、**分析 (Analysis)**、**代码操作 (Code Ops)**、**版本控制 (Version Control)** 与**记忆/RAG (Memory & RAG)** 五大职能。资料来源:[README.md:11-71]() Git 层 (`src/git/shadow.ts`) 实现与 git 历史解耦的"影子还原点"机制,使得 `undo_change` 不会污染版本控制。资料来源:[INSTRUCTIONS.md:46-48]() ```mermaid flowchart TB Agent[AI Agent / Claude / Cursor / OpenCode] -->|stdio MCP| Server[src/index.ts
McpServer] Server --> Tools[17 MCP Tools] Server --> Resources[contextplus://instructions] subgraph Core[Core Layer] Hub[hub.ts
Wikilink Parser] MemGraph[memory-graph.ts
Property Graph] Embed[embeddings.ts
Ollama Embeddings] end subgraph Git[Git Layer] Shadow[shadow.ts
Restore Points] end Tools --> Core Tools --> Git Embed --> Ollama[(Ollama
nomic-embed-text / llama3.2)] ``` ## 工具层职责划分 工具层在功能上划分为五个域,各域工具协同完成"探索 → 理解 → 修改 → 回滚 → 沉淀知识"的工作流。下表概述各域代表工具与职责。 | 工具域 | 代表工具 | 关键职责 | |--------|----------|----------| | Discovery | `get_context_tree`、`semantic_identifier_search` | 构建 AST 骨架与按标识符语义检索,需在每次任务开始时调用 | | Analysis | `get_blast_radius`、`run_static_analysis` | 追踪符号影响范围并执行原生 linter (`tsc`、`eslint`、`py_compile` 等) | | Code Ops | `propose_commit`、`get_feature_hub` | 强制 2 行文件头、禁止行内注释、最大嵌套深度等规则后再写入 | | Version Control | `list_restore_points`、`undo_change` | 影子还原点管理,与 git 解耦 | | Memory & RAG | `search_memory_graph`、`upsert_memory_node`、`create_relation` | 语义搜索 + 1/2 跳邻居遍历 + 跨会话知识沉淀 | 资料来源:[README.md:11-71](),[INSTRUCTIONS.md:50-70](),[agent-instructions.md:14-37]() 以 `semantic_identifier_search` 为例,该工具从 `walker.ts` 遍历得到受支持的文件,经 `parser.ts` 抽取出扁平化的符号列表后,为每个标识符构建包含签名、父符号、行号范围的文档,再调用 `embeddings.ts` 中的 `fetchEmbedding` 生成向量,并维护 `identifier-embeddings-cache.json` (60 秒 TTL) 与 `callsite:` 前缀的调用点缓存。资料来源:[src/tools/semantic-identifiers.ts:1-60]() `propose_commit` 作为"唯一允许写文件"的入口,在写入前调用 `validateHeader` 校验前两行必须为对应语言的注释 (`//` / `#` / `--`),并通过 `createRestorePoint` 先生成可回滚快照。资料来源:[src/tools/propose-commit.ts:5-32]() ## 环境配置与已知限制 默认嵌入与对话模型依赖 Ollama 本地实例,关键环境变量见下表。社区已记录两项与 Ollama 假设相关的限制: | 变量 | 默认值 | 说明 | |------|--------|------| | `OLLAMA_EMBED_MODEL` | `nomic-embed-text` | 嵌入模型名称 | | `OLLAMA_CHAT_MODEL` | `llama3.2` | 用于聚类标签的对话模型 | | `CONTEXTPLUS_EMBED_BATCH_SIZE` | `8` | 单次 GPU 调用的批大小 (硬性封顶 5-10) | | `CONTEXTPLUS_EMBED_TRACKER` | `true` | 启用变更文件的实时嵌入刷新 | | `CONTEXTPLUS_EMBED_TRACKER_MAX_FILES` | `8` | 单次刷新最大文件数 | | `CONTEXTPLUS_EMBED_TRACKER_DEBOUNCE_MS` | `700` | 刷新去抖延迟 | 资料来源:[INSTRUCTIONS.md:52-60]() 社区反馈指出:将 `OLLAMA_HOST` 写入 `.mcp.json` 的 `env` 块对 Ollama JS 客户端并不生效,因为客户端构造时未读取该变量(参见 issue #3 与 #27)。此外,`CONTEXTPLUS_EMBED_PROVIDER=openai` 等文档承诺的 OpenAI 兼容后端目前并未真正接入(issue #34)。在 monorepo 场景下,若子仓库被根目录 `.gitignore` 排除,`walker.ts` 将无法枚举到嵌套子仓库中的源码(issue #38)。Context+ 同时声明 OpenCode 通过标准 MCP 即插即用,并以 `opencode.json` 作为配置目标文件(issue #8,`src/index.ts:14-21`())。 ## See Also - [INSTRUCTIONS.md](https://github.com/forloopcodes/contextplus/blob/main/INSTRUCTIONS.md) — 完整的工具清单与环境变量参考 - [agent-instructions.md](https://github.com/forloopcodes/contextplus/blob/main/agent-instructions.md) — 面向 AI 代理的工具调用最佳实践 - [README.md](https://github.com/forloopcodes/contextplus/blob/main/README.md) — 项目定位与工具概述 --- ## Discovery & Analysis Tools ### 相关页面 相关主题：[Architecture & Overview](#page-1), [Embedding Providers & Configuration](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [src/index.ts](https://github.com/forloopcodes/contextplus/blob/main/src/index.ts) - [src/tools/semantic-identifiers.ts](https://github.com/forloopcodes/contextplus/blob/main/src/tools/semantic-identifiers.ts) - [src/tools/semantic-navigate.ts](https://github.com/forloopcodes/contextplus/blob/main/src/tools/semantic-navigate.ts) - [README.md](https://github.com/forloopcodes/contextplus/blob/main/README.md) - [INSTRUCTIONS.md](https://github.com/forloopcodes/contextplus/blob/main/INSTRUCTIONS.md) - [agent-instructions.md](https://github.com/forloopcodes/contextplus/blob/main/agent-instructions.md) - [src/core/hub.ts](https://github.com/forloopcodes/contextplus/blob/main/src/core/hub.ts)
# Discovery & Analysis Tools ## 概述 Discovery & Analysis Tools（发现与分析工具集）是 Context+ MCP 服务器向 Agent 暴露的两大类核心工具的统称，共包含 **7 个** 通过 Model Context Protocol（std ## File Path: src/core/hub.ts // Obsidian-style hub parser extracting wikilinks and cross-link tags // FEATURE: Hierarchical context management via feature hub graph import { readFile, readdir, stat } from "fs/promises"; import { resolve, relative, join, extname, basename } from "path"; export interface HubLink { target: string; description?: string; } export interface CrossLink { hubName: string; sourceFile: string; } export interface HubInfo { hubPath: string; title: string; links: HubLink[]; crossLinks: CrossLink[]; raw: string; } const WIKILINK_RE = /\[\[([^\]|]+)(?:\|([^\]]*))?\]\]/g; const CROSS_LINK_RE = /@linked-to\s+\[\[([^\]]+)\]\]/g; const HEADER_FEATURE_RE = /^(?:\/\/|#|--)\s*FEATURE:\s*(.+)$/m; export function parseWikiLinks(content: string): HubLink[] { const links: HubLink[] = []; const seen = new Set(); const cleaned = content.replace(CROSS_LINK_RE, ""); for (const match of cleaned.matchAll(WIKILINK_RE)) { const target = match[1].trim(); if (!seen.has(target)) { seen.add(target); links.push({ target, description: match[2]?.trim() }); } } return links; } export function parseCrossLinks(content: string, sourceFile: string): CrossLink[] { const crossLinks: CrossLink[] = []; for (const match of content.matchAll(CROSS_LINK_RE)) { crossLinks.push({ hub ## File Path: README.md | ### Analysis | Tool | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `get_blast_radius` | Trace every file and line where a symbol is imported or used. Prevents orphaned references. | | `run_static_analysis` | Run native linters and compilers to find unused variables, dead code, and type errors. Supports TypeScript, Python, Rust, Go. | ### Code Ops | Tool | Description | | ----------------- | ------------------------------------------------------------------------------------------------------------------------ | | `propose_commit` | The only way to write code. Validates against strict rules before saving. Creates a shadow restore point before writing. | | `get_feature_hub` | Obsidian-style feature hub navigator. Hubs are `.md` files with `[[wikilinks]]` that map features to code files. | ### Version Control | Tool | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------- | | `list_restore_points` | List all shadow restore points created by `propose_commit`. Each captures file state before AI changes. | | `undo_change` | Restore files to their state before a specific AI change. Uses shadow restore points. Does not affect git. | ### Memory & RAG | Tool | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------- | | `upsert_memory_node` | Create or update a memory node (concept, file, symbol, note) with auto-generated embeddings. | | `create_relation` | Create typed edges between nodes (relates_to, depends_on, implements, references, similar_to, contains). | | `search_memory_graph` | Semantic search with graph traversal — finds direct matches then walks # Context+ Semantic Intelligence for Large-Scale Engineering. Context+ is an MCP server designed for developers who demand 99% accuracy. By combining RAG, Tree-sitter AST, Spectral Clustering, and Obsidian-style linking, Context+ turns a massive codebase into a searchable, hierarchical feature graph. https://github.com/user-attachments/assets/a97a451f-c9b4-468d-b036-15b65fc13e79 ## Tools ### Discovery | Tool | Description | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `get_context_tree` | Structural AST tree of a project with file headers and symbol ranges (line numbers for functions/classes/methods). Dynamic pruning shrinks output automatically. | | `get_file_skeleton` | Function signatures, class methods, and type definitions with line ranges, without reading full bodies. Shows the API surface. | | `semantic_code_search` | Search by meaning, not exact text. Uses embeddings over file headers/symbols and returns matched symbol definition lines. | | `semantic_identifier_search` | Identifier-level semantic retrieval for functions/classes/variables with ranked call sites and line numbers. | | `semantic_navigate` | Browse codebase by meaning using spectral clustering. Groups semantically related files into labeled clusters. | ### Analysis | Tool | Description | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `get_blast_radius` | Trace every file and line where a symbol is imported or used. Prevents orphaned references. | | `run_static_analysis` | Run native linters and compilers to find unused variables, dead code, and type errors. Supports TypeScript, Python, ## File Path: INSTRUCTIONS.md - Identifier-level semantic search returning ranked definitions + call chains with line numbers. - `semantic-navigate.ts` - Browse-by-meaning navigator using spectral clustering and Ollama labeling. - `blast-radius.ts` - Symbol usage tracer across the entire codebase. - `static-analysis.ts` - Native linter runner (tsc, eslint, py_compile, cargo check, go vet). - `propose-commit.ts` - Code gatekeeper validating headers, FEATURE tag, no inline comments, nesting, file length. - `feature-hub.ts` - Obsidian-style feature hub navigator with bundled skeleton views. - `memory-tools.ts` - Memory graph MCP wrappers (upsert, relate, search, prune, interlink, traverse). The long-term memory graph architecture is also adapted by the complementary [pmll-memory-mcp](https://www.npmjs.com/package/pmll-memory-mcp) server (`npx pmll-memory-mcp`), which adds short-term KV memory and a solution engine — see [drQedwards/PPM](https://github.com/drQedwards/PPM). The memory graph is a **Retrieval-Augmented Generation (RAG)** system. Agents MUST use `search_memory_graph` at the start of every task to retrieve prior context, and persist learnings with `upsert_memory_node` and `create_relation` after completing work. This prevents redundant exploration and builds cumulative knowledge across sessions. **Core Layer** (continued): - `hub.ts` - Wikilink parser for `[[path]]` links, cross-link tags, hub discovery, orphan detection. - `memory-graph.ts` - In-memory property graph with JSON persistence, decay scoring, and auto-sim _memory_node` and `create_relation` after completing work. This prevents redundant exploration and builds cumulative knowledge across sessions. **Core Layer** (continued): - `hub.ts` - Wikilink parser for `[[path]]` links, cross-link tags, hub discovery, orphan detection. - `memory-graph.ts` - In-memory property graph with JSON persistence, decay scoring, and auto-similarity edges. **Git Layer** (`src/git/`): - `shadow.ts` - Shadow restore point system for undo without touching git history. **Entry Point**: `src/index.ts` registers 17 MCP tools and starts the stdio transport. Accepts an optional CLI argument for the target project root directory (defaults to `process.cwd()`). ## Environment Variables | Variable | Default | Description | | --------------------------------------- | ------------------ | ------------------------------------------------------------- | | `OLLAMA_EMBED_MODEL` | `nomic-embed-text` | Embedding model name | | `OLLAMA_API_KEY` | (empty) | Cloud auth (auto-detected by SDK) | | `OLLAMA_CHAT_MODEL` | `llama3.2` | Chat model for cluster labeling | | `CONTEXTPLUS_EMBED_BATCH_SIZE` | `8` | Embedding batch per GPU call (hard-capped to 5-10) | | `CONTEXTPLUS_EMBED_TRACKER` | `true` | Enable realtime embedding updates for changed files/functions | | `CONTEXTPLUS_EMBED_TRACKER_MAX_FILES` | `8` | Max changed files per tracker tick (hard-capped to 5-10) | | `CONTEXTPLUS_EMBED every task. Map files + symbols with line ranges. | | `semantic_navigate` | Browse codebase by meaning, not directory structure. | | `get_file_skeleton` | MUST run before full reads. Get signatures + line ranges first. | | `semantic_code_search` | Find relevant files by concept with symbol definition lines. | | `semantic_identifier_search` | Find closest functions/classes/variables and ranked call chains with line numbers. | | `get_blast_radius` | Before deleting or modifying any symbol. | | `run_static_analysis` | After writing code. Catch dead code deterministically. | | `propose_commit` | The ONLY way to save files. Validates before writing. | | `list_restore_points` | See undo history. | | `undo_change` | Revert a bad AI change without touching git. | | `get_feature_hub` | Browse feature graph hubs. Find orphaned files. | | `upsert_memory_node` | Create/update memory nodes (concept, file, symbol, note) with auto-embedding. | | `create_relation` | Create typed edges between memory nodes (depends_on, implements, etc). | | `search_memory_graph` | Semantic search + graph traversal across 1st/2nd-degree neighbors. | | `prune_stale_links` | Remove decayed edges (e^(-λt)) and orphan nodes periodically. | | `add_interlinked_context` | Bulk-add nodes with auto-similarity linking (cosine ≥ 0.72). | | `retrieve_with_tr ## File Path: landing/src/app/api/instructions/route.ts ama-powered semantic file search with symbol definition lines and 60s cache TTL. - \`semantic-identifiers.ts\` - Identifier-level semantic search returning ranked definitions + call chains with line numbers. - \`semantic-navigate.ts\` - Browse-by-meaning navigator using spectral clustering and Ollama labeling. - \`blast-radius.ts\` - Symbol usage tracer across the entire codebase. - \`static-analysis.ts\` - Native linter runner (tsc, eslint, py_compile, cargo check, go vet). - \`propose-commit.ts\` - Code gatekeeper validating headers, FEATURE tag, no inline comments, nesting, file length. - \`feature-hub.ts\` - Obsidian-style feature hub navigator with bundled skeleton views. - \`memory-tools.ts\` - Memory graph MCP wrappers (upsert, relate, search, prune, interlink, traverse). The memory graph is a **Retrieval-Augmented Generation (RAG)** system. Agents MUST use \`search_memory_graph\` at the start of every task to retrieve prior context, and persist learnings with \`upsert_memory_node\` and \`create_relation\` after completing work. This prevents redundant exploration and builds cumulative knowledge across sessions. **Core Layer** (continued): - \`hub.ts\` - Wikilink parser for \`[[path]]\` links, cross-link tags, hub discovery, orphan detection. - \`memory-graph.ts\` - In-memory property graph with JSON persistence, decay scoring, and auto-similarity edges. **Git Layer** (\`src/git/\`): - \`shadow.ts\` - Shadow restore point system for undo without touching git history. **Entry Point**: \`src for \`[[path]]\` links, cross-link tags, hub discovery, orphan detection. - \`memory-graph.ts\` - In-memory property graph with JSON persistence, decay scoring, and auto-similarity edges. **Git Layer** (\`src/git/\`): - \`shadow.ts\` - Shadow restore point system for undo without touching git history. **Entry Point**: \`src/index.ts\` registers 17 MCP tools and starts the stdio transport. Accepts an optional CLI argument for the target project root directory (defaults to \`process.cwd()\`). ## Environment Variables | Variable | Default | Description | | --------------------------------------- | ------------------ | ------------------------------------------------------------- | | \`OLLAMA_EMBED_MODEL\` | \`nomic-embed-text\` | Embedding model name | | \`OLLAMA_API_KEY\` | (empty) | Cloud auth (auto-detected by SDK) | | \`OLLAMA_CHAT_MODEL\` | \`llama3.2\` | Chat model for cluster labeling | | \`CONTEXTPLUS_EMBED_BATCH_SIZE\` | \`8\` | Embedding batch per GPU call (hard-capped to 5-10) | | \`CONTEXTPLUS_EMBED_TRACKER\` | \`true\` | Enable realtime embedding updates for changed files/functions | | \`CONTEXTPLUS_EMBED_TRACKER_MAX_FILES\` | \`8\` | Max changed files per tracker tick (hard-capped to 5-10) | | \`CONTEXTPLUS_EMBED_TRACKER_DEBOUNCE_MS\` | \`700\` | Debounce before applying tracker refresh ## File Path: landing/src/app/page.tsx > “Context engineering is the delicate art and science of filling the context window with just the right information for the next next step.”

- Andrej Karpathy