内容
# 健忘症
[](https://github.com/SabilMurti/Amneshia/releases)
[](LICENSE)
[](https://github.com/SabilMurti/Amneshia/actions)
[](https://github.com/SabilMurti/Amneshia/actions)
统一的、零外部数据库的、多智能体的长期记忆中心。构建在 **SQLite FTS5 + BM25 搜索** 之上，集成了 **通用 MCP 桥接管理器**、本地 **睡眠周期记忆巩固引擎** 和交互式的 **Amneshia 网页仪表盘**。
---
## 架构图
Amneshia 协调标准输入输出和 SSE/HTTP 传输，管理底层存储、后台巩固任务和 MCP 集成：
```mermaid
flowchart TB
%% 类定义用于样式
classDef client fill:#1e1e2e,stroke:#a855f7,stroke-width:2px,color:#fff;
classDef transport fill:#1e1e2e,stroke:#06b6d4,stroke-width:2px,color:#fff;
classDef core fill:#181825,stroke:#3b82f6,stroke-width:2px,color:#fff;
classDef bridge fill:#1e1e2e,stroke:#f59e0b,stroke-width:2px,color:#fff;
classDef db fill:#11111b,stroke:#10b981,stroke-width:2px,color:#fff;
subgraph 客户端 ["1. 客户端和智能体 IDE"]
Agent["🤖 AI 智能体（Antigravity IDE / Cursor / Windsurf / Claude Code）"]:::client
Browser["🌐 Amneshia 网页仪表盘（React 18 + Vite）"]:::client
end
subgraph 传输层 ["2. 传输和通信层"]
Stdio["⚡ 标准输入输出传输（JSON-RPC 2.0）"]:::transport
SSE["🌐 HTTP / SSE 服务器（端口 3457）"]:::transport
REST["🔗 REST API 端点"]:::transport
end
subgraph Amneshia ["3. Amneshia v2 核心知识引擎"]
MCP["🛠️ 18 个 MCP 工具表面"]:::core
Graph["知识图谱引擎"]:::core
Sleep["🌙 睡眠周期巩固引擎"]:::core
Exporter["📄 Markdown 自动导出器"]:::core
DB[("💾 SQLite FTS5 存储（~/.amneshia/memory.db）")]:::db
end
subgraph 桥接系统 ["4. 通用 MCP 桥接系统"]
Bridge["🔌 桥接客户端管理器"]:::bridge
CM["💻 代码库内存 MCP（端口 9749）"]:::bridge
Other["🌐 外部自定义 MCP 服务器"]:::bridge
end
%% 流程连接
Agent <-->|标准输入输出流 / SSE| Transport
Browser <-->|HTTP REST API| REST
Stdio <-->|JSON-RPC| MCP
SSE <-->|HTTP 事件| REST
REST <-->|API 处理器| Graph
MCP <-->|CRUD 和 FTS 查询| Graph
Graph <-->|BM25 搜索和 SQL 触发器| DB
Sleep <-->|Jaccard 剪枝和冲突替代| DB
Graph -->|同步 Markdown 镜像| Exporter
Graph <-->|桥接代理工具| Bridge
Bridge <-->|自动同步项目| CM
Bridge <-->|代理工具调用| Other
```
---
## 主要功能
- **语义知识图谱** — 不是一个简单的、扁平的键值存储。实体通过结构化、类型的关系和观察进行组织。
- **FTS5 BM25 搜索** — 将 SQLite FTS5 扩展与 BM25 排名相结合，实现快速、容错的全文本查询查找。
- **通用 MCP 桥接** — 与外部 MCP 服务器（例如 `codebase-memory-mcp`）互操作，允许动态同步外部事实和工具。
- **睡眠周期记忆巩固** — 在睡眠/空闲状态下评估相似性指标（Jaccard 相似性 $\ge 0.8$）和 LLM 上下文分析，以删除重复记忆、解决冲突、跟踪更新历史和清除过期临时数据。
- **访问控制白名单** — 可见性属性（`public`、`restricted`、`private`）和白名单数组（`allowedAgents`）防止未经授权的智能体访问。
- **Amneshia 网页仪表盘** — 采用 TasteSkill 抗疲劳指南构建的丰富视觉界面，用于探索图谱、管理目标导出、控制桥接服务器和查看记忆统计。
---
## 快速入门
### 1. 通过 GitHub 直接运行
您可以直接从 GitHub 运行 Amneshia，无需安装任何软件：
```bash
# 在后台守护模式下运行 HTTP 网页仪表盘和 REST API
amneshia --http --port 3457 --daemon
# 或直接通过 npx 从 GitHub 运行：
npx -y github:SabilMurti/Amneshia --http --port 3457 --daemon
```
或通过 GitHub 全局安装：
```bash
npm install -g github:SabilMurti/Amneshia
# 在后台守护模式下运行：
amneshia --http --daemon
```
### 2. 标准输入输出模式（标准 IDE 集成）
要将 Amneshia 连接到您的编辑器/智能体环境（例如 Cursor、Antigravity IDE、Claude Code），请在 MCP 配置文件（`mcp_config.json`）中添加服务器条目：
```json
{
"mcpServers": {
"amneshia": {
"command": "npx",
"args": ["-y", "github:SabilMurti/Amneshia"]
}
}
}
```
---
## 完整的 MCP 工具参考（18 个工具）
Amneshia 向客户端智能体公开了 18 个专门的工具，用于管理记忆周期、查询数据和桥接其他服务器：
| 类别 | 工具名称 | 参数 | 描述 |
| :--- | :--- | :--- | :--- |
| **实体** | `create_entities` | `entities`（实体输入数组） | 创建具有类型、域和访问白名单的新唯一实体。 |
| | `delete_entities` | `names`（字符串数组） | 删除实体并将其观察和关系级联删除。 |
| **关系** | `create_relations` | `relations`（关系输入数组） | 在实体之间建立类型连接（例如 `creator_of`、`works_on`）。 |
| | `delete_relations` | `ids`（字符串数组） | 按 ID 删除指定的关系。 |
| **观察** | `add_observations` | `observations`（观察输入数组） | 将原始观察或 LLM 合成事实附加到实体。 |
| | `delete_observations`| `ids`（字符串数组） | 删除指定的观察。 |
| | `update_observation` | `id`（字符串）、`content`（字符串）、`changedBy`？ | 更新观察内容，同时记录更改历史。 |
| **查询和图谱**| `search_memory` | `query`（字符串）、`limit`？ | 在实体名称、类型和观察中执行 FTS5 BM25 搜索。 |
| | `read_graph` | `domain`？、`entityType`？ | 检索完整或过滤的知识图谱快照。 |
| | `open_nodes` | `names`（字符串数组） | 检索特定节点的完整属性、观察和关系。 |
| **生命周期** | `cleanup_expired` | *无* | 删除已过期的临时观察。 |
| | `consolidate_memory`| `domain`？ | 执行冲突解决、近似重复的 Jaccard 剪枝和合成。 |
| | `get_stats` | *无* | 返回存储指标、实体域分解和最近活动日志。 |
| **导出** | `export_memory` | *无* | 将当前图谱快照导出到活动 Markdown 目标。 |
| | `manage_export_targets`| `action`、`name`？、`path`？、`format`？、`id`？、`autoExport`？ | 注册、删除或切换自动导出 Markdown 路径。 |
| | `configure_ai` | `provider`（字符串） | 更改默认 AI 合成提供商（`none`、`9router`、`ollama`、`openai`）。 |
| **通用桥接**| `manage_bridge_servers`| `action`（字符串）、`name`？、`command`？、`args`？、`id`？ | 在 SQLite 中添加、列出或删除下游桥接 MCP 服务器。 |
| | `list_bridge_tools` | `serverId`（字符串）、`command`？、`args`？ | 查询桥接服务器以检索其公开的工具。 |
| | `call_bridge_tool` | `serverId`（字符串）、`toolName`（字符串）、`arguments`？ | 在桥接服务器上执行工具并返回结果。 |
---
## 网页仪表盘和代码库集成
Amneshia 在 `http://localhost:3457` 上提供网页客户端，当以 HTTP 模式运行时。客户端提供：
1. **交互式图谱可视化器**，用于查看实体链接和节点集群。
2. **桥接管理器**，用于注册下游 MCP 服务器（例如 `codebase-memory-mcp`）和配置命令/参数。
3. **设置控制**，用于切换 LLM 提供商（9router AG、Ollama、OpenAI 或 None）和管理自动导出 Markdown 日志。
### 代码库内存 MCP 桥接同步
[**codebase-memory-mcp**](https://github.com/DeusData/codebase-memory-mcp) 是 DeusData 的一个高级 MCP 服务器，它为 AI 智能体创建结构化的代码库知识图谱（AST 分析、函数签名、依赖树和 git 元数据）。
当 `codebase-memory-mcp` 配置为 Amneshia 中的桥接服务器并启用时，系统通过 `/api/bridge/sync` REST 端点（或 `call_bridge_tool`）支持一键跨图谱同步。这会触发对桥接服务器的活动代码库索引的自动扫描，导入：
- 工作区根路径。
- 代码库节点和边的指标。
- 活动 git 分支和提交 SHA。
这些同步的详细信息直接存储在项目实体的观察中，前缀为 `[Codebase Memory MCP]`。
---
## 推荐的智能体指令/系统规则
要为您的 AI 智能体（Cursor、Antigravity IDE、Claude Code、Windsurf 等）提供最佳的长期记忆行为，请将以下提示规则复制并粘贴到您的智能体的自定义指令文件中（例如 `GEMINI.md`、`CLAUDE.md`、`.cursorrules`、`AGENTS.md`）：
```markdown
### 长期记忆和知识图谱指令（Amneshia）
您配备了 **Amneshia**（`amneshia`），一个零外部数据库的 SQLite FTS5 长期记忆中心和知识图谱。
1. **会话开始记忆检索**：
- 在对话或会话开始时，调用 `search_memory` 或 `read_graph` 以回忆用户上下文、活动项目偏好、实体关系和架构决策。
2. **主动事实和偏好持久化**：
- 每当用户共享新偏好、个人详细信息、工作流程选择或项目更新时，主动调用 `add_observations` 或 `create_entities` 以将其永久存储在 Amneshia 中。
3. **冲突解决和巩固**：
- 当用户偏好更改或旧语句更新时，附加修订版通过 `add_observations`，或调用 `consolidate_memory`（“睡眠周期”）以跟踪更新历史并自动替代过时记忆。
```
---
## 许可证
MIT © Sabil Murti (Murtix)
