Skip to main content
Glama
M4F-S

Mnemosyne

by M4F-S

Mnemosyne 🧠

CI PyPI version Python 3.9+ MCP License: Apache-2.0

面向生产环境、本地优先的自主 AI 智能体分层记忆引擎。

Mnemosyne 为 AI 智能体(Hermes、OpenClaw、OpenManus、Claude Desktop、Cursor、Windsurf、CrewAI、LangChain)提供永久性的、结构化的长期记忆。它连接了人类可读的 Obsidian Markdown Vault 与高速 PostgreSQL + pgvector (HNSW) 或零配置 SQLite,支持混合倒数排名融合(RRF)搜索、wikilink 知识图谱、艾宾浩斯时间衰减、跨智能体舰队共享,以及异步 Google Drive 云同步。


📑 目录


Related MCP server: Synapto

⚡ 完整功能矩阵

功能

描述

优势

🤖 MCP 原生(v2024-11-05)

标准化的 stdio JSON-RPC 协议服务器

无缝集成 Claude、Cursor、Windsurf、Hermes、OpenClaw

🔎 高召回率 HNSW 向量搜索

pgvector HNSW 索引,使用 vector_cosine_opsm=16, ef_construction=64

无需聚类重训练即可实现亚毫秒级向量召回

⚖️ 混合 RRF 检索

稠密嵌入(1.0)+ GIN FTS(0.8)+ 图谱(0.6)+ 显著性(0.2)的倒数排名融合

同时捕获精确技术关键词(CVE、代码令牌)与模糊语义

🏛️ Wing 与 Room 作用域

2 级分类体系(wing = 领域/项目,room = 频道/主题)

消除上下文窗口膨胀与跨领域幻觉

🌐 跨智能体共享记忆

可跨多智能体舰队查询的中央 shared_db,带凭据筛查

集体舰队智能,同时不损害私有数据库

☁️ 异步 Google Drive 同步

本地优先的双向同步引擎,带 MD5 差异比对与 .conflict.md 分支解决

本地亚毫秒级智能体 I/O + 自动云备份与团队共享

⏳ 艾宾浩斯时间衰减

指数衰减 $Salience_t = Salience_0 \times (0.95)^{\Delta t}$,90 天自动归档

自动修剪瞬时噪声,同时保持活跃记忆清晰

📌 置顶记忆免疫

通过 pinned=True#pinned 标签获得永久免疫衰减

确保基础指令和核心规则永不褪色

📖 Obsidian Zettelkasten

写入带 YAML frontmatter 与 [[Wiki Links]] 的人类可读 Markdown 笔记

可在 Obsidian 中直接可视化检查、编辑和图谱展示

📜 感知轮次的摄取器

1,500 字符滑动窗口分块,沿轮次边界带 200 字符重叠

保留完整对话历史,不破坏代码块

🛡️ 提示注入防护

中和控制令牌(`<

im_start

>[INST]`);转义 XML 上下文标签

防止记忆投毒与上下文劫持攻击

⚡ FastEmbed ONNX 支持

超轻量 ONNX 运行时嵌入引擎(约 30MB 内存)

相比重型 PyTorch sentence-transformers 内存减少 90%

🔄 零配置 SQLite 回退

PostgreSQL 离线时自动回退到本地 SQLite

独立开发者工作站 100% 功能对等


🏗️ 系统架构

                                ┌──────────────────────────────────────────────┐
                                │          AI Agents & LLM Frameworks          │
                                │  Hermes • OpenClaw • Claude • Cursor • Manus │
                                └──────────────────────┬───────────────────────┘
                                                       │ JSON-RPC (stdio) / Python SDK
                                                       ▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                           Mnemosyne Core (v3.4.0)                                           │
