🧠 Live Memory — MCP Knowledge Live Memory Service

Shared working memory for collaborative AI agents

🇫🇷 Version française

📋 Table of Contents

• Concept

• Architecture

• Prerequisites

• Installation

• Configuration

• Getting Started

• MCP Tools

• Graph Bridge

• Web Interface

• MCP Integration

• CLI and Shell

• Tests

• Security

• Project Structure

• Troubleshooting

• Contributing

Related MCP server: knowledgeplane

🎯 Concept

Live Memory is an MCP (Model Context Protocol) server that provides Memory Bank as a Service for AI agents. Multiple agents collaborate on the same project by sharing a common working memory.

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

Two Complementary Modes

Why Live Memory?

🧠 Multi-agent Collaboration and Two-Level Memory Architecture

Recent research on LLM-based multi-agent systems (Tran et al., 2025 — Multi-Agent Collaboration Mechanisms: A Survey of LLMs) identifies shared memory as a fundamental component. In their formal framework, a multi-agent system is defined by agents (A), a shared environment (E), and collaboration channels (C). The authors emphasize that LLMs are inherently isolated algorithms, not designed to collaborate — they need a shared memory infrastructure to coordinate their actions.

Live Memory + Graph Memory directly implements this architecture:

┌─────────────────────────────────────────────────────────────┐
│                  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)   │      │
│                               └──────────────────────┘      │
└─────────────────────────────────────────────────────────────┘

The Graph Bridge (graph_push) is the collaboration channel between these two levels. Following the late-stage collaboration pattern described in literature (sharing consolidated outputs as inputs to another system), it transforms working documentation (Markdown) into structured knowledge (entities/relations graph).

Why two levels? One level is not enough:

• Working memory alone is ephemeral — it disappears when the project ends

• Knowledge graph alone is too heavy for quick daily notes

• The bridge between the two allows agents to work fast (live notes) while capitalizing knowledge (graph)

Specifically, agents can:

1. Write quickly without friction (live-memory, append-only, ~50ms)

2. Automatically consolidate via LLM into structured documentation (bank, ~15s)

3. Persist knowledge in a searchable graph (graph-memory, ~2min)

4. Query the graph in natural language to retrieve information from past projects

🏗️ Architecture

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

Minimal Stack: S3 + LLM. No local database. Optional: connection to Graph Memory for long-term memory (knowledge graph).

📦 Prerequisites

• Docker >= 24.0 + Docker Compose v2

• Python 3.11+ (for CLI, optional)

• A compatible S3 storage (Cloud Temple Dell ECS, AWS, MinIO)

• An OpenAI API compatible LLM (Cloud Temple LLMaaS, OpenAI, etc.)

🚀 Installation

1. Clone the repository

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

2. Configure the environment

cp .env.example .env

Edit .env with your values (see Configuration).

3a. Docker Start (recommended)

# 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. Local Start (development)

# Install dependencies
uv pip install -e .

# Run server
python -m live_mem

4. Install CLI (optional)

uv pip install -e .

5. Verify Installation

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

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

Exposed Ports

⚙️ Configuration

Edit .env. All variables are documented in .env.example.

Mandatory Variables

Optional Variables — LLM

The service can use distinct OpenAI-compatible models for consolidation and hierarchical compaction.

Optional Variables — Consolidation and Compaction

During consolidation, duplicate Markdown sections are merged only when the merge is non-empty. If the model returns an error or an empty result, Live Memory preserves every current occurrence, stops deduplication for that file, continues the batch, and exposes the event through dedup_failures_count.

▶️ Getting Started

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

🔧 MCP Tools

44 tools exposed via the MCP protocol (Streamable HTTP), divided into 7 categories.

System (3 tools)

Space (10 tools)

Mission-space badges (v2.9.0)

space_badge_mint is deliberately not a general ACL mechanism. Only the exact standard token that created a space can mint a badge for an agent instance. A badge is restricted to that one space and to system_whoami, live_read, and live_note; it has a fixed 24-hour lifetime. Re-minting the same client_name revokes its prior badge, and deleting the space revokes all of its badges first.

