内容
# 神经元 — 人工智能的持久语义记忆
神经元是一个 **MCP 服务器**，为大型语言模型提供长期记忆。在对话过程中，它会构建一个**概念图**：每次交流都会保存关键词及其384维向量嵌入和语义链接，以便在后续会话中检索 — 按主题**上下文**，并从父上下文继承。它运行在**本地优先**（一个单独的 `.db` 文件，无需网络），并且可以选择在 Turso Cloud 上支持**共享团队记忆**，允许多人同时写入同一知识库而不会相互冲突。
- **默认本地** — 嵌入式 libSQL（pyturso）带有原生 `vector_distance_cos()`，或作为最后手段的标准库 sqlite3。无需守护进程，无需 HTTP 端口。
- **可选共享和并发** — 将所有人指向同一个 Turso Cloud 数据库。写入是增量和原子的：两个人编辑同一个节点时，两者的更改都会被记录，不会覆盖彼此的更改。参见[团队指南](docs/TEAM.md)。
- **任意 MCP 客户端** — Claude Desktop/Code、Cursor、OpenCode、VS Code、Windsurf、Zed 等通过本地 stdio；ChatGPT 通过 HTTP [桥](docs/BRIDGE.md)。
需要 **Python 3.10–3.14**。
## 安装
### Windows
```powershell
.\install.ps1
```
神经元作为一个真正的 Python 包安装到一个专用的虚拟环境中，使用来自 `.\vendor` 的**预构建 `pyturso` 轮**（Python 3.10–3.14），因此不需要 C/Rust 编译器 — 只有在 Python 版本不在预构建范围内时，才会使用最小的 MSVC 构建工具。`fastembed`（语义嵌入）是必需的。参见 **[INSTALL.md](INSTALL.md)** 以获取手动路径和故障排除。
### Linux / macOS
`pyturso` 在 PyPI 上为 Linux/macOS 提供预构建的轮，因此可以直接安装：
```bash
python3 -m venv .venv && source .venv/bin/activate
pip install neuron-<version>-py3-none-any.whl # 从 GitHub 发布
# 或，从源代码 checkout：pip install ".[dev]"
python -m neuron
```
## 存储：本地或 Turso Cloud 共享
神经元自动解析其存储层，顺序如下：
1. **Turso Cloud** — 当设置了 `TURSO_DATABASE_URL` 和 `TURSO_AUTH_TOKEN` 时。内存是共享的，并且在不同机器上持久存在；`vector_distance_cos()` 在服务器端运行。
2. **本地 pyturso** — 嵌入式 libSQL，原生向量搜索，一个本地文件（默认）。
3. **标准库 sqlite3** — 作为最后手段，Python 端的余弦相似度。
所有操作都通过一个连接层 (`neuron.db`) 进行，因此存储层可以互换，**无需代码更改** — 独立工作和团队合作的唯一区别是连接字符串。
### 开启云存储（推荐流程）
```bash
pip install "neuron[cloud]" # 添加 libsql-client
python scripts/connect_turso.py # 提示输入 URL + token，实际测试连接，然后保存到 .env（token 永远不会被打印）
```
`connect_turso.py` 在保存之前运行实时读取和写入探测，并透明地从 `libsql://` （WebSocket）URL 回退到 `https://` 如果端点拒绝 WebSocket 握手 — 保存实际可用的方案。服务器**自动加载 `.env`**，因此一旦保存，云存储就会自动使用（实际环境变量始终优先；通过 `NEURON_NO_DOTENV=1` 禁用）。要针对您的 Turso 数据库验证端到端：`python scripts/smoke_cloud.py`。
有关整个团队使用一个共享数据库的详细信息，请参见 **[团队指南](docs/TEAM.md)**。
## 知识种子
神经元可以从一个**种子图**开始，以便 AI 在第一次对话时不是空白的。种子图包含在轮子中的 `neuron/data/base_knowledge.db`；如果没有种子图，神经元将从空开始并学习。要从 Obsidian 知识库构建种子图：
```bash
export NEURON_VAULT=/path/to/vault # Windows: set NEURON_VAULT=C:\path\to\vault
python scripts/import_vault.py # -> ./knowledge/base_knowledge.db （本地）
```
仅当您故意要将其作为打包的种子时，才将结果复制到 `src/neuron/data/base_knowledge.db`。详细信息请参阅 [INSTALL.md](INSTALL.md)。
## 在 MCP 客户端中挂载
神经元是一个**本地 stdio MCP 服务器**：客户端将其作为子进程启动（`python3 -m neuron` 或 Windows 上的 `run_mcp.bat`）。挂载意味着注册启动命令。在 Windows 上，`install.ps1` 自动注册 **OpenCode**、**Claude Desktop** 和 **Cursor**；其他客户端需要一次性手动输入。
| 客户端 | 如何挂载 | 备注 |
|---|---|---|
| OpenCode, Claude Desktop, Cursor | 由 `install.ps1` 自动注册 | 重启客户端 |
| Claude Code, Cline/Roocode, VS Code, Windsurf, Zed, Continue.dev, Cody, Amazon Q | 添加启动命令 | 本地 stdio |
| **Perplexity** （macOS 应用） | 设置 → 连接器 → 添加本地 MCP (`python3 -m neuron`) | 仅限 macOS；需要 PerplexityXPC 辅助程序 |
| **ChatGPT / OpenAI** | 通过 HTTP 桥 — 参见 **[桥接指南](docs/BRIDGE.md)** | 开发人员模式，付费计划；无本地 stdio |
每个客户端的 JSON 片段位于 [`clients/`](clients/)，完整的配置指南在 **[docs/DEVELOPER.md](docs/DEVELOPER.md#mcp-client-configuration)** 中。示例，OpenCode（`~/.config/opencode/opencode.json`）：
```json
{
"mcp": {
"neuron": {
"command": ["cmd", "/c", "%LOCALAPPDATA%\\Programs\\neuron\\scripts\\run_mcp.bat"],
"type": "local"
}
},
"instructions": ["%LOCALAPPDATA%\\Programs\\neuron\\skills\\auto-context.md"]
}
```
`instructions` 字段加载自动上下文技能，该技能告诉模型在每次对话开始时调用 `neuron_pre_turn`，并在响应后调用 `neuron_store_turn`。
## 上下文继承
当活动上下文没有某个主题的结果时，`neuron_get_context` 和 `neuron_pre_turn` 会自动搜索父上下文（例如 `default`）并用 `(from:<parent>)` 注释输出 — 存储在 `default` 中的节点可以从任何上下文访问。
## MCP 工具
| 工具 | 描述 |
|---|---|
| `neuron_pre_turn(topic, keywords)` | **PRE 快捷方式** — 状态 + 紧凑上下文，一次调用 |
| `neuron_status` | 图形状态（节点，链接，活动上下文） |
| `neuron_get_context(topic, ...)` | 相关节点和链接；`format=compact` 用于注入；从父上下文继承 |
| `neuron_store_turn` | 保存一次对话：关键词，链接，实体，标签 |
| `neuron_confirm(keywords)` | 提升影响回答的节点的显著性 |
| `neuron_auto(text)` | 启发式提取 + 一次调用保存（较小模型的备用方案） |
| `neuron_extract(text)` | 独立语义提取（无保存） |
| `neuron_find_candidates(keywords)` | 在保存之前查找相似的现有关键词（重复数据删除） |
| `neuron_merge(canonical, aliases)` | 将重复节点吸收到一个规范节点 |
| `neuron_vector_search(keywords)` | 语义向量搜索（无链接遍历） |
| `neuron_summary` | 顶级节点和最近链接概览 |
| `neuron_forgotten` | N 次对话中未触及的概念 |
| `neuron_switch_context(context)` / `neuron_list_contexts` | 切换 / 列出领域上下文（例如 `java/spring`） |
| `neuron_prune` | 强制过期切线链接的修剪 |
| `neuron_flash` / `neuron_dedup` | 切换语义闪存 / 重复数据删除功能 |
| `neuron_export` / `neuron_reset` | 将图形导出为 JSON / 清空 |
## 开发
```bash
pip install -e ".[dev]"
python -m pytest tests/ -v # 单元测试（模拟 fastembed/mcp/turso — 无网络）
python -m build # 轮 + sdist（CI 在每次推送时验证）
```
架构、每个客户端的配置、数据库层和云/桥的详细信息请参阅 **[docs/DEVELOPER.md](docs/DEVELOPER.md)**。发布/CI 机制请参阅 [docs/RELEASE_PLAN.md](docs/RELEASE_PLAN.md)。
## 独立聊天（可选）
一个 CLI 游乐场 (`scripts/run_interactive.py`) 可以与云提供商通信 — 这不是**生产路径**（MCP 服务器默认使用 0-token 启发式）。提供商密钥：`OPENAI_API_KEY`、`ANTHROPIC_API_KEY`、`GEMINI_API_KEY`。
## 许可证
PolyForm Noncommercial 1.0.0 — 参见 [LICENSE](LICENSE)。
