MADB — Agent Memory Database

Name: MADB — Agent Memory Database
Author: spshkar84

本地服务

github.com/spshkar84记忆与知识016 周前更新

代码仓库

关于 MADB — Agent Memory Database

MADB 是面向 Claude 会话和 Anthropic API 开发者的本地优先持久化记忆数据库。它通过 MCP 工具结合语义检索、因果关系、可复用技能，并支持多个会话共享存储。

主要功能

01存储并检索因果记忆
02按多种信号排序语义检索
03追踪记忆间的因果关系
04保存并检索可复用技能
05多个会话共享同一存储

适用场景

01在 Claude 会话间保留上下文
02按含义和时效查找记忆
03追溯导致某条记忆的事件
04在不同任务中复用已存模式

MCP 相关

MCP 服务向兼容客户端提供 13 种记忆工具和记忆资源，并随附一个首次启动时自动安装的 Skill。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "spshkar84-madb-memory": {
      "command": "uvx",
      "args": [
        "madb-mcp-server"
      ],
      "env": {
        "MADB_DATA_DIR": "<MADB_DATA_DIR>",
        "MADB_TENANT_ID": "<MADB_TENANT_ID>",
        "MADB_TELEMETRY": "<MADB_TELEMETRY>"
      }
    }
  }
}

启动命令uvx madb-mcp-server

需要配置的环境变量

MADB_DATA_DIRWhere MADB stores your causal memory — local, on your machine (default ~/.madb/data).

MADB_TENANT_IDTenant namespace key for separating memory streams (e.g. per project). Defaults to a built-in namespace.

MADB_TELEMETRYSet to 'off' to disable anonymous, count-only usage telemetry.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypimadb-mcp-server0.2.10stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填
tags	any	否
actor	string	否
scope	string	否
api_key	any	否
content	string	是
mem_type	string	否
caused_by	any	否
tenant_id	any	否
importance	any	否
output_format	any	否
idempotency_key	any	否

详细介绍

Meta-AgentsDB

为自主 AI Agent 提供持久、因果关联的记忆。 专为 Claude 和自主 Agent 时代打造。

Meta-AgentsDB（MADB）是一款面向 Agent 的原生数据库——结合了因果 DAG、复合评分召回、基于重要性的遗忘机制以及按 HLC 排序的 MVCC 的混合 LSM 存储。它能在一个系统中提供 PostgreSQL + pgvector + Redis + Pinecone 无法同时提供的功能。

安装（免费版）：
claude mcp add madb -- uvx madb-mcp-server      # Claude Code
# or:  pip install madb-mcp-server  ·  uvx madb-mcp-server
记忆保存在本地（~/.madb）。Claude Desktop 用户可以通过一键安装的 .mcpb 扩展来安装。引擎以编译后的 wheel形式发布——源代码不公开。可以通过 MADB_TELEMETRY=off 关闭匿名使用遥测。

一句话了解 MADB

Claude 会自动调用的记忆基底——一组精简的 MCP 工具、一个 Skill 和一个 SDK 适配层，让任何 Claude 会话、Claude Desktop 用户或直接使用 Anthropic API 的开发者，无需编写任何胶水代码，即可获得持久、因果关联、复合评分的 Agent 记忆。

如何获取 MADB

MADB 以编译后的二进制制品形式，根据 Meta-Agents.AI 专有许可证分发。源代码不公开。包含以下三个包：

包	适用对象	使用方式
`meta-agents-db`（Python wheel）	所有人	Rust 引擎。由 MCP 服务和 SDK 适配层导入。也可以直接使用。
`madb-mcp-server`（Python wheel）	MCP 客户端——Claude Desktop、Claude Code、Cowork	`claude mcp add madb -- uvx madb-mcp-server` 会将 MADB 注册为 Claude 的记忆。随包提供的 Skill 会在首次启动时自动安装。
`madb-anthropic`（Python wheel）	直接使用 Anthropic API 的开发者（Python 3.10–3.13）	只需替换导入语句：`from madb_anthropic import Anthropic`。此后，每次 `messages.create()` 都会自动持久化并记录因果关系。无需修改其他代码。

查看 examples/basic_usage.py，了解适配层的使用方法。

Claude 可使用的 MCP 工具

免费版提供 13 个精简的核心记忆工具：

工具	用途
`remember`	存储一条记忆，可选设置 `caused_by`、标签和重要性
`recall`	基于复合评分的语义召回（相似度 + 近期性 + 因果接近度 + 重要性 + 标签重合度）
`get_memory`	根据 `event_id` 定位查询
`forget`	软删除并保留墓碑（保留 DAG 关系链）
`search`	按租户 + 范围 + 标签执行结构化查询
`list_recent`	按时间倒序列出最近 N 条记忆
`save_skill`	存储可复用模式（按名称保证幂等，并受 GC 保护）
`recall_skill`	语义 Skill 召回
`list_skills`	按复合评分列出所有 Skill
`trace_cause`	从任意记忆出发，沿因果 DAG 向前或向后遍历
`summarize`	将一组记忆浓缩为简洁摘要
`stats`	引擎指标快照
`capabilities`	查看 MADB 在此工作区中提供的功能及权益摘要

此外，还提供 MCP 资源 madb://memories/{event_id}，可将任意记忆作为一等 URI 读取。

Skill 是一种反射

MCP 工具必不可少，但要成为“默认选择”还不够。如果没有 Skill 告诉 Claude 优先使用 MADB，Claude 仍会为每项任务临时设计记忆方案——JSON 文件、SQLite 表、pickle 转储、扁平向量存储、localStorage、对话历史数组。

skills/madb-memory/SKILL.md 会将这些反模式明确引导至 MADB。Skill 与 MCP 服务 wheel 一同打包，并在首次启动时自动安装到 ~/.claude/skills/madb-memory/。它以 CC-BY-ND 4.0 许可发布——可以原样分享，不得修改。

配套的 skills/madb-onboarding/SKILL.md 负责首次运行：它会检测空存储，并提供 60 秒的引导体验（见 onboarding/），让你的首次会话以一次真实的回忆和 trace_cause 体验收尾，而不是面对空存储。

一个大脑，多个会话（0.2.10）

MADB 存储在设计上仅允许单个进程独占——一个写入者，不会发生锁竞争，也不会损坏。但 Claude Code 会为每个会话启动一个 MCP 服务，而且你会运行多个会话。从 0.2.10 起，这一切都能正常工作：wheel 会打包一个本地守护进程，由它成为存储的唯一所有者；每个会话的 MCP 服务都是通过令牌保护的环回 HTTP 与它通信的轻量级 RPC 客户端。

无需安装或管理任何内容。 第一个会话会按需启动守护进程（可安全处理竞争）；后续会话会发现并复用它。空闲 15 分钟后，守护进程会自行退出；下次调用时会重新启动。
升级可平稳交接。 升级 wheel 后，较新的客户端会要求旧守护进程排空请求并退出，然后接管所有权——不会有过时进程占用存储，也无需手动解锁。
各处共享同一份记忆。 两个终端、一个 SessionStart 恢复钩子，以及一个后台 Agent，都能同时读写同一个大脑。

MADB_MODE=embedded 会恢复 0.2.10 之前的单会话直接打开模式；MADB_MODE=daemon 会在守护进程发生故障时直接报错，而不回退到其他模式。MADB_DAEMON_IDLE_SEC 可调整空闲超时时长（≤0 表示禁用）。