spherical-memory-mcp
This server provides a spatially-organized, gravity-linked AI memory system that stores, retrieves, and manages memories in a 3D spherical coordinate space with human-like forgetting and associative recall.
Store Memories (
tool_store_memory): Save memory nodes with rich metadata including content, type (coding, creation, discussion, planning, emotion, life, learning), emotional intensity/type, personality relevance, semantic tags (3-8 required), and event associations.Gravity-Based Associative Recall (
tool_recall_by_gravity): Retrieve related memories by spreading activation through gravity links from a natural language query — the core differentiating feature for deep associative search.Coordinate-Based Precise Recall (
tool_recall_by_coordinate): Look up memories using exact filters like memory type, event ID, time range, or keyword, with configurable sorting (by time or quality/mass).Register Events (
tool_register_event): Create named event anchors (e.g., a project, trip, or topic) with optional parent-child hierarchy, serving as organizational axes in the memory space.Manually Link Memories (
tool_link_memories): Explicitly create gravity links between two memory nodes with a specified link type (semantic, emotional, or causal) and optional strength override.View Memory Statistics (
tool_get_memory_stats): Get an overview including total memory count, type distribution, high-mass nodes, recent memories, and decay status.Trigger Memory Decay (
tool_decay_memories): Apply a forgetting mechanism that reduces the quality/mass of memories over time without deleting them, allowing strong links to later reactivate them.Conversation Heartbeat (
tool_conversation_heartbeat): Track conversation turns and signal when memory consolidation (batch store) should occur, based on a configurable interval (default every 3 turns).
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@spherical-memory-mcpstore my idea for a mobile app"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
球状网络标签记忆体系 — MCP Server
一个基于三维球坐标与引力链接的 AI Agent 记忆插件,实现了"球状网络标签记忆体系"论文的核心构想。
任何支持 MCP(Model Context Protocol)的 LLM Agent,接入此插件后即可获得:
空间化记忆存储:每条记忆在闭合球状空间中有唯一的坐标位置
引力联想检索:记忆之间通过语义/情感/因果关联引力自组织为网络
类人遗忘机制:记忆衰减但不删除,可被强关联唤醒
🫀 对话心跳:自动追踪轮次,定时触发记忆固化
快速开始
安装
# 开发安装(推荐)
git clone <this-repo>
cd spherical-memory-mcp
pip install -e .配置到 Agent
WorkBuddy
编辑 ~/.workbuddy/mcp.json:
{
"mcpServers": {
"spherical-memory": {
"command": "/path/to/python",
"args": ["-m", "spherical_memory.server"],
"description": "球状网络标签记忆体系"
}
}
}然后在连接器管理中启用(需要点击 信任)。
Claude Desktop
编辑 Claude Desktop 的 MCP 配置:
{
"mcpServers": {
"spherical-memory": {
"command": "python",
"args": ["-m", "spherical_memory.server"]
}
}
}通用 MCP 客户端
任何支持 MCP stdio 协议的客户端,配置 command + args 同上即可。
Related MCP server: Memsolus MCP Server
工具总览
工具 | 用途 | 调用时机 |
| 存储记忆节点 | 有意义交互后 |
| 引力联想检索 | 用户提及话题时 |
| 坐标精确查询 | 知道时间/类型/事件时 |
| 注册事件锚点 | 新项目/话题出现时 |
| 手动建立引力链接 | 发现深层关联时 |
| 查看记忆概况 | 了解记忆全景 |
| 执行遗忘衰减 | 每 24 小时 |
| 🫀 对话心跳 | 每轮对话结束时 |
🫀 对话心跳机制
每个接入此插件的 Agent 应在每轮对话结束时调用 tool_conversation_heartbeat。
心跳工具自动追踪轮次计数,按配置的间隔(默认每 3 轮)返回 consolidate: true。此时 Agent 应回顾本轮对话的关键信息,批量调用 store_memory 写入球状空间。
对话流程:
第1轮 → heartbeat → consolidate: false
第2轮 → heartbeat → consolidate: false
第3轮 → heartbeat → consolidate: true ← 批量 store_memory
第4轮 → heartbeat → consolidate: false
...可通过环境变量 SM_HEARTBEAT_INTERVAL 调整间隔(默认 3)。
记忆写入原则
该存什么
✅ 用户分享的重要事实、决定、偏好
✅ Agent 做出的关键决策及其理由
✅ 有情感价值的互动
✅ 新知识的习得
✅ 项目进展的里程碑
不该存什么
❌ 日常问候、简单确认
❌ 重复信息
❌ 临时性技术细节
标签是引力链接的生命线
每条 store_memory 必须提供 3–8 个精准的 semantic_tags。标签质量直接决定引力检索效果。
"用户决定辞去大厂工作开始创业" → ["辞职", "创业", "大厂", "职业转型", "勇气"]语义相似度引擎
当前默认使用 Jaccard 标签重叠(零外部依赖,速度快),但存在颗粒度瓶颈——语义相近但文字不同的标签(如"论文"vs"学术写作")Jaccard = 0。
预留了可插拔引擎接口(services/similarity.py),后续接入 bge-small-zh embedding 后,语义相似度将从"精确匹配"升级为"向量余弦",引力链接质量将质的飞跃。
⚠️ EmbeddingSimilarityEngine 当前尚未实现(规划中,欢迎贡献)。目前唯一切换方式是替换为其他
SimilarityEngine的实现类。# 未来切换方式(规划中): # from spherical_memory.services.similarity import set_similarity_engine, EmbeddingSimilarityEngine # set_similarity_engine(EmbeddingSimilarityEngine(model="BAAI/bge-small-zh-v1.5"))
配置项
环境变量 | 默认值 | 说明 |
|
| 数据库路径 |
| 3 | 心跳固化间隔(轮) |
| 0.3 | 引力链接建立阈值 |
| 0.6 | 引力检索激活阈值 |
| 0.95 | 记忆衰减系数 |
| false | 是否启用 embedding 引擎 |
架构
src/spherical_memory/
├── server.py # FastMCP Server 入口,8 个工具注册
├── config.py # 全局配置
├── db/
│ ├── schema.py # 5 张表 + 索引
│ └── connection.py # SQLite 连接管理(WAL 模式)
├── models/
│ ├── memory.py # MemoryNode
│ ├── event.py # Event
│ └── gravity_link.py # GravityLink
└── services/
├── memory_service.py # 记忆 CRUD + 球坐标计算
├── event_service.py # 事件管理
├── gravity_service.py # 引力计算 + 链接建立
├── recall_service.py # 引力扩散 + 坐标检索
├── decay_service.py # 质量衰减 + 唤醒
├── heartbeat_service.py # 🫀 对话心跳
└── similarity.py # 可插拔语义引擎接口核心理念
Agent的记忆体系,不应当是传统的数据库格式。Agent作为强交互载体,其记忆的录入及读取方式应更类人,这样在双方的交互中才能让自然语言有更高效率。
详见配套论文《球状网络标签记忆体系》。
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Latest Blog Posts
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/NeverDrunkMasterQian/spherical-memory-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server