The intended flow is: mcp-mission holds the creator token and requests a badge after it has authenticated the mission and reserved the runtime agent identity; mcp-agent keeps the returned secret private and uses it only for the mission space. Badges cannot call the web API or the admin console.

Live (3 tools)

Bank (11 tools)

Applied bank_compact is asynchronous: it joins the same per-space FIFO as consolidation and returns a job_id. For each logical file above BANK_FILE_MAX_SIZE, bounded Map calls create ephemeral cards for complete Markdown source units and one Reduce writes a compact, non-exhaustive Markdown digest. The server validates that digest, replaces all eligible historical units with one code-owned, recompactable container, and requires the candidate to reduce the original file strictly. When protected content makes the target unreachable, a safe digest may remain above the configured limit and reports target_met=false; otherwise the target remains enforced. Recent, undated, code-bearing, HTML-bearing and external content stays byte-identical. In dated mode, the digest may consume at most 75% of the space left after protected content only when the target is reachable; the remaining 25% is growth headroom. Best-effort compaction uses its full safe reduction budget. All candidates are validated before a full-space backup is created. Persisted content is read back and verified; failure triggers a verified bank/ rollback. If rollback also fails, the job reports the backup_id needed for manual restore. No new *.part-NNN.md object is created. Legacy v2.7.x multipart families are read losslessly, then reassembled into their single canonical file by compaction, consolidation, or an explicit bank_write restoration.

Since v2.7.1, consolidation validates the complete LLM edit plan before the first write. Bank and synthesis outputs (plus metadata outside normal batched mode) are rolled back and verified as one batch on failure; source notes are deleted only after every fallible operation in that batch has completed. Final metadata/audit I/O runs after committed batches but can only return partial; it never rolls them back. Partial note deletion exposes verified restoration/loss metrics. Multi-file compaction restores only bank/, so a live note created concurrently is never removed by rollback. Terminal job results are persisted for post-restart audit; active/queued jobs remain an in-memory FIFO.

When 2.8+ compaction has legitimately absorbed an old heading, a surgical replace_section, append_to_section, or prepend_to_section may recover it only as a strict ATX heading with non-empty content at the end of the existing logical file. An absent delete_section is idempotent. This compatibility path does not create files, infer Markdown parents, relax other plan validation, or hide the event: terminal results expose recovered_operations, and recovered files are read back exactly before source notes are deleted.

Since 2.9.3, automatic pre-consolidation is advisory when a refusal leaves the Bank intact, or when a failed write has an exact verified rollback: it is reported in compaction while normal live-note consolidation continues. Since 2.9.4, BANK_FILE_MAX_SIZE is also a target for manual and automatic compaction: a safe candidate strictly smaller than its source may remain above it only when protected content already makes the target unreachable; target_met reports that outcome. Only an inconsistent legacy split family or an unverified compaction rollback blocks bank_consolidate; bank_compact remains strict on integrity checks.

2.8.0 release-ready — product-owner accepted, not deployed: bounded Maps plus one Reduce passed the real-corpus mechanical gates. Comparative review selected mistral-small4:119b as the recommended compaction model: it preserved the global meaning and important operational points better than the tested Qwen models. gpt-oss:120b is not supported for this compaction path: it reached finish_reason=length with the product Map ceiling of 4,000 tokens and remained slower and less faithful in an 8,000-token R&D rerun. Compaction is intentionally lossy and still requires a manual canary before production. See the 2.8.0 hierarchical compaction design.

Graph (4 tools) — 🌉 Link to Graph Memory

Backup (5 tools)

Admin (8 tools)

🌉 Graph Bridge — Link to Graph Memory

⚠️ Architecture note (v2.5.0) — Live Memory + Graph Memory responsibility separation

• Memory Bank (Live Memory) = compact session bootstrap. activeContext.md is a volatile focus snapshot, progress.md is a bounded recent journal. The consolidator continuously rewrites and compacts these files.