│                                                                                                             │
│  ┌─────────────────────────┐  ┌─────────────────────────┐  ┌─────────────────────────────────────────────┐  │
│  │ Admission & Security    │  │ Multi-Backend Embedder  │  │ Turn-Aware Session Ingestor                 │  │
│  │ - Secret Regex Guard    │  │ - FastEmbed (ONNX 30MB) │  │ - Turn boundary splitting                   │  │
│  │ - Injection Neutralizer │  │ - Remote Microservice   │  │ - 1500-char linear sliding window           │  │
│  │ - Path Traversal Guard  │  │ - SentenceTransformers  │  │ - Sequential [[Wiki Link]] chaining         │  │
│  └─────────────────────────┘  └─────────────────────────┘  └─────────────────────────────────────────────┘  │
│                                                                                                             │
│  ┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐  │
│  │                                 Hybrid RRF Retrieval & Graph Ranker                                   │  │
│  │            RRF Score = 1.0 * Dense(HNSW) + 0.8 * Keyword(FTS) + 0.6 * Graph + 0.2 * Salience          │  │
│  └───────────────────────────────────────────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────┬───────────────────────────────────────┬─────────────────────────────┘
                                        │                                       │
                ┌───────────────────────┴───────────────────────┐               │
                ▼                                               ▼               ▼
 ┌─────────────────────────────┐                 ┌─────────────────────────────────────────────┐
 │    PostgreSQL + pgvector    │                 │       Obsidian Markdown Vault (Local)       │
 │ - HNSW vector_cosine_ops    │                 │ - Human-Readable Markdown + YAML Frontmatter │
 │ - GIN tsvector English FTS  │                 │ - [[Wikilink]] Knowledge Graph Visualizer   │
 │ - Self-Healing DB Pool      │                 │ - Atomic Writes with EXDEV Fallback         │
 │ - Private DB + shared_db    │                 └──────────────────────┬──────────────────────┘
 └─────────────────────────────┘                                        │ Async Background Sync
                                                                        ▼
                                                 ┌─────────────────────────────────────────────┐
                                                 │              Google Drive Cloud             │
                                                 │ - Service Account / OAuth2 Authentication    │
                                                 │ - MD5 Checksum Verification                 │
                                                 │ - Sibling .conflict-TIMESTAMP.md Resolution │
                                                 └─────────────────────────────────────────────┘

🧠 核心能力深度解析

1. 分层 Wing 与 Room 分类体系

记忆交叉污染是多智能体舰队中的主要故障模式。Mnemosyne 将记忆结构化为 2 级记忆宫殿:

  • wing(领域/项目): 顶级领域边界(例如 ecommercepentestdevopsshared)。

  • room(主题/频道): 细粒度主题分区(例如 databasefirewallstripe_api)。

查询可以严格限定在特定 wing 或 room 内,防止营销提示词召回渗透测试发现。

2. 混合倒数排名融合(RRF)搜索

标准向量搜索在精确技术字符串(例如 CVE-2024-380770x7fff5fbff8c0)上会失败,而关键词搜索在语义概念上会失败。Mnemosyne 执行多候选检索,并使用加权 RRF 合并结果:

$$\text{RRF Score}(d) = \sum_{m \in \text{modes}} w_m \cdot \frac{1}{k + \text{rank}_m(d)} + 0.2 \cdot \text{Salience}(d)$$

  • 稠密 HNSW 向量搜索: 权重 $1.0$(384 维嵌入上的余弦距离)。

  • PostgreSQL 全文搜索: 权重 $0.8$(tsvector,标题权重为 A,内容权重为 B)。

  • 递归图谱遍历: 权重 $0.6$(递归 CTE 发现 1 跳和 2 跳 [[Wiki Links]])。

  • 记忆显著性引擎: 权重 $0.2$(重要性分数从 $0.0$ 到 $1.0$)。

