AI导哈

持久内存服务器

为单体和多体LLM系统设计的持久内存服务器，支持SQLite存储和混合关键词+语义搜索。

  • by hz1ulqu01gmnZH4
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 hz1ulqu01gmnZH4/universal-memory-mcp

使用说明

通用存储器mcp

用于单代理和多代理LLM系统的持久内存MCP服务器。通过混合关键字+语义搜索，为AI代理提供SQLite支持的长期内存。

特征

  • 内存类型：偶发性（事件/日志）、语义性（事实/知识）、程序性（操作方法/工作流程）
  • 混合搜索：FTS5关键字搜索+嵌入上的余弦相似性，具有可配置的权重
  • 知识图谱：内存之间的有向链接（caused_by、related_to、conflict、supports、follows）与BFS遍历
  • 会话检查点：跨对话保存/还原代理状态
  • 多代理支持：按agent_id、session_id或全局共享范围内存
  • 乐观锁定：具有版本冲突检测的安全并发更新
  • 可插拔嵌入件：HuggingFace变压器（进程内）或llama服务器（外部HTTP）

安装

uv sync

用法

作为MCP服务器运行（stdio传输）：

uv run python server.py

或者通过包装器脚本：

./run.sh

命令行界面

此软件包还安装了 memory CLI：

uv run memory doctor

摄入克劳德/Codex原木

日志摄取器读取本地Claude/Codex JSONL/文本日志，编辑常见日志 秘密，提取持久记忆，并仅存储提取的记忆 带有日志来源元数据。未存储原始日志。

先进行试运行：

uv run memory ingest-logs codex --dry-run --root ~/.codex/sessions --extractor heuristic
uv run memory ingest-logs claude --dry-run --root ~/.claude/projects --extractor heuristic

使用本地 llama-server 用于提取的OpenAI兼容聊天端点：

llama-server --model /path/to/chat-model.gguf --port 8080
uv run memory ingest-logs all --llm-url http://localhost:8080 --llm-model local

默认情况下，CLI不发送 max_tokens 到聊天端点，这避免了 截断思维模型的提取反应。仅设置明确的上限 当你需要一个：

uv run memory ingest-logs codex --llm-max-tokens 4096

还要通过本地嵌入服务器计算嵌入：

llama-server --model embeddinggemma-300m-Q4_0.gguf --port 8787 --embedding --ctx-size 512
MEMORY_ENABLE_EMBEDDINGS=true \
MEMORY_EMBEDDING_BACKEND=llama-server \
MEMORY_EMBEDDING_DIMENSION=768 \
MEMORY_LLAMA_SERVER_URL=http://localhost:8787 \
uv run memory ingest-logs codex --llm-url http://localhost:8080

增量检查点存储在SQLite中，因此以后的运行只消耗新的 事件。投票：

uv run memory watch-logs all --interval 30 --llm-url http://localhost:8080

Claude代码配置

添加到MCP设置(~/.claude/settings.json 或项目 .mcp.json):

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/universal-memory-mcp", "python", "server.py"]
    }
  }
}

配置

通过环境变量（前缀）进行所有设置 MEMORY_):

变量 默认值 描述
MEMORY_DATABASE_PATH ./memory.db SQLite数据库路径
MEMORY_EMBEDDING_BACKEND transformers transformers 或 llama-server
MEMORY_EMBEDDING_MODEL sentence-transformers/all-MiniLM-L6-v2 拥抱脸部模型名称
MEMORY_EMBEDDING_DIMENSION 384 嵌入向量大小
MEMORY_LLAMA_SERVER_URL http://localhost:8787 llama服务器端点
MEMORY_ENABLE_EMBEDDINGS true 设置 false 仅用于关键字搜索
MEMORY_KEYWORD_WEIGHT 0.4 混合搜索关键字权重
MEMORY_SEMANTIC_WEIGHT 0.6 混合搜索语义权重
MEMORY_RECALL_MIN_RELEVANCE 0.25 语义通道召回结果的最小余弦相似度（0=禁用）。关键字匹配始终有效。
MEMORY_RECALL_SNIPPET_CHARS 600 将召回的内容截断为这么多字符（0=禁用）。全文通过精确提取或 full_content=true.

使用llama服务器后端

对于GGUF型号的较低内存使用率：

llama-server --model embeddinggemma-300m-Q4_0.gguf --port 8787 --embedding --ctx-size 512
MEMORY_EMBEDDING_BACKEND=llama-server MEMORY_EMBEDDING_DIMENSION=768 uv run python server.py

MCP工具

表面故意很小——五个工具，按调用频率分层：

工具 说明
recall_memories 一个检索工具，三个选择器： query （混合/关键字/语义搜索）， memory_id （精确获取，完整内容），或 entity （回忆提到 src/foo.py、标识符等）。 expand_links=N 为每个结果附加图邻居。除非满足以下条件，否则长内容将作为片段返回 full_content=true.
store_memory 存储具有类型、代理/会话范围、重要性的内存；optional links 在同一调用中为现有内存创建图形边
update_memory 使用乐观锁定进行更新(expected_version)
manage_session action: create | checkpoint | restore --跨对话保存/恢复代理状态
memory_admin action: stats | dream_status | run_dream_jobs | extract_entities | check_contradictions | link | delete --统计、后台作业维护、手动图形链接和删除（在一个工具后面进行破坏性操作，用于每个工具的权限分配）

错误被引发为MCP工具错误(isError: true)，从未作为数据返回。

0.2.0中的突破性变化

get_memory, delete_memory, link_memories, get_linked_memories, create_session, checkpoint_session, restore_session, get_stats, extract_entities, get_entity_neighbors, check_contradictions, dream_status，以及 run_dream_jobs 被折叠成上面的五个工具。 recall_memories 现在回来了 {mode, count, memories} 默认情况下，截断长内容，并应用语义相关性截断，而不是直接列表(MEMORY_RECALL_MIN_RELEVANCE).

测试

uv run pytest

许可证

WTFPL

相关 MCP