esim

# 外部结构化意图内存（ESIM） 基于图的MCP服务器，通过Neo4j为AI助手提供持久化、结构化的内存。 ESIM将任何支持[MCP](https://modelcontextprotocol.io/)的AI客户端转变为具有长期记忆的系统，该记忆以结构化的知识图谱形式存在，具有语义搜索、关系遍历和自动诊断功能。 > **从`esm`升级？** 此版本重命名了项目（ESM → ESIM），并进行了两个破坏性模式更改。请参阅 **[MIGRATING.md](MIGRATING.md)**。 ## 工作原理 AI客户端通过MCP（stdio传输）连接到ESIM。每个知识片段都作为Neo4j图中的有类型节点存储，并具有用于语义搜索的向量嵌入。节点通过有类型的关系连接，这些关系编码了事物之间的联系。 ``` AI 客户端（Claude等） ↕ MCP（stdio） ESIM 服务器（Deno + TypeScript） ↕ Neo4j（图存储 + 向量搜索） ↕ LLM API（嵌入 + 元数据提取） ``` ## 数据模型 ### 节点类型 | 类型 | 目的 | |------|---------| | **代理** | 有意图行动的人、团队、组织或AI | | **需求** | 缺口、要求或愿望 — 具有生命周期 | | **资源** | 能力或资产 — 技能、知识、工具、预算 | | **约束** | 管辖力量 — 优先级、理解、方法、机制 | | **输出** | 代理产生的某物 | | **角色** | 命名的功能或职位 | | **信号** | 观察 — 具体数据 + 解释 | | **会话** | 有界交互或工作会话 | | **差异** | 意图和输出之间的差距 | | **库存** | 可衡量的积累（信任、知识、容量） | ### 关系类型 23种有类型关系，包括`PURPOSE`、`CONTAINS`、`FILLS`、`GOVERNS`、`OWNS`、`SERVES`、`SIGNALS`、`SCOPED_TO`、`TRIGGERED_BY`、`AFFECTS`、`GOVERNED_BY`等。完整列表请参见`src/types.ts`。 ## 结构化意图模型 ESIM的节点和关系类型并非通用 — 它们编码了特定的意图结构模型。理解该模型是使图谱有用的关键；如果没有它，你只会有类型化的框。 核心思想：**意图具有结构，而且该结构可以被显式表达、存储和诊断。** 大多数意图都隐含地存在 — 在某人的脑海中，散布在文档中，假设但从未被陈述。结构化意图将其公开为一个图谱，你可以对其进行推理。 ### 意图框架 — 六层 中心对象是**意图框架**：单个实体的完整配置 — 一个人、团队、项目、工具或角色。完整的框架回答了六个问题，从*为什么*到*如何*逐层递进。每一层都由一个ESIM基本元素表达，你已经拥有，每个元素都有不同的评判标准： | 层级 | 问题答案 | ESIM 基本元素 | 良好形成时... | |-------|---------------------|---------------|-------------------| | **1. 目的** | 为什么存在？ | `PURPOSE` 边（+ `purpose_type`） | 它指向外部，指向它服务的对象或事物 | | **2. 理解** | 我们认为什么是真的？ | `Constraint`（`understanding`） | 图片是*完整的* — 没有未陈述的假设 | | **3. 优先级** | 冲突时什么优先？ | `Constraint`（`priority`) | 每个优先级都采取明确的*立场*，面对实际的紧张关系 | | **4. 方法** | 我们如何进行？ | `Constraint`（`approach`） | 方法与上述优先级*兼容* | | **5. 组成** | 它由什么组成？ | `CONTAINS` 边（带 `order`） | 零件*凝聚* — 它们组合在一起 | | **6. 机制** | 什么具体的机制运行它？ | `Constraint`（`mechanics`） | 它与上述所有内容*集成* | 层级**级联**：目的塑造了人们需要理解的内容，而理解又塑造了哪些优先级在发挥作用，优先级又塑造了方法，以此类推。因此，底部的问题（工具、例行程序）通常可以追溯到顶部未陈述的内容（未检查的理解、未声明的目的） — 这就是为什么你需要从症状出发，向上遍历来诊断。 其中两个不是节点，而是边：目的和组成描述了一个实体*如何关联* — 到它服务的对象和它自己的部分。其他四个是`Constraint`节点，由`constraint_type`区分。所有这些都不是你开启的特性；六个层级是你观察ESIM已经存储的内容的视角。 > **命名说明：** 四个约束层存储为`Constraint`节点，`constraint_type`为`understanding`、`priority`、`approach`或`mechanics`。目的和组成不是约束类型 — 它们是`PURPOSE`和`CONTAINS`边。 ### 目的存在于边上，而不是节点上 一个实体的目的不是它拥有的属性 — 它是指向它所服务的对象的一组`PURPOSE`边。一个人、团队或工具*存在以做某事*，而“为了某人”是方向性的，所以它是一条边。没有目的边的实体不具有意图 — 它只是反应。 每条`PURPOSE`边都带有类型： | 目的类型 | 含义 | |--------------|---------| | **创建** | 新价值进入系统 | | **维持** | 现有价值抵御熵 | | **转化** | 价值通过处理改变形式 | | **启用** | 价值到达它原本无法到达的目的地 | ### 意图公式 结构化意图通过一个关系读取每个输出： ``` (需求 + 资源) / 约束 = 输出 ``` - **需求** — 需要什么。 - **资源** — 有什么可用（技能、知识、工具、预算、能力）。 - **约束** — 影响潜在产出的因素。 - **输出** — 实际产生的产出。 约束是杠杆。 与目的相符时，约束*倍增*产出（杠杆效应）；而不相符时，约束*消耗*潜力（税收）。 该公式将模糊的“这不奏效”转化为一个可定位的问题：*哪个约束对产出造成了税收？* ### 目的 vs. 功能 **目的** 是实体存在的目的（声明）。**功能** 是实体实际被使用的功能（观察）。混淆两者是大多数不一致的根源 — 把黄油刀用作螺丝刀可以勉强凑合，但刀会损坏，螺丝也无法正确安装。ESIM 将声明的目的和观察到的功能作为独立、可比较的事物；两者之间的差距是一个一等节点（`Discrepancy`）。 ### 构建意图 — 工作流程 "意图构建" 是为特定实体构建一个完整的框架，直到它完整且连贯。在ESIM中，这是使用工具调用的具体顺序： 1. **创建实体。** `create_entity` 一个`Agent`（或`Role`）— 你要构建其意图的实体。 2. **声明目的。** 从它到它所服务的对象连接`PURPOSE`边，每个边都有一个`purpose_type`。没有目的边意味着没有意图 — 只是反应。 3. **添加四个约束层。** 为理解、优先级、方法和机制创建`Constraint`节点（`constraint_type`为`understanding`、`priority`、`approach`、`mechanics`）；用`GOVERNS`连接它们。 4. **组成它。** 如果实体有部分，创建它们并连接`CONTAINS`（带`order`）— 这是组成层。 5. **附加需求和资源。** 创建所需的需求和可用的资源节点。 6. **捕获证据。** 随着现实产生观察结果，使用`create_signal`将它们记录在相关实体中 — 在声明的意图一侧，在观察到的信号一侧。 7. **校准。** 将声明的框架与积累的信号进行比较。 当它们偏离时，显示一个`Discrepancy`。 关闭这个差距 — 通过更新框架或改变行为 — 是整个练习的重点。 步骤1-5是**声明**（你打算做什么）；步骤6-7是**校准**（使意图与现实相符）。 一个框架永远不会“完成” — 它在每次校准时都会变得更加清晰。 ### 技能的位置 [`skills/`](skills/)目录将此模型转化为有指导的实践： - [`purpose-discovery`](skills/purpose-discovery/SKILL.md) — 引导一个人从头到尾构建他们的第一个框架（步骤1-5）。 - [`session-protocol`](skills/session-protocol/SKILL.md) — 管理助手如何在持续工作中捕获信号并保持图谱校准（步骤6-7）。 - [`signal-processing`](skills/signal-processing/SKILL.md) — 系统地处理捕获的信号以更新图谱（校准背后的引擎）。 ## 安装 ### 先决条件 - [Deno 2+](https://deno.land/) - Neo4j（云或本地） - 用于嵌入和补全的OpenAI兼容API ### 快速入门（Docker + OpenAI） ```bash # 启动本地Neo4j docker compose up -d # 配置环境（推荐：系统范围的配置文件目录） mkdir -p ~/.config/env cp .env.example ~/.config/env/esim.env # 编辑 ~/.config/env/esim.env — 取消Docker行的注释，添加您的OpenAI密钥 # 初始化模式（创建向量索引 + 约束） deno task setup # 注册Claude Code（使用您的克隆的绝对路径） claude mcp add esim -- deno run --allow-net --allow-env --allow-read --allow-sys \ /absolute/path/to/esim/src/main.ts # 验证 claude mcp list # 应该显示“esim” ``` ### 完全本地设置（Docker + Ollama） 对于完全自主的设置，无需外部API调用： 1. 安装 [Ollama](https://ollama.com/) 并拉取模型： ```bash ollama pull qwen3-embedding:0.6b # 嵌入 — 见下文“选择嵌入模型” ollama pull llama3.2 # 元数据提取/分类 ``` 2. 启动Neo4j： ```bash docker compose up -d ``` 3. 配置环境： ```bash mkdir -p ~/.config/env cp .env.example ~/.config/env/esim.env ``` 编辑 `~/.config/env/esim.env` — 取消Docker和Ollama部分的注释： ```env NEO4J_DB_CONNECTION_URI=bolt://localhost:7687 NEO4J_DB_USERNAME=neo4j NEO4J_DB_PASSWORD=password LLM_BASE_URL=http://localhost:11434/v1 LLM_API_KEY=ollama LLM_EMBEDDING_MODEL=qwen3-embedding:0.6b LLM_EMBEDDING_DIMENSIONS=1024 LLM_COMPLETION_MODEL=llama3.2 ``` 4. 初始化和注册： ```bash deno task setup claude mcp add esim -- deno run --allow-net --allow-env --allow-read --allow-sys \ /absolute/path/to/esim/src/main.ts ``` ### 云设置（Neo4j Aura + OpenAI/OpenRouter） 1. 创建一个免费的 [Neo4j Aura](https://neo4j.com/cloud/aura/) 实例 2. 配置环境： ```bash mkdir -p ~/.config/env cp .env.example ~/.config/env/esim.env ``` 编辑 `~/.config/env/esim.env`： ```env NEO4J_DB_CONNECTION_URI=neo4j+s://xxxx.databases.neo4j.io NEO4J_DB_USERNAME=neo4j NEO4J_DB_PASSWORD=your-password LLM_BASE_URL=https://api.openai.com/v1 LLM_API_KEY=sk-... ``` 3. 初始化和注册： ```bash deno task setup claude mcp add esim -- deno run --allow-net --allow-env --allow-read --allow-sys \ /absolute/path/to/esim/src/main.ts ``` ## 环境变量 | 变量 | 默认值 | 必需 | 描述 | |----------|---------|----------|-------------| | `NEO4J_DB_CONNECTION_URI` | — | 是 | Neo4j连接字符串 | | `NEO4J_DB_USERNAME` | — | 是 | Neo4j用户名 | | `NEO4J_DB_PASSWORD` | — | 是 | Neo4j密码 | | `LLM_API_KEY` | — | 是 | 您使用的LLM提供商的API密钥 | | `LLM_BASE_URL` | `https://api.openai.com/v1` | 否 | 任何OpenAI兼容的端点 | | `LLM_EMBEDDING_MODEL` | `text-embedding-3-small` | 否 | 嵌入模型名称 | | `LLM_EMBEDDING_DIMENSIONS` | `1536` | 否 | 必须与嵌入模型的输出匹配 | | `LLM_COMPLETION_MODEL` | `gpt-4o-mini` | 否 | 分类和元数据提取的模型 | 环境加载顺序如下（先找到的为准）： 1. `ESIM_ENV_FILE` 环境变量（显式覆盖 — 适用于多实例设置） 2. `~/.config/env/esim.env`（推荐 — 无论工作目录如何都有效） 3. `.env` 在仓库根目录（开发的备用） **重要：** `LLM_EMBEDDING_DIMENSIONS` 必须与嵌入模型的输出完全匹配。常见值：`qwen3-embedding:0.6b`（Ollama）= 1024，`nomic-embed-text`（Ollama）= 768，`text-embedding-3-small`（OpenAI）= 1536。如果您在设置后更改模型，请删除并重新创建索引 — 请参阅 **选择嵌入模型** 下文。 ## 选择嵌入模型 语义搜索质量主要由嵌入模型决定，而对于ESIM，一个因素比基准分数更重要：**上下文窗口。** ESIM嵌入整个节点，而不仅仅是短标签 — 单个节点可以保存几个段落（信号存储其完整推理，而不仅仅是标题）。如果模型的上下文窗口小于节点，则它只嵌入开头并静默丢弃其余部分，悄悄地降低搜索质量。 **选择一个上下文窗口舒适地超过您最长的节点。** 这就是为什么 `mxbai-embed-large` 尽管英语召回率强，但在这里是一个糟糕的选择：其512-token窗口截断了更丰富的`context`字段 — 对ESIM来说是一个糟糕的选择。 维度计数影响较小。ESIM图谱很小 — 数百到几千个节点 — 因此通常的“更多维度=更多存储且搜索速度更慢”的权衡可忽略不计。使用模型的原生维度即可。 ### 选项（Ollama / 本地） | 模型 | 原始维度 | 上下文 | 适合ESIM | |-------|-------------|---------|--------------| | **`qwen3-embedding:0.6b`** — 推荐 | 1024 | 32K | 2026本地质量，多语言（100+语言），上下文大到永远不会截断。~640 MB。 | | `bge-m3` | 1024 | 8K | 已证明，多语言，还发出稀疏向量（后期混合搜索的路径）。~1.2 GB。 | | `embeddinggemma` | 768 | 2K | RAM紧张时最佳质量每字节。~300 MB。 | | `nomic-embed-text` | 768 | ~2K | 轻量级基线 — 被上述选项改进。~274 MB。 | | `mxbai-embed-large` | 1024 | **512** ⚠️ | 英文召回率强，但512-token窗口截断了丰富的`context`字段 — 对ESIM来说是一个糟糕的选择。 | 对于OpenAI/云，`text-embedding-3-small`（1536）和`text-embedding-3-large`（3072）都有足够的上下文，不需要特殊处理。 ### 更改模型后设置 嵌入模型之间的嵌入 **不可比较** — 切换模型意味着重新嵌入每个节点，即使维度计数相同： ```bash # 1. 在.env文件中设置LLM_EMBEDDING_MODEL + LLM_EMBEDDING_DIMENSIONS # 2. 删除旧的向量索引 | 3. 丢弃旧的索引 deno run --allow-net --allow-env --allow-read --allow-sys scripts/drop-indexes.ts # 4. 在新维度下重新创建索引 deno task setup # 4. 使用新模型为每个节点重新嵌入 deno run --allow-net --allow-env --allow-read --allow-sys scripts/reembed.ts ``` > **注意：** `scripts/reembed.ts` 仅重新嵌入维度不同的节点。如果您切换模型但保留相同的维度，它将不会注意到更改 — 请先清除旧嵌入，或更改维度以强制完全重新嵌入。 ## MCP 连接 ### Claude 代码 ```bash claude mcp add esim -- deno run --allow-net --allow-env --allow-read --allow-sys /path/to/esim/src/main.ts ``` 验证：`claude mcp list` 应该显示 `esim` 可用。 ### Claude 桌面 将以下内容添加到您的MCP配置中（根据平台位置不同而有所不同 — 请参阅Claude Desktop 文档）： ```json { "mcpServers": { "esim": { "command": "deno", "args": ["run", "--allow-net", "--allow-env", "--allow-read", "--allow-sys", "/path/to/esim/src/main.ts"] } } } ``` 重启Claude Desktop 后编辑。 ESIM 工具将出现在工具菜单中。 ### 验证连接 注册后，通过在Claude Code 中询问它运行 `stats` 来测试连接。您应该会收到节点/边计数（在全新安装时均为零）。如果您遇到连接错误，请参阅下面的故障排除。 ## MCP 工具 | 工具 | 描述 | |------|-------------| | `setup_schema` | 创建向量索引和约束（幂等） | | `capture` | 统一入口 — 自动分类和存储任意内容 | | `create_entity` | 创建带有自动嵌入的类型化实体节点 | | `create_signal` | 捕获带有数据 + 解释的观察结果 | | `create_session` | 启动带有参与者和范围的会话 | | `create_relationship` | 用类型化边线连接节点 | | `search` | 跨向量索引进行语义搜索 | | `get_node` | 获取带有所有关系的节点 | | `get_context` | 重建主题或实体的上下文 | | `traverse` | 带过滤器的多跳图遍历 | | `list` | 按类型、最近时间或状态浏览节点 | | `stats` | 摘要统计数据和关注项 | | `run_diagnostic` | 图谱的结构健康检查 | | `update_node` | 更新现有节点的属性 | | `delete_node` | 删除节点及其关系 | ## 工具参考 ### `setup_schema` 在Neo4j中创建向量索引和唯一性约束。幂等 — 可以多次安全运行。 **参数：** 无 ```json {} ``` --- ### `capture` 统一入口 — 发送任意内容，它将被分类、嵌入并存储为适当的节点类型。此方法是添加数据最简单的方式。分类器自动确定节点类型，或者您可以提供提示以跳过分类。 **参数：** | 名称 | 类型 | 必需 | 描述 | |------|------|----------|-------------| | `content` | 字符串 | 是 | 要捕获的内容 — 任意文本 | | `hints` | 对象 | 否 | `{ node_type?: string, name?: string }` — 指导或跳过分类 | ```json // 最简洁 — 让分类器决定类型 { "content": "我们需要将身份验证服务迁移到OAuth 2.1之前 Q3" } // 带有提示 — 跳过分类 { "content": "Kurt 是平台团队的工程经理", "hints": { "node_type": "Agent", "name": "Kurt" } } ``` --- ### `create_entity` 创建类型化的实体节点（Agent、Need、Resource、Constraint、Output、Role）。自动生成嵌入并通过LLM提取元数据。显式属性覆盖LLM提取的值。 **参数：** | 名称 | 类型 | 必需 | 描述 | |------|------|----------|-------------| | `entity_type` | 字符串 | 是 | 以下之一：`Agent`、`Need`、`Resource`、`Constraint`、`Output`、`Role` | | `name` | 字符串 | 是 | 实体显示名称 | | `content` | 字符串 | 否 | 描述/上下文 — 用于嵌入生成 | | `properties` | 对象 | 否 | 附加属性 — 显式值覆盖LLM提取的元数据 | ```json { "entity_type": "Agent", "name": "Ada", "content": "专注于平台基础设施的工程经理" } { "entity_type": "Need", "name": "身份验证迁移", "content": "将身份验证服务迁移到OAuth 2.1", "properties": { "lifecycle_state": "open", "priority": "high" } } ``` --- ### `create_signal` 捕获带有可选上下文的观察结果。当提供ID时，自动创建`OBSERVED_BY`、`SIGNALS`和`PRODUCED_IN`边。观察者撰写的字段（`observation`、`context`、`how_observed`、`confidence`、`perceived_impact`）是神圣的 — 永远不会被系统覆盖。 **参数：** | 名称 | 类型 | 必需 | 描述 | |------|------|----------|-------------| | `observation` | 字符串 | 是 | 从观察者的角度来看发生了什么 — 事实的、可验证的 | | `context` | 字符串 | 否 | 观察者撰写的情境、环境或假设 | | `observed_by_agent_id` | 字符串 | 否 | 捕获此信号的代理ID | | `signals_entity_id` | 字符串 | 否 | 此信号所关的实体ID | | `produced_in_session_id` | 字符串 | 否 | 捕获此信号的会话ID | | `properties` | 对象 | 否 | 附加属性（how_observed、confidence、perceived_impact、disposition、disposition_note等） | ```json { "observation": "API延迟p99在部署后从200ms增加到850ms", "context": "新的身份验证中间件在2小时前部署，延迟立即开始增加", "signals_entity_id": "uuid-of-auth-service" } ``` --- ### `create_session` 启动具有参与者、范围和触发器的会话。创建`PARTICIPATES_IN`、`SCOPED_TO`和`TRIGGERED_BY`边。 **参数：** | 名称 | 类型 | 必需 | 描述 | |------|------|----------|-------------| | `name` | 字符串 | 是 | 会话名称 | | `content` | 字符串 | 否 | 会话描述/摘要 | | `participant_ids` | 字符串[] | 否 | 参与者的代理ID | | `scoped_to_id` | 字符串 | 否 | 此会话所关的实体ID | | `triggered_by_signal_ids` | 字符串[] | 否 | 触发此会话的信号ID | | `properties` | 对象 | 否 | 附加属性（session_type、trigger_type等） | ```json { "name": "身份验证迁移规划", "content": "OAuth 2.1迁移的规划会话", "participant_ids": ["agent-uuid-1", "agent-uuid-2"], "scoped_to_id": "need-uuid", "properties": { "session_type": "planning" } } ``` --- ### `create_relationship` 在两个节点之间创建23种关系类型之一，并带有可选的边属性。 **参数：** | 名称 | 类型 | 必需 | 描述 | |------|------|----------|-------------| | `from_id` | 字符串 | 是 | 源节点ID | | `to_id` | 字符串 | 是 | 目标节点ID | | `relationship_type` | 字符串 | 是 | 以下之一：`PURPOSE`、`CONTAINS`、`FILLS`、`GOVERNS`、`OWNS`、`SERVES`、`GENERATED_BY`、`REQUIRES`、`PRODUCES`、`EVALUATED_AGAINST`、`HAS_STOCK`、`SIGNALS`、`OBSERVED_BY`、`FLAGGED_AT`、`PRODUCED_IN`、`PARTICIPATES_IN`、`SCOPED_TO`、`TRIGGERED_BY`、`DEFINED_BY`、`ESCALATED_TO`、`RELATED_TO` | | `properties` | 对象 | 否 | 边属性 | ```json { "from_id": "agent-uuid", "to_id": "need-uuid", "relationship_type": "OWNS" } ``` --- ### `search` 跨向量索引的语义搜索。返回按余弦相似度排序的结果。 **参数：** | 名称 | 类型 | 必需 | 默认值 | 描述 | |------|------|----------|---------|-------------| | `query` | 字符串 | 是 | — | 自然语言搜索查询 | | `index` | 字符串 | 否 | `"all"` | 索引：`all`、`entity`、`signal`、`session`、`discrepancy` | | `limit` | 数字 | 否 | `10` | 每个索引的最大结果数 | | `threshold` | 数字 | 否 | `0.5` | 最低相似度分数（0–1） | ```json { "query": "身份验证和授权" } { "query": "延迟问题", "index": "signal", "limit": 5, "threshold": 0.7 } ``` --- ### `get_node` 通过ID获取节点及其所有关系和连接的节点。 **参数：** | 名称 | 类型 | 必需 | 描述 | |------|------|----------|-------------| | `id` | 字符串 | 是 | 节点ID（UUID） | ```json { "id": "550e8400-e29b-41d4-a716-446655440000" } ``` --- ### `get_context` 重建围绕主题或实体的上下文。返回语义锚、活动线程、结构邻居、注意力项，以及可选的发现建议。 **参数：** | 名称 | 类型 | 必需 | 默认值 | 描述 | |------|------|----------|---------|-------------| | `query` | 字符串 | 是 | — | 查找相关上下文的自然语言查询 | | `entity_id` | 字符串 | 否 | — | 锚定到已知的实体ID而不是搜索 | | `include_discoveries` | 布尔值 | 否 | `true` | 包括发现建议 | ```json { "query": "身份验证迁移的进展如何" } { "query": "平台团队优先级", "entity_id": "agent-uuid", "include_discoveries": false } ``` --- ### `traverse` 从起始节点的多跳图遍历。按关系类型（s）、控制深度和方向进行筛选。 **参数：** | 名称 | 类型 | 必需 | 默认值 | 描述 | |------|------|----------|---------|-------------| | `id` | 字符串 | 是 | — | 起始节点ID | | `relationship_types` | 字符串[] | 否 | all | 筛选到特定的关系类型 | | `max_depth` | 数字 | 否 | `3` | 最大遍历深度（1–10） | | `direction` | 字符串 | 否 | `"both"` | `both`、`outgoing`或`incoming` | ```json { "id": "agent-uuid", "relationship_types": ["OWNS", "PRODUCES"], "max_depth": 2, "direction": "outgoing" } ``` --- ### `list` 浏览捕获的节点，并带有可选筛选器。 **参数：** | 名称 | 类型 | 必需 | 默认值 | 描述 | |------|------|----------|---------|-------------| | `days` | 数字 | 否 | — | 仅限最近N天的节点 | | `type` | 字符串 | 否 | — | 按节点标签筛选（例如`Signal`、`Agent`、`Need`） | | `status` | 字符串 | 否 | — | 按状态字段筛选 | | `limit` | 数字 | 否 | `20` | 最大结果数 | ```json { "type": "Signal", "days": 7, "limit": 10 } { "type": "Need", "status": "open" } ``` --- ### `stats` 汇总统计数据：节点类型计数、边计数、7天活动和注意力项（未处理的信号、开放的需求）。 **参数：** 无 ```json {} ``` --- ### `run_diagnostic` 图的健康检查。 **参数：** | 名称 | 类型 | 必需 | 默认值 | 描述 | |------|------|----------|---------|-------------| | `checks` | 字符串[] | 否 | `["all"]` | 运行诊断：`unattached_needs`、`missing_purpose`、`overloaded_agents`、`phantom_sessions`、`entities_without_purpose`、`unprocessed_signals`、`ego_drift_check`、`constraint_role_analysis`、`all` | ```json {} { "checks": ["unprocessed_signals", "unattached_needs"] } ``` --- ### `update_node` 通过ID更新现有节点的属性。合并现有属性 — 只有指定的字段更改，未提及的字段保留。如果`content`或`name`更改，则重新生成嵌入。不能覆盖`id`或`created_at`。 **参数：** | 名称 | 类型 | 必需 | 描述 | |------|------|----------|-------------| | `id` | 字符串 | 是 | 要更新的节点ID（UUID） | | `properties` | 对象 | 是 | 要设置或更新的属性 — 与现有属性合并 | ```json { "id": "550e8400-e29b-41d4-a716-446655440000", "properties": { "status": "resolved_into_update" } } { "id": "550e8400-e29b-41d4-a716-446655440000", "properties": { "name": "更新的名称", "content": "新描述触发重新嵌入" } } ``` --- ### `delete_node` 删除节点及其所有关系。不可逆。 **参数：** | 名称 | 类型 | 必需 | 描述 | |------|------|----------|-------------| | `id` | 字符串 | 是 | 要删除的节点ID（UUID） | ```json { "id": "550e8400-e29b-41d4-a716-446655440000" } ``` ## 安全与隐私 **ESIM设计用于本地、单用户环境。** 它作为stdio MCP服务器运行 — AI客户端和ESIM通过本地机器的标准输入/输出进行通信。没有网络身份验证层。 不要在没有添加自己的身份验证的情况下将ESIM暴露在网络上。任何具有MCP传输访问权限的人都可以读取和写入图中的所有数据。 **数据流感知：** - 默认情况下，节点内容被发送到您配置的LLM API（OpenAI、OpenRouter等）用于嵌入生成和元数据提取。 - 如果您需要零外部数据共享，请使用完全本地设置和Ollama — 所有处理都保留在您的机器上。 - 所有图数据都存储在您的Neo4j实例中。您负责确保其安全。 ## 项目结构 ``` src/ main.ts — 入口点 server.ts — MCP工具注册 db.ts — Neo4j连接和查询运行器 queries.ts — Cypher查询构建器 types.ts — TypeScript类型和常量 llm.ts — LLM集成（嵌入 + 元数据） classify.ts — 内容分类 context.ts — 上下文重建 env.ts — 环境变量加载 schema.ts — 模式设置脚本 ``` ## 故障排除 **"缺少NEO4J_DB_CONNECTION_URI"** — 未找到环境文件。检查`~/.config/env/esim.env`是否存在，或显式设置`ESIM_ENV_FILE`： ```bash ESIM_ENV_FILE=/path/to/your/.env deno task setup ``` **"Neo4j连接失败"** — Docker未运行或URI错误。验证Neo4j是否正在运行： ```bash docker compose ps # 显示neo4j正在运行 docker compose up -d # 需要时重启 ``` **"嵌入请求失败（401）"** — 无效的`LLM_API_KEY`或错误的`LLM_BASE_URL`。与提供商验证您的API凭证。 **"向量索引创建时维度错误"** — `LLM_EMBEDDING_DIMENSIONS`与您的模型不匹配。删除并重新创建： ```bash deno run --allow-net --allow-env --allow-read --allow-sys scripts/drop-indexes.ts deno task setup ``` **Claude Code看不到ESIM工具** — 重新注册并验证： ```bash claude mcp remove esim claude mcp add esim -- deno run --allow-net --allow-env --allow-read --allow-sys /absolute/path/to/esim/src/main.ts claude mcp list ``` ## 技能 ESIM附带[Claude Code](https://claude.com/claude-code)技能，位于[`skills/`](skills/)中，将原始图转换为有指导的结构意图实践： - **[`purpose-discovery`](skills/purpose-discovery/SKILL.md)** — 促进第一次结构意图会话：发现实体的核心目的、约束栈和基础图。 - **[`session-protocol`](skills/session-protocol/SKILL.md)** — 一个操作协议，控制助手如何加载上下文、捕获信号以及在任何ESIM会话期间保持图同步。 - **[`signal-processing`](skills/signal-processing/SKILL.md)** — 将捕获的信号处理为图状态更新，以便图保持一致和完整。 参见[`skills/README.md`](skills/README.md)了解如何加载它们。 ## 许可证 Apache 2.0 — 参见[LICENSE](LICENSE)。