• Graph Memory = durable semantic index for stable canonical documents (RFCs, incidents, runbooks, design docs, infrastructure inventories).

• Repository files = final authority.

Graph Memory complements the bank; it does not replace it. Graph Memory localizes; canonical repository files confirm.

Therefore, graph_push is NOT a routine action: pushing the full bank into the graph teaches it transient content that a later compaction strands as stale. Routine flows should ingest canonical repository documents directly into Graph Memory from the agent / tooling layer, using stable source_path keys. graph_push remains available for one-off bootstrap and explicit debug / migration only.

In particular, activeContext.md and progress.md must never end up in Graph Memory. A future revision (tracked in DESIGN/live-mem/EVOLUTION_LIVE_GRAPH_INTEGRATION.md) will turn this into a server-side guardrail. See WORKSPACE_CLINE_ADVANCE_RULES.md for the agent-side template.

Live Memory can push its Memory Bank into a Graph Memory instance for long-term memory. The knowledge graph extracts entities, relations, and embeddings from bank files.

Workflow

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

2. bank_consolidate(space_id)
   └─ Queues async consolidation; call once and do not watch/poll unless explicitly requested

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...

Smart Push (delete + re-ingest)

Each push is a complete refresh of the graph for that file. Existing files are deleted then re-ingested so Graph Memory recalculates entities, relations, and embeddings with up-to-date content.

Available Ontologies

🖥️ Web Interface

Live Memory exposes a web interface on /live to visualize memory spaces in real-time.

Access

http://localhost:8080/live

Features

Layout

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

Smart Auto-refresh

• Configurable: 3s / 5s / 10s / 30s / manual

• Anti-flicker: only re-renders DOM if data has changed

• Pulsing green dot with last refresh timestamp

• Space selection → immediate loading (no button needed)

REST API (5 endpoints)

