MCP Local Memory

本地内存MCP服务器🧠

面向AI代理的轻量级、隐私优先的“零Docker”内存服务器。此服务器提供语义搜索、关键字搜索和知识图，所有这些都在本地计算机上本地运行。

Antigravity Agent Demo

主要特点

• 混合搜索：语义（矢量）搜索+关键字（FTS5）搜索。
• 本地嵌入：用途 transformers.js （ONNX）运行 all-MiniLM-L6-v2 在您的CPU本地。
• 知识图谱：结构化 entities 和 relations 链接事实的表格。
• 高级图形遍历：递归查询以查找“朋友的朋友”（深度图）。
• 混合聚类：将相关记忆和实体组合在一起的“重心”聚类（#6.1）。
• 机密档案：可配置的“自动摄取”策略，用于自动构建图形。
• 隐私第一：零数据离开您的机器。没有强制性的云API。
• 资源效率的：内存使用量约为50MB至200MB。优化为 Float32Array 缓冲器。
• 增强的NLP提取：通过稳健的模式匹配提取复杂的概念（“优化的WGSL”）、形容词（“语用”）、实体和关系。
• 时光隧道：用于时间回忆的自然语言日期查询（例如“上周”、“2025年”）。
• Todo系统：具有自动上下文注入和内存归档功能的集成任务管理。
• 实体观察：使用“Smart Append”进行标准化存储，以不断发展实体知识。

🌐 跨代理共享上下文

此服务器的一个核心优势是它能够作为 集中式长期内存池 适用于您的所有AI工作流程。

与短暂或锁定到单个会话的标准代理内存不同，此服务器允许多个启用MCP的代理（例如，Claude Code、IDE扩展或自定义CLI）：

• 分享知识：一个代理学到的信息可以立即被另一个代理访问。
• 保持一致性确保你的所有人工智能工具都基于相同的既定事实和实体历史进行操作。
• 持续智能：随着时间的推移，您的互动历史会逐渐成熟，成为整个当地生态系统中可用的强大、结构化的知识库。

______________________________________________________________________

🛠 安装

1.先决条件

• Node.js：v18或更高版本。
• 构建工具：Python和C++构建工具（需要 better-sqlite3 本地编译）。

\[！重要\] windows用户：您可能需要安装C++构建工具。 运行： npm install --global --production windows-build-tools 或者通过Visual Studio安装程序安装“用C++进行桌面开发”。 *如果不这样做，可能会导致 gyp 安装过程中出现错误。*

📦 安装和设置

方法1：通过NPX使用（推荐）

您可以直接使用服务器，而无需全局安装，使用 npx。这是将其与Claude Desktop等MCP客户端一起使用的最简单方法。

添加到MCP配置中：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@beledarian/mcp-local-memory"],
      "env": {
        "ARCHIVIST_STRATEGY": "nlp"
      }
    }
  }
}

方法2：通过NPM安装

全局安装提供 memory 和 mcp-local-memory 命令：

npm install -g @beledarian/mcp-local-memory

# Usage
memory --help

添加到MCP配置中：

{
  "mcpServers": {
    "memory": {
      "command": "mcp-local-memory",
      "env": {
        "ARCHIVIST_STRATEGY": "nlp"
      }
    }
  }
}

### Method 3: Install from Source (For Contributors)

1.  **Clone the repository**:

git clone https://github.com/Beledarian/mcp-local-memory.git cd mcp-local-memory

2.  **Install dependencies**:

npm install

3.  **Build the project**:

npm run build

4.  **Run the server**:

npm start

---

## ⚙️ Configuration

Control the server behavior via environment variables:

| Variable | Options | Default | Description |
| :--- | :--- | :--- | :--- |
| `ARCHIVIST_STRATEGY` | `passive`, `nlp`, `llm` | `nlp` | Control automatic entity extraction behavior. `passive`=disabled, `nlp`=free offline extraction, `llm`=AI-powered extraction (~200 tokens per `remember_fact` call). Can be comma-separated (e.g., `nlp,llm`). |
| `MEMORY_DB_PATH` | Path to DB file | `./memory.db` | Location of the SQLite database. |
| `CONTEXT_WINDOW_LIMIT` | Integer | `500` | Max characters returned by `memory://current-context`. |
| `CONTEXT_MAX_ENTITIES` | Integer | `5` | Max high-importance entities in context. |
| `CONTEXT_MAX_MEMORIES` | Integer | `5` | Max recent memories in context. |
| `OLLAMA_URL` | URL string | `http://localhost:11434` | Full API Endpoint for the LLM strategy (e.g. `http://localhost:11434/api/generate`). |
| `USE_WORKER` | `true`, `false` | `true` | Run Archivist in a background thread to prevent blocking. |
| `ENABLE_CONSOLIDATE_TOOL` | `true`, `false` | `false` | Enable the `consolidate_context` tool for retrospective memory extraction. |
| `TAG_MATCH_BOOST` | Float | `0.15` | Score boost for exact tag matches in `recall` results. Higher = stronger tag priority. |
| `MEMORY_HALF_LIFE_WEEKS` | Float | `4.0` | Weeks until memory importance decays to 50%. Longer = slower decay. |
| `MEMORY_CONSOLIDATION_FACTOR` | Float | `1.0` | Strength of access-based consolidation. Higher = frequently-used memories resist decay more. |
| `MEMORY_SEMANTIC_WEIGHT` | Float | `0.7` | Balance between semantic similarity (0.7) and decayed importance (0.3) in recall ranking. |
| `EXTRACT_COMPLEX_CONCEPTS` | `true`, `false` | `true` | Enable extraction of modifier+noun phrases (e.g., "optimized WGSL"). Set to `false` to disable. |
| `CONTEXT_TODO_LIMIT` | Integer | `3` | Max pending todos shown in `memory://current-context`. |
| `EMBEDDING_CONCURRENCY` | Integer | `5` | Max concurrent embedding operations for `remember_facts`. Higher values = faster batch processing but more CPU/memory usage. |
| `EXTENSIONS_PATH` | Path to directory | (none) | Optional path to load custom tool extensions from external directory. Allows adding private/experimental tools without modifying the codebase. |