3. 跨智能体共享记忆层(shared_db

在自主多智能体环境中,智能体维护隔离的私有数据库(toy_dbold_dbcandy_db 等)以防止状态损坏。然而,集体智能需要共享全局策略和经过验证的事实。

  • 发布: 使用 memory_publish_shared,经过审查的笔记被发布到 shared_db

  • 凭据筛查: 内容会针对严格的 regex 过滤器进行扫描,以检测 Anthropic 密钥(sk-ant-)、Google Gemini 密钥(AIza...)、HuggingFace 令牌(hf_...)、OpenAI 密钥(sk-proj-...)、AWS 访问密钥(AKIA...)、Slack 令牌(xox-)和私钥。

  • 软失败召回: 当智能体查询记忆时,memory_recall 同时查询私有存储和 shared_db。如果共享数据库暂时不可达,它会优雅降级,不会中断智能体。

4. 艾宾浩斯时间衰减与置顶免疫

记忆会随时间自然失去相关性。Mnemosyne 实现了赫尔曼·艾宾浩斯的指数遗忘曲线:

$$\text{Salience}(t) = \text{Salience}0 \times (0.95)^{\Delta t{\text{days}}}$$

  • 触达反馈: 访问记忆会更新 last_accessed_at,重置其衰减。

  • 夜间自动归档: 整合过程自动将 $\text{Salience} < 0.05$ 且超过 $>90\text{ 天}$ 未访问的笔记转换为 status = 'archived'

  • 置顶免疫: 系统规则、核心策略或标记为 pinned=True 或带有 #pinned 标签的笔记获得对时间衰减的永久免疫($\text{Salience} = 1.0$)。

5. Obsidian Markdown Vault 与双向图谱

智能体创建的每条记忆都会同时作为人类可读的 .md 文件写入你的 Obsidian vault 中:

  • Zettelkasten Frontmatter: 包含 titledatetagstypesaliencewingroom

  • 知识图谱:[[目标笔记]] 形式提及的目标笔记会被自动解析为 PostgreSQL 中的双向边。

  • 实时检查: 在桌面或移动设备上打开 Obsidian,在 Obsidian 的交互式图谱视图中探索你的智能体舰队的集体记忆。

6. 感知轮次的逐字会话摄取器

对话记录通常包含在有损摘要中丢失的关键细微差别。memory_ingest_session

  • 沿轮次边界(User:Assistant:### Turn**Human**:)拆分原始记录。

  • 对于超过 1,500 字符的轮次,应用线性滑动窗口(1,500 字符,200 字符重叠)。

  • 使用 [[Session ... Turn 01 Part 02]] wikilink 链接连续分块,保留代码块、执行轨迹和对话流程。

7. 异步 Google Drive 云同步

让你的智能体 vault 在多台机器或移动设备上安全备份和同步:

  • 本地优先速度: 代理工具调用以本地 SSD 速度(<1ms)执行,不会因 Google Drive 网络延迟而阻塞。

  • 后台守护进程 / Cron 同步: 扫描 vault 文件,计算 MD5 校验和,并与 Google Drive 双向同步增量。

  • 冲突解决: 如果文件同时在 Google Drive 和本地代理 vault 中被修改,Mnemosyne 会将传入版本保存为 NoteName.conflict-YYYYMMDD-HHMMSS.md,防止数据丢失。

  • 身份验证: 支持 Google Cloud 服务账号 JSON(GOOGLE_APPLICATION_CREDENTIALSGDRIVE_SERVICE_ACCOUNT_JSON)和 OAuth2 用户令牌(GDRIVE_TOKEN_JSON)。

8. 灵活的嵌入后端(FastEmbed / 微服务 / 本地)

Mnemosyne 可适应任何部署资源预算:

  1. FastEmbed ONNX Runtime(推荐用于独立节点): 使用 ONNX Runtime C++ 执行(约 30MB 内存)。零 PyTorch 开销。

  2. 集中式微服务(mnemosyne.embed_service): 在单个专用容器中托管 sentence-transformers,通过 HTTP(MEMORY_EMBED_URL)为多个代理容器提供服务。

  3. 本地 SentenceTransformers: 独立 PyTorch 执行(all-MiniLM-L6-v2,384 维)。

  4. 确定性哈希回退: 为零资源受限环境提供零内存数学向量哈希。

9. 纵深防御安全与注入防护

  • 路径遍历免疫: 双重解析的规范路径检查(is_relative_to)确保文件操作无法逃逸 vault 根目录。

  • 原子同级写入: 文件写入同级临时文件(.note.pid.tmp)并原子重命名,对 EXDEV 跨设备卷挂载自动回退。

  • 控制令牌中和: 中和散文中的 LLM 注入令牌(<|im_start|><|system|>[INST]<<SYS>>),同时逐字保留代码块。

  • 结构化 XML 上下文封装: 召回的记忆被包裹在 <recalled_memory_context id="..." title="..." source="..."> 标签中,并进行内部标签转义,确保宿主 LLM 永远不会将召回的记忆与活动系统指令混淆。


🛠️ MCP 工具参考(8 个工具)

全部 8 个工具通过标准 MCP JSON-RPC stdio 原生暴露给代理:

1. memory_remember

在 vault 中存储带语义嵌入、标签和分层作用域的私有记忆笔记。

{
  "title": "PostgreSQL HNSW Tuning",
  "content": "For datasets >10,000 vectors, use HNSW with m=16 and ef_construction=64 for optimal recall.",
  "tags": ["database", "pgvector", "performance"],
  "wing": "engineering",
  "room": "databases",
  "salience": 0.8,
  "pinned": true
}

2. memory_publish_shared

将经过净化和审核的发现或策略发布到跨代理共享舰队记忆(shared_db)。

{
  "title": "Fleet Security Policy: SSL Verification",
  "content": "All internal agent HTTP requests must enforce SSL certificate validation.",
  "tags": ["security", "policy"],
  "wing": "shared",
  "room": "general"
}

3. memory_recall

使用混合 RRF、HNSW 向量、关键词或图在私有和共享舰队数据库中搜索记忆。

{
  "query": "HNSW index configuration parameters",
  "mode": "hybrid",
  "top_k": 5,
  "scope": {
    "wing": "engineering",
    "room": "databases"
  },
  "include_shared": true
}

4. memory_ingest_session

按轮次边界逐字摄取并分块完整的对话记录。

{
  "transcript": "User: How do we configure pgvector?\nAssistant: Use CREATE EXTENSION vector; then create an HNSW index.",
  "wing": "engineering",
  "room": "sessions"
}

5. memory_timeline

按时间顺序检查最近的记忆操作(remember、recall、remind、consolidate)。

{
  "limit": 20
}

6. memory_history

在更新前查看特定记忆笔记的版本历史和过往编辑快照。

{
  "title": "PostgreSQL HNSW Tuning",
  "limit": 5
}

7. memory_remind_me

安排未来的前瞻性提醒或周期性任务。

{
  "title": "Rotate Database Credentials",
  "content": "Verify that all 5 agent connection pools are refreshed with new passwords.",
  "trigger_at": "2026-09-01T00:00:00Z",
  "recurring": "monthly"
}

8. memory_audit

获取实时记忆健康指标、存储后端状态、请求计数和活动翼区。

{}

🌐 多代理舰队生产架构

在多代理生产环境中(例如 5 代理 Hermes 舰队),Mnemosyne 在内部 Docker 网络上隔离代理数据库,同时提供共享智能:

                                  ┌─────────────────────────────────────────┐
                                  │      Production VPS (${VPS_HOST})      │
                                  └────────────────────┬────────────────────┘
                                                       │
         ┌───────────────────┬──────────────────┼───────────────────┬──────────────────┐
         ▼                   ▼                  ▼                   ▼                  ▼
┌──────────────────┐┌──────────────────┐┌──────────────────┐┌──────────────────┐┌──────────────────┐
│   hermes-agent   ││ hermes-assistant ││ hermes-marketing ││  hermes-pentest  ││  hermes-trader   │
│      (Toy)       ││      (Old)       ││     (Candy)      ││     (Pencil)     ││      (Coin)      │
│   Database:      ││   Database:      ││   Database:      ││   Database:      ││   Database:      │
│     toy_db       ││     old_db       ││     candy_db     ││     pencil_db    ││     trader_db    │
└────────┬─────────┘└────────┬─────────┘└────────┬─────────┘└────────┬─────────┘└────────┬─────────┘
         │                   │                  │                   │                  │
         └───────────────────┴──────────────────┼───────────────────┴──────────────────┘
                                                │
                                                ▼
                               ┌───────────────────────────────────┐
                               │   PostgreSQL + pgvector (HNSW)    │
                               │   - Private DBs: toy_db, old_db.. │
                               │   - Shared DB:   shared_db        │
                               └───────────────────────────────────┘

🚀 快速开始与安装

1. 安装

# Standard installation
pip install mnemosyne-memory

# With Google Drive Cloud Synchronization support
pip install "mnemosyne-memory[gdrive]"

# With lightweight FastEmbed ONNX support (~30MB RAM)
pip install "mnemosyne-memory[fastembed]"

# Full installation (All extras + Dev dependencies)
pip install "mnemosyne-memory[dev,gdrive,fastembed,embed-service]"

2. 使用 Docker Compose 运行

启动 PostgreSQL + pgvector 容器:

docker compose up -d

3. 启动 MCP 服务器

# Standalone with local SQLite (Zero configuration)
python -m mnemosyne server

# With PostgreSQL + pgvector
MEMORY_DB_DSN="postgresql://mnemosyne:***@localhost:5432/my_agent_db" python -m mnemosyne server

🤖 代理框架集成配方

1. Claude Desktop(claude_desktop_config.json

{
  "mcpServers": {
    "mnemosyne": {
      "command": "python3",
      "args": ["-m", "mnemosyne", "server"],
      "env": {
        "MEMORY_VAULT_PATH": "/Users/username/Documents/Obsidian/AgentVault",
        "MEMORY_DEFAULT_WING": "claude"
      }
    }
  }
}

2. Cursor IDE(.cursor/mcp.json

{
  "mcpServers": {
    "mnemosyne": {
      "command": "python3",
      "args": ["-m", "mnemosyne", "server"],
      "env": {
        "MEMORY_VAULT_PATH": "./.vault",
        "MEMORY_DEFAULT_WING": "codebase"
      }
    }
  }
}

3. Hermes Agent(~/.hermes/config.yaml

mcp_servers:
  obsidian_memory:
    command: python3
    args: ["-m", "mnemosyne", "server"]
    env:
      MEMORY_DB_DSN: "postgresql://mnemosyne:***@${DB_HOST}:5432/toy_db"
      MEMORY_SHARED_DSN: "postgresql://mnemosyne:***@${DB_HOST}:5432/shared_db"
      MEMORY_VAULT_PATH: "/opt/data/vault"

4. OpenClaw(openclaw-config.yaml

plugins:
  mcp_servers:
    mnemosyne:
      command: "python3"
      args: ["-m", "mnemosyne", "server"]
      env:
        MEMORY_VAULT_PATH: "~/.openclaw/vault"
        MEMORY_DEFAULT_WING: "openclaw"

5. Python SDK 与自主代理脚本

from mnemosyne import UnifiedMemorySystem

mem = UnifiedMemorySystem(
    vault_path="~/.agent/vault",
    dsn="postgresql://mnemosyne:***@localhost:5432/agent_db",
    shared_dsn="postgresql://mnemosyne:***@localhost:5432/shared_db"
)

# Remember fact
mem.remember(
    title="Kubernetes Cluster Policy",
    content="Deployments in staging must specify resource memory limits.",
    wing="infrastructure",
    room="k8s",
    tags=["kubernetes", "policy"],
    pinned=True
)

# Hybrid recall
results = mem.recall(
    query="staging memory limits",
    mode="hybrid",
    scope={"wing": "infrastructure"}
)

for r in results:
    print(r["title"], "->", r["formatted_context"])

💻 完整 CLI 命令参考

Mnemosyne 包含功能完备的管理 CLI:

# 1. Store a memory note
python -m mnemosyne remember "API Architecture" "Uses Bearer JWT auth." --tags security auth --wing backend --room api --salience 0.8 --pinned

# 2. Publish shared fleet memory
python -m mnemosyne publish-shared "Global Production Policy" "Always check SSL certs." --wing devops

# 3. Search memories
python -m mnemosyne recall "JWT authentication" --mode hybrid --top-k 5 --wing backend

# 4. View activity timeline
python -m mnemosyne timeline --limit 20

# 5. Trigger Ebbinghaus decay & link reconciliation
python -m mnemosyne consolidate --decay-rate 0.95 --archive-threshold 0.05

# 6. Check system statistics & health
python -m mnemosyne stats

# 7. Synchronize with Google Drive (One-off pass)
python -m mnemosyne sync-gdrive --folder "My-Agent-Vault" --credentials service-account.json

# 8. Run Google Drive Sync as a background daemon
python -m mnemosyne sync-gdrive --daemon --interval 60

# 9. Run standalone Centralized Embedding Microservice
python -m mnemosyne embed-service --host 0.0.0.0 --port 8000 --model all-MiniLM-L6-v2

⚙️ 环境变量参考

变量

默认值

描述

MEMORY_VAULT_PATH

~/.mnemosyne/vault

本地 Obsidian Markdown vault 目录的文件系统路径

MEMORY_DB_DSN

(无)

PostgreSQL DSN(例如 postgresql://user:pass@host:5432/db)。如果未设置,则使用 SQLite

MEMORY_SHARED_DSN

(无)

可选跨代理共享舰队数据库的 PostgreSQL DSN

MEMORY_AGENT_NAME

local-agent

多代理舰队部署中源代理的标识符

MEMORY_EMBED_URL

(无)

远程集中式嵌入微服务的 URL(例如 http://localhost:8000

MEMORY_REQUIRE_POSTGRES

false

设置为 true 时,如果 PostgreSQL 失败则抛出错误而不是回退到 SQLite

GOOGLE_APPLICATION_CREDENTIALS

(无)

用于 Google Drive 同步的 Google Cloud 服务账号 JSON 文件路径

GDRIVE_SERVICE_ACCOUNT_JSON

(无)

Google Cloud 服务账号凭据的字符串化 JSON 内容

GDRIVE_TOKEN_JSON

(无)

已授权 Google OAuth2 用户令牌的字符串化 JSON 内容

TOKENIZERS_PARALLELISM

false

禁用 HuggingFace 分词器分支以保持 stdio JSON-RPC 流完整性

HF_HUB_DISABLE_PROGRESS_BARS

1

禁用 stdio 中的进度条以保持 MCP 流纯净

HF_HUB_OFFLINE

0

设置为 1 可使用本地缓存 100% 离线运行 SentenceTransformers

TRANSFORMERS_OFFLINE

0

设置为 1 可防止 transformers 发出外部 HuggingFace 网络请求


🧪 测试与基准

Mnemosyne 维护全面的测试套件(单元测试、安全注入测试、SQLite 测试和实时 PostgreSQL pgvector 集成测试):

# Run all unit tests
pytest tests/ -v -m "not integration"

# Run full test suite including live PostgreSQL + pgvector tests
MEMORY_DB_DSN="postgresql://mnemosyne:***@localhost:5432/test_db" pytest tests/ -v

📄 许可证

Apache-2.0 许可证。为开放自主代理生态系统而构建。完整详情请参阅 LICENSE

A
license - permissive license
A
quality
A
maintenance

Maintenance

Maintainers
Response time
1wRelease cycle
2Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Gives AI agents persistent memory with semantic search, automatic extraction, and memory decay, accessible via MCP protocol.
    12
    MIT
  • A
    license
    Not graded
    quality
    A
    maintenance
    Provides persistent, searchable memory for MCP-compatible agents, enabling recall by meaning, automatic decay, trust scoring, and cross-agent handoffs.
    5
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    Provides persistent memory with semantic search for MCP-based AI agents, enabling them to store and recall information across sessions using vector embeddings.
    4
    1
    MIT

View all related MCP servers

Related MCP Connectors

  • Shared, governed long-term memory for AI agents across tools and sessions via MCP and REST.

  • Your memory, everywhere AI goes. Build knowledge once, access it via MCP anywhere.

  • Shared long-term memory vault for AI agents with 20 MCP tools.

View all MCP Connectors

Latest Blog Posts

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/M4F-S/gomaa'

If you have feedback or need assistance with the MCP directory API, please join our Discord server