使用说明（Markdown 格式）

项目简介
- 该仓库实现了一个本地化的 MCP 服务端，核心职责是向 LLM 客户端以标准化的方式提供上下文信息和功能接口。服务器基于 SQLite 数据库持久化内存资源，并通过注册的工具（如 memory_get_context、memory_search、memory_upsert、memory_capture、memory_health 等）暴露数据访问、操作和状态查询能力。同时集成了向量嵌入能力（通过 Ollama 进行语义检索）及纯文本检索，支持会话、项目和全局三种作用域。
- MCP 服务器通过 JSON-RPC 形式与客户端通信，并使用多种实现方式的传输（示例实现为标准输入输出的 Stdio 传输，便于在本地脚本和测试环境中运行）。
主要功能点
- 资源管理与检索：在 SQLite 中持久化 Memory 条目，支持全文检索、语义检索、按范围过滤（全局/项目/会话）等。
- 工具注册与执行：提供 memory_upsert、memory_search、memory_get_context、memory_capture、memory_health、memory_delete、memory_forget_scope 等工具，客户端可通过 JSON-RPC 调用执行。
- Embeddings 与检索模式：默认支持词嵌入（若可用），在 Ollama 可用时实现语义+ lexical 的混合排序，无法使用时回退到 lexical-only。
- Canonical 与优先级：支持 canonical key 的推断、更新与时间线，提供基于 canonical 的获取上下文与时间线查看。
- 会话与作用域管理：支持 global、project、session 三种作用域，且 project/ session 的标识可以通过路径哈希等方式进行脱敏管理。
- 安全与合规：对敏感信息进行红线处理，且支持对嵌入及文本输出进行字节/字符数限制，确保输出在未超限时尽量完整。
- 本地化部署友好：默认使用本地数据目录与内置启动参数，便于在本地开发、测试和微服务场景中快速上手。
安装与运行步骤
- 安装依赖并构建代码：
  - 安装依赖后执行构建命令，生成可执行的 dist/index.js。
- 启动 MCP 服务器：
  - 使用命令行启动后，服务器将监听并通过 Stdio 传输与客户端通信（可外部接入更多传输实现）。
- 运行测试与体验：
  - 仓库内包含单元测试与集成测试用例，可在开发阶段执行确保核心功能正常。
服务器配置（给 MCP 客户端的配置示例，JSON 形式说明，不包含具体代码）
- server 名称：agent-memory-mcp
- 启动命令（command）：node
- 命令参数（args）：指向 dist/index.js 的路径
- 环境变量（env）示例说明（客户端配置中可设置的常用变量）：
  - AGENT_MEMORY_HOME：内存数据存储根目录，例如 /用户/某处/.agent-memory
  - AGENT_MEMORY_DB_PATH：数据库文件路径，例如 /路径/ memory.db
  - AGENT_MEMORY_OLLAMA_URL：嵌入服务端 URL，若启用 Ollama 时使用
  - AGENT_MEMORY_EMBED_MODEL：嵌入模型名称
  - AGENT_MEMORY_DISABLE_EMBEDDINGS：是否禁用嵌入（1 表示禁用）
- 配置示例要点（非代码）：
  - 客户端在本地需要为 MCP 服务器提供启动命令和参数的配置信息，以便通过 MCP 建立初始连接和会话。具体的 JSON 配置应包含服务器名称、启动命令、参数及环境变量等字段，便于客户端在不同环境下复用同一 MCP 服务。
基本使用方法
- 连接与调用
  - 在本地使用 MCP 客户端，指向配置中描述的启动命令与参数，建立与服务器的 JSON-RPC 通道后即可调用注册的工具（memory_search、memory_get_context、memory_upsert 等）。
- 常用工作流
  - 通过 memory_upsert 写入记忆，然后使用 memory_search/ memory_get_context 进行上下文聚合，再通过 memory_health 监控健康状态。
- 部署与扩展
  - 可以将同一 SQLite 数据库作为多客户端共享的本地存储，确保通过 canonical/作用域控制来实现跨进程协作与一致性。
备注
- 该实现包含完整的服务端代码、内存数据库、工具注册、以及集成测试，属于可直接用于生产或本地开发的 MCP 服务器实现。

Agent Memory MCP 服务器

服务器信息