To enable AI-powered entity extraction, importance scoring, and auto-labeling, run [Ollama](https://ollama.com/) locally.

{ "mcpServers": { "local-memory": { "command": "wsl", "args": ["/home/username/.nvm/versions/node/v20.11.1/bin/node", "/home/username/mcp-local-memory/dist/index.js"], "env": { "MEMORY_DB_PATH": "/home/username/.memory/memory.db", "ARCHIVIST_STRATEGY": "nlp", "ARCHIVIST_LANGUAGE": "en" // Optional: Default is 'en' } } } }

### 档案员策略(`ARCHIVIST_STRATEGY`)

您可以通过用逗号分隔来组合多种策略（例如。 `nlp,llm`).

- **`passive`**：仅限手动。服务器等待代理调用工具。
- **`nlp`**: **（开源/离线）** 使用 `compromise` 库在本地提取实体。速度很快，但不够全面。
- **`llm`**: **（Ollama/人工智能）** 将文本发送到本地LLM（例如Llama 3）以进行深入理解、关系提取和重要性评分。需要运行Ollama。

______________________________________________________________________

## ⚡ 性能优化

### 异步内存操作

**所有节省内存的操作现在都是非阻塞的** 对于即时响应：

- **`remember_fact`**：立即返回，进程嵌入+后台档案管理员

  - **之前**：~50-200ms阻塞等待
  - **之后**：即时返回（0ms）

- **`remember_facts`**：具有并发限制的并行批处理

  - **之前**：7个事实×200ms=~1.4s（连续）
  - **之后**：~200ms（平行批次）
  - **加速比**：快7倍
  - **配置**：设置 `EMBEDDING_CONCURRENCY` env为（默认值：5）

### 自然记忆进化

频繁访问的记忆会自动变得重要：

- **每 `recall()`**：+0.05重要性提升（上限为1.0）
- **新鲜的回忆**：重要性从0.5开始
- **约10次访问后**：变得“被珍视”（重要性>0.7）
- **约20次访问后**：最大重要性（1.0）

这模仿了 **海马巩固** -经常使用的记忆自然会排在首位。无需手动管理。

### 官方/捆绑扩展

此软件包包括第一方扩展，以增强内存管理：

1. **灵魂维护** (`extensions/soul_maintenance.ts`)：实施“生物”生命周期，记忆必须通过使用获得重要性，并随着时间的推移自然衰减，除非被核心标签免疫。

要使用这些官方/捆绑的扩展，请设置 `EXTENSIONS_PATH` 到 `extensions` 已安装包内的文件夹：

Example for npx usage

EXTENSIONS_PATH=./node_modules/@beledarian/mcp-local-memory/extensions

### 社区扩展

1. **主题数据库扩展** ( | )：添加主题分隔内存数据库，以隔离不同项目或主题的上下文。
   - **安装**：运行 `npx theme-db-extension install` 自动将工具复制到您的 `~/.memory/extensions` 目录。

**设置：**

1. 为您的扩展创建一个目录（例如。， `./my-extensions/`)
1. 使用自定义工具添加Types/JavaScript模块
1. 集 `EXTENSIONS_PATH` 环境变量到您的目录
1. 重新启动服务器

**扩展格式：**

// my-extensions/my_tool.ts import type { Database } from 'better-sqlite3';

export function handleMyTool(db: Database, args?: any) { // Your tool logic here return { result: "Custom tool output" }; }

export const MY_TOOL_TOOL = { name: "my_tool", description: "Description of what your tool does", inputSchema: { type: "object", properties: { // Define input parameters } } };

**优点：**

- 将实验/私有工具与主代码库分开
- 无需重建或修改源代码
- 易于独立版本控制您的扩展
- 非常适合个人定制

______________________________________________________________________

## 💡 推荐系统提示

为了使代理与此内存服务器进行有效的交互，我们建议使用详细的系统提示。

- **快速开始**：参见 [docs/example_instructions.md](docs/example_instructions.md)
- **综合规则**：参见 [docs/detailed_prompt.md](docs/detailed_prompt.md)

______________________________________________________________________

## 🔧 代理工具

服务器公开了以下MCP工具：

### 内存管理

- **`remember_fact(text, tags?)`**：保存一条新信息。 **经常使用**--主动保存用户共享的任何重要内容（偏好、项目、目标、决策、上下文）。
  - **自动实体提取**：使用配置的提取实体和关系 `ARCHIVIST_STRATEGY` (**NLP=免费，LLM=每次调用约200个令牌**)
- **`remember_facts(facts)`**：同时保存多个不同的事实。使用此功能批量保存并减少延迟。
  - **输入**: `{ facts: [{ text: "...", tags?: [...] }] }`
- **`recall(query, limit?)`**：通过Vector或FTS搜索搜索相关的过去条目。
  - **自动跟踪**：更新 `access_count` （+1）和 `last_accessed` （时间戳）用于所有返回的内存
  - **自动跟踪**：更新 `access_count` （+1）和 `last_accessed` （时间戳）用于所有返回的内存
  - **饲料整合**：经常回忆的记忆获得稳定性并抵抗衰退
  - **时光隧道**：按自然语言日期筛选（例如，“上周”、“昨天”、“2025年”）。
- **`list_recent_memories(limit?)`**：查看最新上下文。
- **`forget(memory_id)`**：删除特定条目。
- **`export_memories(path)`**：将所有数据备份到JSON文件。

### 知识图谱

- **`create_entity(name, type, observations?)`**：手动定义实体。 **智能追加**：如果实体存在，则向其添加观察结果。
- **`delete_observation(entity_name, observations)`**：从实体中删除特定的无效事实。
- **`create_relation(source, target, relation)`**：用谓词链接两个实体。
- **`delete_relation(source, target, relation)`**：删除实体之间的特定链接。
- **`delete_entity(name)`**：删除实体 **以及它的所有关系、观察和嵌入** （级联删除）。
- **`update_entity(current_name, new_name?, new_type?)`**：重命名实体或更改其类型。关系会自动更新。
- **`read_graph(center?, depth?)`**探索相互关联的事实网络。
- **`cluster_memories(k?)`**：将知识分组到k个主题中，以获得鸟瞰图。

### 任务管理

#### 全球待办事项（遗留系统）

- **`add_todo(content, due_date?)`**：创建全局任务。待处理的任务会自动显示在 `memory://current-context`.
- **`complete_todo(id)`**：将任务标记为已完成。将其存档为长期记忆（“已完成的任务：…”）。
- **`list_todos(status?, limit?)`**：查看待处理或已完成的任务。

#### 对话与任务管理

- **`init_conversation(name?)`**：初始化对话会话。退货 `conversation_id`. **必须跟进 `read_resource("memory://current-context")`** 获取启动上下文（用户信息、最近的记忆、活动任务）。
- **`add_task(content, section?, conversation_id?)`**：将任务添加到特定对话或全局范围（如果 `conversation_id` 省略）。
- **`update_task_status(id, status)`**：将任务状态更新为 `pending`, `in-progress`，或 `complete`.
- **`list_tasks(conversation_id?, status?)`**：列出任务。使用 `__all__` 显示所有任务或省略以仅显示全局任务。
- **`delete_task(id)`**: **对任务园艺至关重要** -删除过时或已完成的任务，以防止上下文污染。

### 回顾性提取

- **`consolidate_context(text, strategy?, limit?)`** *（通过OPT-IN `ENABLE_CONSOLIDATE_TOOL=true`)*：从简短的对话摘要中提取重要事实（约50-100个标记）。使用NLP或LLM来识别代理可能遗漏的新记忆。返回提取的事实供代理有选择地保存。
  - **启用**：设置 `ENABLE_CONSOLIDATE_TOOL=true` 在MCP服务器环境变量中
  - **`strategy`**: `'nlp'` （快速、离线、默认）或 `'llm'` （彻底，要求Ollama）
  - **代币成本**：约80个令牌（摘要输入）+ **约200个代币（如果策略='llm'）** = **总计约280个代币（LLM）** 或 **约80个令牌（仅限NLP）**
  - **示例**: `consolidate_context(text="Discussed Python for data science, TypeScript frustrations, CEOSim project", strategy="llm")`

> \[！注意\]
> **聊天应用程序开发人员**：合并工具专为手动代理使用而设计。然而，聊天应用程序可以将NLP/LLM逻辑直接集成到客户端中 **自动、零成本上下文解析**。参见 [高级集成](#advanced-integration-possibilities) 在......下面

### 🧠 高性能

#### 项目标记（自动组织）

服务器会自动检测项目名称，如“project Alpha”或“Operation X”，并用它们标记内存。

- **搜索**: `recall("Project Alpha")` 会优先考虑这些记忆。
- **图**：类型的节点 `Project` 是自动创建的。

#### 标签优先级匹配

使用时 `recall`，具有精确标签匹配的记忆会获得分数提升，从而获得更好的排名。

- **默认增强**: `0.15` （可通过以下方式配置 `TAG_MATCH_BOOST`)
- **示例**：查询“性能”将对标记的记忆进行排名 `["performance", "optimization"]` 更高
- **纯语义**：内容嵌入保持干净；标签匹配发生在帖子过滤器中，以提高透明度

#### 记忆衰退与巩固

除非被访问，否则记忆会随着时间的推移而褪色，模仿人类通过某种方式巩固记忆 **要么使用它，要么失去它** 系统。

**工作原理：**

- **自动跟踪**：每次 `recall` 返回内存，更新两个字段：
  - `access_count` → 递增+1
  - `last_accessed` → 设置为当前时间戳
- **稳定性计算公式**: `stability = halfLife * (1 + consolidation * log2(access_count + 1))`
- **衰变计算**: `decayedImportance = importance * pow(0.5, weeks / stability)`

**结果**：经常回忆的记忆变得更多 **稳定的** 并抵抗腐烂。你从未使用过的记忆会逐渐从搜索结果中消失。

**配置：**

- **半衰期**：4周（可通过配置 `MEMORY_HALF_LIFE_WEEKS`)
- **合并系数**：1.0（可通过配置 `MEMORY_CONSOLIDATION_FACTOR`)
- **语义权重**：0.7（可通过配置 `MEMORY_SEMANTIC_WEIGHT`)

**时间线示例：**

Day 1: recall("python") → Memory A: access_count=1, importance=0.8 Day 7: recall("coding") → Memory A: access_count=2, stability↑ Day 30: Memory A maintains relevance due to high access_count Day 90: Unused memories decay to 50% importance (one half-life)

#### 混合主题聚类

将你的知识按主题分组，以了解全局。

- **工具**: `cluster_memories(k=5)`
- **逻辑**：对记忆和实体进行聚类，以找到语义中心（例如“SpaceX”实体+“发射成功”记忆）。

______________________________________________________________________

## 📂 资源

服务器通过MCP资源公开结构化数据：

|URI模式|描述|
| :--- | :--- |
| `memory://current-context` |最近记忆、重要实体、关系和前3个待办事项的标准快照。针对回合启动上下文注入进行了优化。 |
| `memory://turn-context` |动态刷新活动任务、重要实体和最近的内存活动。建议在谈话中进行“意识检查”。 |
| `memory://tasks` |查看所有全局任务（与特定对话无关）。 |
| `memory://tasks-{conversation_id}` |查看特定对话的所有任务，按部分组织。 |
| `memory://todos` |查看所有待处理和最近完成的待办事项。 |

______________________________________________________________________

## 🏗 系统架构

该系统的核心是一个 `memory.db` SQLite文件。

1. **语义层**: `sqlite-vec` 扩展存储384个由以下生成的维度嵌入 `transformers.js`.
1. **文字图层**：SQLite FTS5索引通过数据库触发器保持同步。
1. **图形层**：具有外键约束的关系表，以确保数据完整性。

______________________________________________________________________

## 🧪 测试

运行内部验证测试：

- `npx tsx test_verification.ts` （核心流）
- `npx tsx test_embedding.ts` （AI模型检查）
- `npx tsx test_graph.ts` （图形检查）
- `npx tsx test_archivist_nlp.ts` （自动摄入检查）

______________________________________________________________________

## 🖥 兼容性和故障排除

### Windows ARM64（骁龙/Surface Pro X）

- **限制**：矢量搜索扩展(`sqlite-vec`)目前不提供Windows ARM64的预构建二进制文件。
- **结果**：基于矢量的特征（如 `recall` 语义查询）将不可用。
- **变通方案**：使用以下命令运行此服务器 **WSL2** （见上面的WSL配置示例）。
  - **替代**：如果您更喜欢本机Windows，请使用 **x64 Node.js** （建议使用v20或v22）。
  - **备注**：暂时避免使用Node v24+，因为它缺少预构建的二进制文件 `better-sqlite3`，要求您安装C++构建工具才能从源代码编译。

### 构建工具

- **需求**要求 `better-sqlite3`规格
- **：此项目使用**，它是一个本机C++模块。 **谁需要它们？** ：平台上的用户
- **没有预构建的二进制文件**（例如，Windows ARM64、一些Linux发行版）必须安装Python和C++构建工具才能从源代码编译模块。 `npm install --global --production windows-build-tools` 视窗
- **：通过安装**或Visual Studio构建工具。 `sudo apt-get install build-essential python3`

## Linux

: