# agentmemory-middleware

**Repository Path**: dev_cpg/agentmemory-middleware

## Basic Information

- **Project Name**: agentmemory-middleware
- **Description**: Agent智能体长期记忆项目
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-17
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AgentMemory Middleware (AMM)

> **v3.0.2** | 任何 AI Agent 通过 [MCP](https://modelcontextprotocol.io/) 即可读写 **5 端融合** 长期记忆 | 启动 < 1s | 跨会话零遗忘

AMM 是 **AI Agent 长期记忆中间件**,提供 5 端持久化 + 智能融合检索 + 标准 MCP 接入。让任何兼容 opencode / Claude / Cursor 等的 AI Agent 通过 5 个 MCP 工具直接读写分布式记忆,无需理解底层存储。

## 核心能力

### 🎯 5 端持久化融合记忆
- **Hindsight** (云,语义层): TEMPR 四路并行检索 + Observation 自动聚合 + Disposition 配置
- **MongoDB** (本地,结构化层): agent 隔离 + 索引缓存 + WAL 事务
- **Obsidian** (本地,文档层): vault 路径分层 + 项目/技能/决策归档
- **ReMe** (本地,程序记忆): personal / procedural / tool 三种结构化记忆
- **mem0** (云,第 5 端): LLM 自动提取 fact,专长用户偏好类

### 🔌 一键 MCP 接入
- 5 个标准 MCP tools: `amm_remember` / `amm_recall` / `amm_reflect` / `amm_health` / `amm_archive_learning`
- opencode.json 一行配置,无需写代码
- 兼容任何 MCP 协议客户端 (Claude Desktop / Cursor / Continue.dev)

### ⚡ 高性能 + 低开销
- 启动 < 1s (FastAPI 框架优化后)
- recall P50 ~700ms (5 端并行查询 + RRF 融合)
- 内存 < 100MB
- 共享 httpx.Client 池 + ThreadPool max_workers=8

### 🛡️ 企业级可靠性
- **WAL 预日志事务**: 写入原子性,失败可回滚
- **Sliding window Circuit Breaker**: 云限流自动熔断 (5s 窗口,80% 失败率)
- **AsyncExitStack + retry**: 单 store 失败不阻塞其他 store
- **Per-namespace async 锁**: 同 agent 串行,跨 agent 并行

## 架构

```mermaid
graph TB
    Client[opencode Agent / MCP Client]

    subgraph "MCP Layer"
        AMM_MCP[amm_mcp<br/>stdio transport]
        MEM0_MCP[mem0-mcp<br/>官方]
    end

    subgraph "AMM Core :8899 (FastAPI + LazyFastAPI)"
        Router[FastAPI Router]
        Classifier[QueryClassifier<br/>9 种类型]
        Fusion[FusionService<br/>RRF 5 源]
        TC[TransactionCoordinator<br/>WAL]
    end

    subgraph "5 Stores"
        Hindsight[Hindsight Cloud<br/>api.hindsight.vectorize.io]
        MongoDB[Local MongoDB<br/>:27017/agentmemory]
        Obsidian[Local Vault<br/>~/AI_Agent/shared-knowledge]
        ReMe[ReMe SDK<br/>personal/procedural/tool]
        Mem0[mem0 Cloud<br/>api.mem0.ai]
    end

    Client -->|"tools/call"| AMM_MCP
    Client -->|"tools/call"| MEM0_MCP
    AMM_MCP -->|"HTTP JSON"| Router
    Router --> Classifier
    Router --> TC
    Classifier --> Fusion
    TC --> Hindsight
    TC --> MongoDB
    TC --> Obsidian
    TC --> ReMe
    TC --> Mem0
```

## 快速开始

### 方式 A: opencode 一键接入 (推荐)

```bash
# 1. 启动 AMM (云模式,无需本地 LLM)
cd /Users/mac/OpenShareProject/agentmemory-middleware
nohup /opt/anaconda3/bin/python3 -m uvicorn src.app:app \
  --host 127.0.0.1 --port 8899 > /tmp/amm.log 2>&1 </dev/null & disown

# 2. 在 ~/.config/opencode/opencode.json 添加 mcp 段:
{
  "mcp": {
    "amm": {
      "type": "local",
      "command": ["/opt/anaconda3/bin/python3", "-m", "amm_mcp.server"],
      "environment": {
        "AMM_BASE_URL": "http://127.0.0.1:8899",
        "PYTHONPATH": "/Users/mac/OpenShareProject/agentmemory-middleware"
      },
      "enabled": true
    }
  }
}

# 3. 重启 opencode, 5 个 amm_* tools 自动可用
```

### 方式 B: 全栈本地模式 (需要 llama.cpp)

```bash
cd /Users/mac/OpenShareProject/agentmemory-middleware

# 一键启动 llama.cpp + Hindsight + AMM
./start_all.sh start

# 或云模式 (跳过本地 LLM)
CLOUD_HINDSIGHT=1 ./start_all.sh start
```

### 验证

```bash
# 健康检查
curl http://127.0.0.1:8899/health | python3 -m json.tool

# 写入记忆
curl -X POST http://127.0.0.1:8899/api/v1/memory/remember \
  -H "Content-Type: application/json" -H "X-Agent-ID: opencode" \
  -d '{"content":"AMM v3.0.2 启动成功","metadata":{"type":"project_state","title":"test"}}'

# 检索记忆
curl -X POST http://127.0.0.1:8899/api/v1/memory/recall \
  -H "Content-Type: application/json" -H "X-Agent-ID: opencode" \
  -d '{"query":"AMM 启动","limit":5,"mode":"deep"}'
```

## API 端点

| 端点 | 方法 | 说明 | MCP tool |
|------|------|------|----------|
| `/api/v1/memory/remember` | POST | 写入记忆 (5 端 WAL) | `amm_remember` |
| `/api/v1/memory/recall` | POST | 检索 + RRF 融合 | `amm_recall` |
| `/api/v1/memory/reflect` | POST | Hindsight agentic 推理 | `amm_reflect` |
| `/api/v1/phase5/archive/task` | POST | 任务归档 | `amm_archive_learning` |
| `/api/v1/phase5/archive/decision` | POST | 决策归档 | `amm_archive_learning` |
| `/api/v1/phase5/archive/learning` | POST | 学习归档 | `amm_archive_learning` |
| `/health` | GET | 5 端探活 | `amm_health` |

**MCP 工具** (5 个,通过 stdio 暴露):`amm_remember` / `amm_recall` / `amm_reflect` / `amm_health` / `amm_archive_learning`

## 配置 (.env)

```ini
# Hindsight (云)
HINDSIGHT_API_BASE_URL=https://api.hindsight.vectorize.io
HINDSIGHT_API_KEY=hsk_xxx
HINDSIGHT_API_BANK_ID=opencode

# mem0 (云, 第 5 端)
MEM0_API_KEY=m0-xxx
MEM0_BASE_URL=https://api.mem0.ai

# MongoDB (本地)
MONGODB_HOST=192.168.1.5
MONGODB_PORT=27017
MONGODB_DATABASE=agentmemory
MONGODB_USERNAME=openclaw
MONGODB_PASSWORD=xxx

# Obsidian (本地 vault)
OBSIDIAN_VAULT_PATH=/Users/mac/AI_Agent/shared-knowledge

# ReMe (本地, vendored SDK)
REME_ENABLED=true
REME_MONGODB_VECTOR_MODE=local
```

完整配置: `src/config.py` (9 个嵌套 BaseSettings)

## 版本演进

| 版本 | 日期 | 核心特性 | 状态 |
|------|------|----------|------|
| **v3.0.2** | 2026-06-01 | LazyFastAPI 框架优化 + BaseAsyncStore + sliding window backpressure | **当前** |
| v3.0.1 | 2026-06-01 | 路线图 6 项完成 (lazy import / BaseHttpService / retry / etc) | 稳定 |
| v3.0.0 | 2026-06-01 | mem0 第 5 存储 + AMM-as-MCP | 稳定 |
| v2.0.2 | 2026-06-01 | 云 Hindsight 集成 (Bearer auth + bank_id 修复) | 稳定 |
| v2.0.0-2.0.1 | 2026-05-23 | ReMe 集成 + 6 项 P0 风险修复 | 历史 |
| v1.3.x | 2026-05-18 | Phase 5 自适应学习 + WAL 事务 | 历史 |

详细变更: [Obsidian 实施记录](https://gitee.com/dev_cpg/agentmemory-middleware/wiki) / `benchmarks/REPORT_v3.0.2.md`

## 性能 (v3.0.2 实测)

| 指标 | v3.0.1 | **v3.0.2** | 目标 |
|------|--------|--------|------|
| 启动 (uvicorn → listen) | 4.8s | **655ms** | < 2s ✅ |
| recall P50 | 858ms | **1049ms** | < 500ms ⚠️ |
| 内存常驻 | 94MB | **94MB** | < 100MB ✅ |
| 5 端 recall 命中率 | - | **100%** | - ✅ |

详细: `benchmarks/REPORT_v3.0.2.md`

## 项目结构

```
agentmemory-middleware/
├── src/
│   ├── app.py                          # FastAPI 入口 (LazyFastAPI)
│   ├── config.py                       # 9 个嵌套 BaseSettings
│   ├── routers/
│   │   ├── admin.py                    # /health, /version
│   │   ├── memory.py                   # /remember, /recall, /reflect
│   │   └── phase5.py                   # /archive/{task|decision|learning}
│   ├── services/
│   │   ├── base.py                     # BaseHttpService + retry + sliding window CB
│   │   ├── base_async_store.py         # v3.0.2 本地 store 基类
│   │   ├── hindsight_service.py        # Hindsight API 封装 (云 Bearer)
│   │   ├── mongodb_service.py          # MongoDB (继承 BaseAsyncStore)
│   │   ├── obsidian_service.py         # Obsidian 文件 IO
│   │   ├── ollama_service.py           # Ollama embeddings/rerank
│   │   ├── mem0_service.py             # v3.0.0 第 5 端 (Token auth)
│   │   ├── fusion_service.py            # RRF 5 源融合
│   │   ├── query_classifier.py          # 9 种 QueryType
│   │   ├── wal_service.py               # 预日志事务
│   │   ├── transaction_service.py       # 事务协调器
│   │   ├── context_recovery_service.py  # Phase 5 会话恢复
│   │   ├── memory_archiver.py           # Phase 5 长期归档
│   │   └── reme/                       # ReMe 集成层 (6 P0 修复)
│   ├── fastapi_extensions/             # v3.0.2 FastAPI 二次开发
│   │   ├── lazy_fastapi.py              # LazyFastAPI 类
│   │   ├── lru_cache.py                 # 路由解析缓存
│   │   └── simplified_exceptions.py     # 简化的异常处理器
│   ├── amm_mcp/                        # v3.0.0 MCP server
│   │   ├── server.py                    # FastMCP 实例
│   │   ├── tools.py                     # 5 tools 定义
│   │   ├── client.py                    # httpx async client
│   │   └── README.md                    # MCP 使用文档
│   ├── middleware/
│   │   ├── auth.py                     # Agent 身份验证
│   │   └── namespace.py                # 命名空间管理
│   ├── models/
│   │   ├── requests.py                 # Pydantic 请求模型
│   │   └── responses.py                # Pydantic 响应模型
│   └── utils/
│       ├── hashing.py                  # SHA256 工具
│       └── tags.py                     # Tag 解析
├── amm_mcp/                            # MCP server package (顶层)
├── benchmarks/
│   ├── REPORT_v3.0.0.md
│   ├── REPORT_v3.0.1.md
│   └── REPORT_v3.0.2.md
├── docs/
│   ├── ReMe-AMM-集成落地方案-定稿.md
│   ├── ReMe-AMM-实施与联调记录-2026-06-01.md
│   └── FastAPI-源码深度分析-2026-06-01.md
├── tests/
├── .env.example
├── pyproject.toml
├── start.sh
├── start_all.sh
└── start_llamacpp.sh
```

## 路线图

### v3.0.3 (下一版)
- FastAPI 框架 import 进一步优化 (考虑 starlette-only)
- NamespaceManager 多 agent 池重新设计 (元类 + 弱引用)
- Obsidian 集成 BaseAsyncStore
- cached_get_dependant 实际接入 (15 路由 × 6ms 节省)

## 贡献

1. Fork 仓库
2. 创建 `feature/<name>` 分支
3. 提交代码 + 单元测试
4. 提交 Pull Request

**编码规范**: 严格遵循 [AGENTS.md](docs/AGENTS.md) (pydantic-settings 9 个嵌套 + Type hints + docstrings on public APIs)

## 协议

MIT License

## 仓库信息

- **Gitee**: https://gitee.com/dev_cpg/agentmemory-middleware
- **Wiki**: https://gitee.com/dev_cpg/agentmemory-middleware/wikis
- **版本**: v3.0.2 (commit `809c16a`)
- **作者**: cpg