tomtan/memory-gateway
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ba84b1ddb32442a5782a4554277a5ec038c9323a
memory-gateway/README.md
tomtan ba84b1ddb3 update memory gateway
2026-04-30 16:09:28 +08:00

6.5 KiB
Raw Blame History

Memory Gateway

Memory Gateway 是一个通用记忆网关，用于给 AI agent / harness 提供统一的记忆检索、文档上传、LLM 总结和知识沉淀能力。

它的定位不是某个单一业务场景的垂直应用，而是一个可复用的本地 memory/context gateway：上层 agent 通过 REST、MCP 或 Hermes skill 调用它，底层由 OpenViking 承载 memory/resource，由 Obsidian 承载人工可维护的 Markdown 知识。

当前能力

  • 搜索 OpenViking memory / resource。
  • 写入普通 memory。
  • 写入结构化 resource。
  • 对任意文本调用 LLM 总结，并按需沉淀到 OpenViking。
  • 上传文档，使用 MarkItDown 转 Markdown。
  • 将上传文档保存到 Obsidian vault。
  • 将文档摘要和结构化 artifact 写入 OpenViking knowledge。
  • 给 Hermes 提供通用 memory-gateway skill。

架构

Agent / Harness / CLI
  -> Memory Gateway REST / MCP
  -> OpenViking memory / resource
  -> Obsidian markdown vault
  -> OpenAI-compatible LLM summary

目录结构

memory-gateway/
├── memory_gateway/                 # Gateway 服务代码
│   ├── server.py                    # REST / MCP 接口
│   ├── openviking_client.py         # OpenViking client
│   ├── llm.py                       # OpenAI-compatible LLM summary
│   ├── document_ingest.py           # MarkItDown + Obsidian write helpers
│   ├── config.py
│   └── types.py
├── integrations/hermes/
│   └── memory-gateway/              # 通用 Hermes skill
├── obsidian-vault/
│   ├── 01_Knowledge/Uploaded/       # 上传文档转成的 Markdown
│   └── 05_Templates/                # 通用知识模板
├── tests/
├── config.example.yaml
└── pyproject.toml

环境

使用当前虚拟环境：

cd /home/tom/memory-gateway
source /home/tom/OpenViking/.venv/bin/activate

本地配置文件：

/home/tom/memory-gateway/config.yaml

关键配置：

memory:
  default_namespace: memory-gateway

llm:
  base_url: https://oai.bwgdi.com/v1
  api_key: <local secret, git ignored>
  model: MiniMaxAI

obsidian:
  vault_path: /home/tom/memory-gateway/obsidian-vault
  knowledge_dir: 01_Knowledge/Uploaded

config.yaml 已被 .gitignore 忽略，不会提交密钥。

启动

OpenViking 需要先运行在 127.0.0.1:1933。

source /home/tom/OpenViking/.venv/bin/activate
openviking-server --host 127.0.0.1 --port 1933

启动 Memory Gateway：

cd /home/tom/memory-gateway
source /home/tom/OpenViking/.venv/bin/activate
python -m memory_gateway.server --config /home/tom/memory-gateway/config.yaml

健康检查：

curl http://127.0.0.1:1934/health

REST 接口

GET /health

检查 Gateway 和 OpenViking 状态。

POST /api/search

搜索 OpenViking memory / resource。

curl -X POST http://127.0.0.1:1934/api/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "memory gateway document upload summary",
    "uri": "viking://resources",
    "limit": 5
  }'

POST /api/memory

写入普通 memory。

curl -X POST http://127.0.0.1:1934/api/memory \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "memory-gateway",
    "memory_type": "preference",
    "content": "The user prefers concise technical summaries."
  }'

POST /api/resource

写入结构化 resource。

curl -X POST http://127.0.0.1:1934/api/resource \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "viking://resources/memory-gateway/knowledge/example.json",
    "resource_type": "json",
    "content": "{\"title\":\"example\"}"
  }'

POST /api/summary

调用 LLM 总结任意文本，并按需沉淀到 OpenViking。

curl -X POST http://127.0.0.1:1934/api/summary \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Project decision summary",
    "content": "需要总结和沉淀的内容...",
    "namespace": "memory-gateway",
    "memory_type": "decision",
    "tags": ["project", "decision"],
    "persist_as": "resource"
  }'

persist_as 支持：none、memory、resource、both。

POST /api/knowledge/upload

上传文档，MarkItDown 转 Markdown，保存到 Obsidian，LLM 总结后写入 OpenViking knowledge。

curl -X POST http://127.0.0.1:1934/api/knowledge/upload \
  -F "file=@/path/to/document.pdf" \
  -F "title=Design Notes" \
  -F "namespace=memory-gateway" \
  -F "knowledge_type=design_doc" \
  -F "tags=project,design,reference" \
  -F "persist_as=resource"

默认保存到：

obsidian-vault/01_Knowledge/Uploaded/

MCP Tools

POST /mcp/rpc 支持：

  • search
  • add_memory
  • add_resource
  • commit_summary
  • get_status
  • list_memories
  • list_resources

Hermes Skill

通用 Hermes skill：

/home/tom/.hermes/skills/memory-gateway/

仓库副本：

integrations/hermes/memory-gateway/

主要脚本：

scripts/retrieve_memory.py
scripts/commit_summary.py
scripts/upload_knowledge.py
scripts/search_obsidian.py

检索记忆：

python /home/tom/.hermes/skills/memory-gateway/scripts/retrieve_memory.py \
  --query "document upload summary memory gateway" \
  --uri viking://resources \
  --limit 5

总结沉淀：

python /home/tom/.hermes/skills/memory-gateway/scripts/commit_summary.py \
  --title "Reusable conclusion" \
  --namespace memory-gateway \
  --memory-type decision \
  --tag project \
  --persist-as resource \
  --text "最终结论或可复用知识..."

上传知识：

python /home/tom/.hermes/skills/memory-gateway/scripts/upload_knowledge.py \
  --file /path/to/document.md \
  --title "Knowledge note" \
  --namespace memory-gateway \
  --knowledge-type reference \
  --tags project,reference \
  --persist-as resource

测试

cd /home/tom/memory-gateway
source /home/tom/OpenViking/.venv/bin/activate
PYTHONPATH=/home/tom/memory-gateway pytest -q

当前测试覆盖：

  • API key 校验。
  • MCP tools/list。
  • OpenViking search 透传。
  • LLM summary artifact 构建。
  • document upload -> markdown -> Obsidian -> OpenViking resource。

下一步

  • 在 Gateway 层加强 /api/search 的 URI prefix 过滤和去重。
  • 给 /api/knowledge/upload 增加文件大小限制、类型白名单和 dry-run。
  • 增加 Obsidian -> OpenViking 增量同步脚本。
  • 给 Memory Gateway skill 增加更稳定的“回答时引用 memory/resource/Obsidian note”输出约束。
  • 增加更多文档解析格式和异常处理测试。