Symbolic Memory MCP

符号内存MCP

  

通过MCP（模型上下文协议）为AI系统提供显式、确定性的符号记忆。

SymbolicMemoryMCP提供了一个小型MCP服务器，允许LLM和代理 存储和检索精心策划的“地面真相” 通过稳定 符号 （以及可选的别名），而不是依赖于概率回忆。

存储真理（语义）。必要时计算含义。\ 这个回购是实现这一想法的最小、实用的基础。

______________________________________________________________________

你得到了什么

存储库内容：

• server.py --基于FastAPI的MCP JSON-RPC服务器
• client.py --用于手动保存/获取工作流的CLI客户端
• tests_smoke.py --端到端MCP烟雾测试
• MCP2genericLLM.py --参考LLM电桥（用Ollama测试）
• LICENSE.md --商业来源许可证（BUSL 1.1）

______________________________________________________________________

为什么存在

大多数LLM系统通过以下方式“记住”：

• 聊天历史记录（令牌窗口有限）
• 向量/RAG内存（近似+启发式）
• 提示状态（随时间漂移）

SymbolicMemoryMCP增加了一个补充层：

• 确定性召回 （没有猜测）
• 稳定的引用 （符号不会漂移）
• 精心策划的地面真相 （小、高信号、人类可验证）

推荐模式：矢量内存+符号内存

• 向量存储器：宽泛、模糊的“记忆痕迹”
• 符号内存MCP：小，精心策划 定义/不变量/策略 代理人必须咨询

______________________________________________________________________

与JIT符号存储器设计模式的关系

符号内存MCP是一个 最小实现基板 与 JIT符号存储器 设计模式：

• 上下文≠记忆 （内存是外部可寻址的）
• 实时检索 （仅在需要时提取内存）
• 没有隐藏的快速增长 （无背景积累）
• LLM是一个推理引擎，而不是一个记忆系统

设计模式（概念文档）：

• https://github.com/Th3Hypn0tist/random/blob/main/jit-symbolic-memory-design-pattern

重要许可说明

• 此存储库的许可证为 总线1.1 （参见 LICENSE.md).
• 这 JIT符号内存设计模式 该文档中有自己的许可条款（OPL/commercial）。
• 把这些当作 分开：repo许可证管理此代码；设计模式文档管理该架构描述的使用。

______________________________________________________________________

符号模型

A. 符号 是一个稳定的、人类可读的密钥。

推荐惯例：

• 用点分隔的大写片段： DOMAIN.SUBDOMAIN.NAME
• 为类型使用后缀： .DEF, .RULE, .CFG, .ENUM, .NOTE
• 喜欢一小部分稳定的根（不要长出无休止的根）

示例：

• HGI.DEF --定义
• USER.PREF.LANG --用户偏好
• POLICY.SAFETY.NO_SHELL_EXEC --不变/策略
• PROJECT.SMMCP.ROADMAP.NOTE --项目说明

别名

别名是可选的自然语言友好键，可解析为同一条目。

例子：

• 符号： HGI.DEF
• 别名： ["hgi", "hybrid intelligence"]

______________________________________________________________________

已实现MCP表面（v0.1.0）

保存（写入）

MCP方法：

• tools/call

工具名称：

• sm.texts.save

参数示例：

{
  "symbol": "HGI.DEF",
  "text": "Hybrid General Intelligence = AI + human symbiosis",
  "cat": "ai",
  "subcat": "concepts.intelligence",
  "aliases": ["hgi", "hybrid intelligence"]
}

检索（读取）

MCP方法：

• resources/read

URI：

• resource://sm/v1/texts/

示例：

• resource://sm/v1/texts/HGI.DEF
• resource://sm/v1/texts/hybrid intelligence

建议（尽最大努力）

如果你不存钱 cat/subcat，服务器将尽最大努力返回 suggestions 块。

______________________________________________________________________

安装

推荐使用Python 3.10+。

pip install fastapi uvicorn pydantic requests

______________________________________________________________________

运行服务器

uvicorn server:app --host 127.0.0.1 --port 8000

MCP端点：

http://127.0.0.1:8000/mcp

______________________________________________________________________

冒烟测试

启动服务器，然后：

python tests_smoke.py

预期：

OK: smoke tests passed

烟雾测试验证：

• MCP初始化握手
• sm.texts.save
• resources/read
• 别名解析
• 建议发动机基线

______________________________________________________________________

CLI使用情况（client.py）

保存定义

python client.py save   --symbol HGI.DEF   --text "Hybrid General Intelligence = AI + human symbiosis"   --cat ai   --subcat concepts.intelligence   --aliases hgi "hybrid intelligence"

按符号检索

python client.py get --symbol HGI.DEF

按别名检索

python client.py get --symbol "hybrid intelligence"

______________________________________________________________________

LLM桥梁使用（Ollama示例）

启动服务：

uvicorn server:app --port 8000
ollama serve

跑桥：

python MCP2genericLLM.py   --backend ollama   --model llama3.1:8b   --mcp-url http://127.0.0.1:8000/mcp   --ollama-url http://127.0.0.1:11434/v1/chat/completions   --strict-get   --prompt "You MUST use tools. Save symbol TEST.BRIDGE with text 'bridge ok' in cat test subcat smoke.bridge and aliases ['bridge ok alias']. Then call sm_get using symbol TEST.BRIDGE."

预期：

bridge ok

推理提示模板（实用）

使用此选项强制一致使用工具：

You MUST use the tools.
Before answering, resolve any important term via sm_get (symbol or natural-language alias).
If a required invariant/definition is missing, propose a symbol + aliases and store it via sm_save.
Answer strictly based on retrieved ground truth.

______________________________________________________________________

LLM应该如何在推理中使用它

呼叫 sm_get 当

• 需要一个规范的定义（避免重新发明术语）
• 策略/不变约束操作
• 正确性取决于稳定的配置值

呼叫 sm_save 当

• 用户提供了一个明确的定义/不变量来持久化
• 你有一个精心策划的、稳定的定义，值得重用
• “命名代理”决定一个新的规范符号+别名

避免无声的发明

如果符号不存在：

• 请用户定义它，或
• 明确提出符号+定义并存储（在高风险系统中进行确认）

______________________________________________________________________

存储和一致性

当前的参考实现是SQLite支持的。

范围保证：

• 单进程服务器
• 每次写入的事务安全性（SQLite）

超出范围（目前）：

• 分布式复制
• 跨服务器实例的多编写器协调
• 版本化符号、前缀搜索、批量操作（见路线图）

______________________________________________________________________

建筑

LLM / Agent
  ↓ (tool calls)
MCP2genericLLM (bridge)
  ↓ (MCP JSON-RPC)
SM-MCP Server (FastAPI)
  ↓
SQLite Symbolic Store

这是框架中立的，适合可以进行工具调用的代理堆栈（例如OpenClaw/MoltBot风格的生态系统）。

______________________________________________________________________

路线图（仅文件）

尚未实施：

• 前缀搜索(HGI.*)
• 显式别名管理端点
• 版本控制(HGI.DEF@v2)+“当前”别名固定
• 类型化有效载荷（每个符号的JSON模式）
• 批量操作+导出/导入

核心理念： 小型、确定性核心优先.

______________________________________________________________________

许可证（此存储库）

商业来源许可证1.1（BUSL 1.1）

• 免费供个人、教育和研究使用
• 商业使用需要付费许可
• 转换为 GPL-2.0或更高版本 3年后

看 LICENSE.md 完整条款。

______________________________________________________________________

作者

阿基·希维拉米