Live Memory

🧠 活记忆——MCP知识活记忆服务

协作AI代理的共享工作内存

 ](https://ghcr.io/cloud-temple/live-memory) ](<>)   

🇫🇷 法文版

______________________________________________________________________

📋 目录

• 概念
• 建筑
• 先决条件
• 安装
• 配置
• 入门指南
• MCP工具
• 图形桥
• 网络界面
• MCP集成
• CLI和Shell
• 测试
• 安全
• 项目结构
• 故障排除

______________________________________________________________________

🎯 概念

实时记忆 是一个MCP（模型上下文协议）服务器，提供 存储库即服务 对于AI代理。多个代理通过共享共同的工作记忆在同一项目上进行协作。

graph-memory  = LONG-TERM memory (documents → Knowledge Graph → Vector RAG)
live-memory   = WORKING memory (live notes → LLM → Structured Memory Bank)

两种互补模式

为什么要活记忆？

🧠 多智能体协作和两级存储架构

基于LLM的多智能体系统研究进展(Tran等人，2025年-- *多智能体协作机制：LLMs综述*)识别 共享内存 作为一个基本组成部分。在他们的正式框架中，多智能体系统由下式定义： 代理 （A） A 共享环境 （E） ，以及 协作渠道 C作者强调，LLM本质上是孤立的算法，不是为了协作而设计的——它们需要一个 共享内存基础结构 协调他们的行动。

实时内存+图形内存直接实现了这种架构：

┌─────────────────────────────────────────────────────────────┐
│                  Shared Environment E                       │
│                                                             │
│  ┌──────────────────┐   LLM   ┌──────────────────────┐      │
│  │   Live           │ ──────► │   Bank               │      │
│  │  Real-time notes │ consolid│  Structured working  │      │
│  │  (append-only)   │  -ates  │  memory              │      │
│  └──────────────────┘         └──────────┬───────────┘      │
│                                          │                  │
│                                     graph_push              │
│                                     (MCP Streamable HTTP)   │
│                                          │                  │
│                               ┌──────────▼───────────┐      │
│                               │  🌐 Graph Memory     │      │
│                               │  Knowledge Graph     │      │
│                               │  (entities, relations│      │
│                               │   embeddings, RAG)   │      │
│                               └──────────────────────┘      │
└─────────────────────────────────────────────────────────────┘

图形桥 (graph_push)是这两个层次之间的协作渠道。跟随 后期合作 文献中描述的模式（将合并输出作为另一个系统的输入共享），它将工作文档（Markdown）转换为结构化知识（实体/关系图）。

为什么是两个层次？ 一个级别是不够的：

• 仅凭工作记忆 短暂的 --项目结束后，它就会消失
• 知识图谱本身就是 太重 用于快速记下每日笔记
• 两者之间的桥梁使特工能够 快速工作 （实时笔记） 资本化 知识（图表）

具体来说，代理人可以：

1. 快速写作 无摩擦（实时记忆，仅追加，~50ms）
2. 自动合并 通过LLM转化为结构化文档（银行，约15秒）
3. 坚持知识 在可搜索的图形中（图形内存，约2分钟）
4. 查询图表 用自然语言从过去的项目中检索信息

______________________________________________________________________

🏗️ 建筑

     Agent Cline        Agent Claude        Agent X
          │                   │                │
          └────────┬──────────┘                │
                   │                           │
                   ▼  MCP Protocol (Streamable HTTP)  ▼
          ┌────────────────────────────────────────┐
          │   Caddy WAF (Coraza CRS)               │
          │   Rate Limiting • TLS • OWASP CRS      │
          └────────────┬───────────────────────────┘
                       │
          ┌────────────┴───────────────────┐
          │   Live Memory MCP (:8002)      │
          │   40 tools • Auth Bearer       │
          │   LLM Consolidation            │
          └──────┬──────────┬──────┬───────┘
                 │          │      │
          ┌──────┴──┐  ┌────┴───┐  │
          │   S3    │  │ LLMaaS │  │  MCP Streamable HTTP
          │Dell ECS │  │ CT API │  │  (optional)
          └─────────┘  └────────┘  │
                       ┌───────────┴────────────┐
                       │   Graph Memory         │
                       │   (long-term memory)   │
                       │   Neo4j + Qdrant       │
                       └────────────────────────┘

最小堆栈：S3+LLM。没有本地数据库。 可选的：连接到图形存储器以实现长期记忆（知识图）。

______________________________________________________________________

📦 先决条件

• 码头工人 >= 24.0 + Docker Compose V-2型
• Python 3.11+ （对于CLI，可选）
• A兼容 S3存储 （云神庙戴尔ECS、AWS、MinIO）
• 与OpenAI API兼容 LLM （云神庙LLMaaS、OpenAI等）

______________________________________________________________________

🚀 安装

1.克隆存储库

git clone https://github.com/Cloud-Temple/live-memory.git
cd live-memory

2.配置环境

cp .env.example .env

编辑 .env 与你的价值观（参见 配置).

3a。Docker启动（推荐）

# Build images (WAF + MCP server)
docker compose build

# Start services
docker compose up -d

# Check status
docker compose ps

# Health check
curl -s http://localhost:8080/health

3b。本地启动（开发）

# Install dependencies
uv pip install -e .

# Run server
python -m live_mem

4.安装CLI（可选）

uv pip install -e .

5.验证安装

# Health check via CLI
python scripts/mcp_cli.py health

# Or full E2E test (creates space, writes notes, consolidates)
python scripts/test_recette.py

暴露端口

______________________________________________________________________

⚙️ 配置

编辑 .env所有变量都记录在 .env.example.

强制变量

可选变量--LLM

合并器使用LLM（OpenAI-compatible API）将实时票据转换为结构化银行文件。

可选变量——固结和压实

______________________________________________________________________

▶️ 入门指南

docker compose up -d
docker compose ps       # Check status
docker compose logs -f live-mem-service --tail 50  # Logs

______________________________________________________________________

🔧 MCP工具

通过MCP协议（Streamable HTTP）公开的40个工具，分为7类。

系统（3个工具）

空间（9个工具）

Live（3工具）

银行（7种工具）

图表（4个工具）——🌉 图形内存链接

备份（5个工具）

管理员（7个工具）

______________________________________________________________________

🌉 图形桥——连接到图形内存

Live Memory可以将其内存库推入 图形存储器 例如长期记忆。知识图从银行文件中提取实体、关系和嵌入。

工作流程

1. graph_connect(space_id, url, token, memory_id, ontology="general")
   └─ Tests connection, creates Graph Memory if needed

2. bank_consolidate(space_id)
   └─ LLM produces/updates bank files

3. graph_push(space_id)
   ├─ Lists documents in Graph Memory
   ├─ For each modified bank file:
   │   ├─ document_delete (removes orphaned entities)
   │   └─ memory_ingest (complete graph recalculation)
   ├─ Cleans deleted bank documents
   └─ Updates metrics (last_push, push_count)

4. graph_status(space_id)
   └─ Stats: 79 entities, 61 relations, top entities, documents...

智能推送（删除+重新摄取）

每一次推都是 完全刷新 该文件的图形。现有文件会被删除，然后重新摄入，因此Graph Memory会使用最新内容重新计算实体、关系和嵌入。

可用本体论

______________________________________________________________________

🖥️ 网络界面

Live Memory揭示了一个 网络界面 上 /live 实时可视化存储空间。

访问

http://localhost:8080/live

特性

布局

┌──────────────┬────────────────────────────┐
│  📊 Dashboard│  🔴 Live Timeline          │
│  (info,      │  (auto-refresh, date group)│
│   agents,    ├────────────────────────────┤
│   rules...)  │  📘 Bank (Markdown tabs)   │
└──────────────┴────────────────────────────┘

智能自动刷新