/api/* endpoints require a standard Bearer Token. Mission-space badges are MCP-only and are refused, including by /api/login. /live page and /static/* files are public.

Admin Console (/admin)

A full administration console is available at /admin, exposing all 44 MCP tools through a web interface:

http://localhost:8080/admin

• Auth: requires a valid token (same as /live), session via HttpOnly cookie

• CSP-safe: zero inline handlers, all via data-action + event delegation

• Upload Rules: file picker (.md) or paste directly from the Rules modal

🔌 MCP Integration

📖 Full Guide: See CLINE_INTEGRATION_GUIDE.md for the step-by-step guide (Cline configuration, custom instructions, workflow, multi-agents, troubleshooting). Equivalent guides exist for CLAUDE_CODE_INTEGRATION.md and CODEX_INTEGRATION.md.

With Cline (VS Code / VSCodium)

In Cline's MCP settings (cline_mcp_settings.json):

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

To configure the Custom Instructions for your agent, copy one of the two workspace rule templates into your Cline global Custom Instructions (or into a .clinerules/ directory in your project):

Customize a few placeholders ({LIVE_MCP_SERVER}, {SPACE}, and for the advanced template {GRAPH_MCP_SERVER} / {GRAPH_MEMORY_ID}). The agent name is auto-detected from the authentication token — nothing else to configure.

💡 Ready-to-use templates: WORKSPACE_CLINE_RULES.md (Live-only) and WORKSPACE_CLINE_ADVANCE_RULES.md (Live + Graph) — copy and customize the placeholders.

📖 Detailed integration guides: CLINE_INTEGRATION_GUIDE.md, CLAUDE_CODE_INTEGRATION.md, CODEX_INTEGRATION.md.

With Claude Desktop

In claude_desktop_config.json:

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

Via Python (MCP client)

from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
import httpx2

async def example():
    headers = {"Authorization": "Bearer your_token"}
    async with httpx2.AsyncClient(
        headers=headers, timeout=httpx2.Timeout(30, read=30),
        follow_redirects=True, trust_env=True,
    ) as http_client:
        async with streamable_http_client(
            "http://localhost:8080/mcp", http_client=http_client
        ) 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 and Shell

CLI Installation

pip install click rich prompt-toolkit 'mcp[cli]>=2.1.1,<3' 'httpx2>=2.5.0,<3'
export MCP_URL=http://localhost:8080
export MCP_TOKEN=your_token

CLI Commands (Click)

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

Interactive Shell

python scripts/mcp_cli.py shell

Autocomplete, history, Rich display. See scripts/README.md for full reference.

🧪 Tests

Unified test script with 4 selectable suites via --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

🔒 Security

Authentication

• Bearer Token mandatory on all MCP requests

• Bootstrap key to create the first admin token

• SHA-256 Tokens stored on S3 (never in clear text)

• 3 levels: read, write, admin

• Space scope: a token can be limited to specific spaces

• Mission badge: no general permission; one mission space and only system_whoami, live read/write MCP operations. It is rejected by the web API and admin console.

WAF (Caddy + Coraza)

• OWASP CRS: SQL/XSS injection, path traversal, SSRF

• Rate Limiting: 200 MCP/min (Streamable HTTP)

• Automatic TLS: Let's Encrypt in production (SITE_ADDRESS=domain.com)

• Non-root container: mcp user

📂 Project Structure

live-memory/
├── src/live_mem/              # Source code (44 MCP tools + web interface)
│   ├── server.py              # MCPServer v2 + 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           #   10 tools (spaces CRUD + mission badge)
│       ├── live.py            #   3 tools (notes)
│       ├── bank.py            #   11 tools (bank + consolidation + supervision + maintenance)
│       ├── 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
├── WORKSPACE_CLINE_RULES.md           # 📋 Cline Custom Instructions template — Live Memory only
├── WORKSPACE_CLINE_ADVANCE_RULES.md   # 📋 Cline Custom Instructions template — Live Memory + Graph Memory
├── RULES/                     # 📜 Memory Bank rules templates (general, book, medical, presales, product management, company steering)
├── DESIGN/live-mem/           # 9 architecture documents
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml             # Dependencies & project config (uv)
├── uv.lock                    # uv lockfile
├── VERSION                    # 2.9.5
├── CHANGELOG.md
└── FAQ.md

🔍 Troubleshooting

Service does not start

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

401 Unauthorized

• Check your token: Authorization: Bearer YOUR_TOKEN

• Bootstrap key is not a token — create a token first via admin_create_token

Consolidation fails

• Check LLMaaS credentials in .env

• Default timeout is 1800s (30 minutes) to accommodate slower, higher-quality consolidation models

• bank_consolidate returns an async job acknowledgement (running or queued) with next_action="return_to_user_without_polling"; call it once and do not watch/poll unless explicitly requested

• bank_consolidation_status(job_id) remains available for manual status checks only

🤝 Contributing

Development is driven entirely through GitHub — issues, branches, pull requests, code reviews and project status all live there. This makes the project easy to pilot remotely from the command line with the gh CLI (including by AI coding agents): create an issue, branch, open a PR, review and merge without ever leaving the terminal or the GitHub UI.

The full, mandatory workflow is documented in WORKSPACE_WORKFLOW_GIT.md:

• Branch + PR only — no local merge into main; every change lands through a pull request merged on GitHub.

• Issue lifecycle — self-assign, move the Projects status to In Progress, keep solution-design discussion in the issue.

• PR ↔ issue link — a Closes #N keyword in the PR body auto-closes the issue on merge.

• PR-channel reviews — once a PR is open, code-review discussion moves to the PR; every review conclusion is published on GitHub (gh pr review / gh pr comment), not only in chat.

Following this file keeps the issue and PR histories clean and auditable, and lets a contributor (or an agent) drive the whole cycle reproducibly via gh.

🔗 Related Projects

📄 License

Apache License 2.0

👤 Author

Cloud Temple — cloud-temple.com

Developed by Christophe Lesur.

Live Memory v2.9.5 — Shared working memory for collaborative AI agents