• 可配置：3s/5s/10s/30s/手动
• 抗闪烁：仅在数据发生更改时重新呈现DOM
• 带有上次刷新时间戳的脉冲绿点
• 空间选择→ 立即加载（无需按钮）

REST API（5个端点）

/api/* 端点需要承载令牌。 /live 页面和 /static/* 文件是公开的。

______________________________________________________________________

🔌 MCP集成

📖 完整指南：参见 GUIDE_INGRATION_CLINE.md 获取分步指南（临床配置、自定义说明、工作流程、多代理、故障排除）。

使用Cline（VS代码/VSodium）

在Cline的MCP设置中(cline_mcp_settings.json):

{
  "mcpServers": {
    "live-memory": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer lm_YOUR_TOKEN"
      }
    }
  }
}

要配置 自定义指令 为您的代理人复制 clinerules.md 将文件保存到您的Cline全局自定义说明中（或保存到 .clinerules/ 项目中的目录）。你只需要改变 两个值:

• 这 MCP服务器名称 （如中所配置 cline_mcp_settings.json例如。 my-live-mem)
• 这 您的存储空间名称 （ID传递给 space_create例如。 my-project)

代理名称为 自动检测 从身份验证令牌中提取，无需配置其他内容。

💡 即用型模板： clinerules.md --复制并自定义2个粗体值 📖 详细指南： Cline集成和定制说明指南

使用克劳德桌面

在 claude_desktop_config.json:

{
  "mcpServers": {
    "live-memory": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer lm_YOUR_TOKEN"
      }
    }
  }
}

通过Python（MCP客户端）

from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

async def example():
    headers = {"Authorization": "Bearer your_token"}
    async with streamablehttp_client("http://localhost:8080/mcp", headers=headers) as (r, w, _):
        async with ClientSession(r, w) as session:
            await session.initialize()

            # Load all context
            result = await session.call_tool("bank_read_all", {
                "space_id": "my-project"
            })

            # Write a note
            await session.call_tool("live_note", {
                "space_id": "my-project",
                "category": "observation",
                "content": "Build passing in CI"
            })

______________________________________________________________________

💻 CLI和Shell

CLI安装

pip install click rich prompt-toolkit mcp[cli]>=1.8.0
export MCP_URL=http://localhost:8080
export MCP_TOKEN=your_token

CLI命令（单击）

python scripts/mcp_cli.py health
python scripts/mcp_cli.py whoami                       # Current token identity
python scripts/mcp_cli.py about
python scripts/mcp_cli.py space list
python scripts/mcp_cli.py space create my-project --rules-file rules.md
python scripts/mcp_cli.py live note my-project observation "Build OK"
python scripts/mcp_cli.py bank consolidate my-project
python scripts/mcp_cli.py bank read-all my-project
python scripts/mcp_cli.py token create agent-cline read,write
python scripts/mcp_cli.py graph connect my-project URL TOKEN MEM-ID -o general
python scripts/mcp_cli.py graph push my-project
python scripts/mcp_cli.py graph status my-project
python scripts/mcp_cli.py graph disconnect my-project

交互式 Shell

python scripts/mcp_cli.py shell

自动补全、历史记录、丰富显示。看 scripts/README.md 供充分参考。

______________________________________________________________________

🧪 测试

统一测试脚本 4间可选套房 通过 --suite:

docker compose up -d   # Prerequisite

# All suites (44 tests, ~60s)
python scripts/test_recette.py --url http://localhost:8080

# Single suite
python scripts/test_recette.py --suite recette     # Agent pipeline (7 tests)
python scripts/test_recette.py --suite isolation    # Multi-tenant (18 tests)
python scripts/test_recette.py --suite qualite      # MCP tools (19 tests)

# Graph Memory suite (optional, requires running graph-memory)
python scripts/test_recette.py --suite graph \
  --graph-url http://host.docker.internal:8080 \
  --graph-token your_token

# List available suites
python scripts/test_recette.py --list

# Step-by-step + verbose
python scripts/test_recette.py --suite isolation -v --step --no-cleanup

______________________________________________________________________

🔒 安全

认证

• 持有者令牌 所有MCP请求都是强制性的
• Bootstrap键 创建第一个管理员令牌
• SHA-256令牌 存储在S3上（从不以明文形式）
• 3个级别：读、写、管理
• 空间范围：令牌可以限制为特定的空格

WAF（球童+科拉扎）

• OWASP CRS：SQL/XSS注入、路径遍历、SSRF
• 速率限制：200 MCP/min（流式HTTP）
• 自动TLS：让我们在生产中加密(SITE_ADDRESS=domain.com)
• 非根容器: mcp 用户

______________________________________________________________________

📂 项目结构

live-memory/
├── src/live_mem/              # Source code (40 MCP tools + web interface)
│   ├── server.py              # FastMCP server + middlewares
│   ├── config.py              # pydantic-settings configuration
│   ├── auth/                  # Authentication
│   │   ├── middleware.py      #   Auth + Logging + StaticFiles
│   │   └── context.py         #   check_access, check_write, check_admin
│   ├── static/                # /live web interface
│   │   ├── live.html          #   SPA (Dashboard + Live + Bank)
│   │   ├── css/live.css       #   Styles (Cloud Temple theme)
│   │   ├── js/                #   7 JS modules (config, api, app, dashboard, timeline, bank, sidebar)
│   │   └── img/               #   Cloud Temple SVG Logo
│   ├── core/                  # Business services
│   │   ├── storage.py         #   S3 dual SigV2/SigV4 (Dell ECS)
│   │   ├── space.py           #   Memory spaces CRUD
│   │   ├── live.py            #   Live notes (append-only)
│   │   ├── consolidator.py    #   LLM Pipeline (4 steps)
│   │   ├── graph_bridge.py    #   🌉 Link to Graph Memory
│   │   ├── tokens.py          #   SHA-256 tokens management
│   │   ├── backup.py          #   S3 snapshots
│   │   ├── gc.py              #   Garbage Collector
│   │   ├── locks.py           #   asyncio locks per space
│   │   └── models.py          #   Pydantic models
│   └── tools/                 # MCP Tools (7 modules)
│       ├── system.py          #   3 tools (health, whoami, about)
│       ├── space.py           #   9 tools (spaces CRUD)
│       ├── live.py            #   3 tools (notes)
│       ├── bank.py            #   8 tools (bank + consolidation + compaction + admin)
│       ├── graph.py           #   4 tools (Graph Bridge)
│       ├── backup.py          #   5 tools (snapshots)
│       └── admin.py           #   8 tools (tokens + GC + purge + bulk)
├── scripts/                   # CLI + Shell + Tests
├── waf/                       # Caddy + Coraza WAF
├── clinerules.md              # 📋 Cline Custom Instructions template (copy + customize)
├── DESIGN/live-mem/           # 9 architecture documents
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml             # Dependencies & project config (uv)
├── uv.lock                    # uv lockfile
├── VERSION                    # 1.9.0
├── CHANGELOG.md
└── FAQ.md

______________________________________________________________________

🔍 故障排除

服务未启动

docker compose logs live-mem-service --tail 50
docker compose logs waf --tail 20

401未经授权

• 检查您的令牌： Authorization: Bearer YOUR_TOKEN
• Bootstrap密钥不是令牌——首先通过以下方式创建令牌 admin_create_token

整合失败

• 在中检查LLMaaS凭据 .env
• 默认超时为600秒——增加 CONSOLIDATION_TIMEOUT 如有需要
• 只有一个 bank_consolidate 每个空间一次（异步锁）

______________________________________________________________________

🔗 相关项目

______________________________________________________________________

📄 许可证

Apache许可证2.0

______________________________________________________________________

👤 作者

云庙 — cloud-temple.com

由开发 克里斯托夫·莱瑟.

______________________________________________________________________

*Live Memory v1.9.0——协作AI代理的共享工作内存*