MemALL

Multi-agent Memory OS — 本地优先的 AI Agent 持久化记忆系统

7 MCP tools · 3 priority + 11-layer memory lifecycle · 31-step self-evolving pipeline · Knowledge graph · Multi-agent shared memory · Hook-driven automation

English · 中文 · Changelog

✨ What is MemALL?

MemALL gives AI Agents memory that persists across sessions, tools, and agents. Install it, connect it to Claude Desktop / Cursor / Cline / any MCP client, and your agents stop starting from scratch every conversation.

pip install memall-os          # install (lightweight, no AI models)
pip install memall-os[full]    # install + viz + FAISS
pip install memall-os[rerank]  # install + cross-encoder reranking (HEAVY: ~1.8GB, requires PyTorch)
memall init                    # initialize
memall start                   # start services
memall hook list               # list registered lifecycle hooks
memall hook register post_capture --action log  # register a hook
# → MCP ready at http://127.0.0.1:9876/mcp
# → MCP ready at stdio (add to your mcp.json)

Then in any MCP client:

{
  "mcpServers": {
    "memall": {
      "command": "memall",
      "args": ["serve"]
    }
  }
}

# /capture "Decided to go open-source: MIT license, GitHub-first distribution"
# /retrieve "pricing decision"
# → finds the memory above, plus its context, timestamp, and relations

🔥 Why MemALL?

🧠 14-Level Memory Lifecycle (3 Priority + 11 Lifecycle Layers)

Not just "store and retrieve". Every memory has a semantic level with exclusion-based priority classification, epoch detection, and echo scoring:

Scope note: "Cross-domain" at L10 means cross-category within one agent (produced by integrate_step). Truly cross-agent insight is produced separately by the cross_agent pipeline step, which can also emit L10 (cross-agent L9 aggregation) and L11 (domain patterns recurring across ≥5 agents). The two mechanisms are distinct.

30 core steps + 5 optional auto pipeline (see list_pipeline_steps()): enriches → classifies → detects epochs → reflects → distills → integrates → observes. No manual CRUD needed.

🔗 Knowledge Graph

Memories are connected by typed edges (refines, cites, contradicts, supersedes, extends). Traverse from "bug #123" to "fix PR #456" to "retrospective L6 reflection" in one hop.

/capture "Bug #123: OOM on large datasets"
/connect 123 456 --relation "resolved_by"
/traverse 123
→ finds #456 (fix), #789 (regression test), #912 (L6 reflection)

🤝 Multi-Agent Shared Memory

Claude, opencode, Codex, WorkBuddy — all reading from and writing to the same memory base. Cross-agent queries, fact extraction, and active push delivery are single MCP calls.

/fed_query "architecture decision last week" agent_name="claude"
→ returns cross-agent results with source attribution

🔄 Self-Evolving Pipeline

MemALL doesn't just store — it improves itself:

1. L6 Reflection — auto-reviews work quality, identifies patterns, corrects mistakes
2. L7 Preference Extraction — learns user preferences from interaction patterns
3. Hook-Driven Automation — post-capture auto-triggers lightweight pipeline + discussion convergence; pre-retrieve injects pending work; post-pipeline reports rich summaries
4. L9 Distillation — compresses raw conversations into structured knowledge
5. L11 Domain Intelligence — cross-project pattern detection
6. Forget & Adaptive — TTL-based decay, low-value cleanup, automatic re-indexing
7. OODA Loop — Observe → Orient → Decide → Act, no human intervention

🏠 100% Local

SQLite + FTS5 + vector search. Zero cloud dependency. Your data stays on your machine.

🛠️ MCP Tool Surface (7 server endpoints)

Count clarification: The gateway exposes 7 top-level MCP tools (memall_write, memall_read, memall_persona, memall_discussion, memall_federation, memall_system, memall_hooks_recent). Each is a consolidated tool with many actions — the table below lists the individual actions, which may read like "30+ tools" but are dispatched through those 7 endpoints. This is why older docs said "6 consolidated tools": the count depends on whether memall_hooks_recent is counted. Source of truth: src/memall/mcp/tools/__init__.py.

🚀 Quick Start

# One-shot install + start (recommended)
pip install memall-os && memall quickstart

# Or from source
git clone https://github.com/j19800/MemALL.git
cd MemALL
python install.py

memall quickstart initialises the database, starts the gateway, wires up the MCP config, and opens the browser — nothing else to configure.

Then start recording:

memall capture "Project X: decided to use FastAPI, reason: async support"
memall capture "Fixed OOM bug in NLP pipeline — root cause: vector dimension mismatch"
memall retrieve "FastAPI decision"

📊 Why Not Competitors?

📁 Project Structure

src/memall/
├── cli/          # CLI (40+ commands)
├── core/         # SQLite / NLP / vector search / event processor / echo scoring
├── api/          # FastAPI REST (35 routes)
├── mcp/          # MCP adapter (7 consolidated tool endpoints)
├── pipeline/     # 31-step auto pipeline + 5 optional (see list_pipeline_steps())
│   ├── observe/  # OODA observation step
│   ├── distill/  # L9/L10/L11 distillation, L7 preference, epoch detection
│   ├── classify/ # Exclusion-based priority classification
│   └── forget/   # TTL decay, L5 archive, low-value decay
├── graph/        # Knowledge graph + arc lifecycle management
├── federation/   # Cross-device memory sync + active push delivery
├── plugins/      # Hook/event-driven dashboard, exporter, notifier, scheduler
└── migrations/   # DB migrations

📝 Roadmap

• v0.1.0 — Core MCP server, 7 consolidated tool endpoints, CLI, PyPI package
• v0.1.69 — Repo made clonable again (task_identity + migrations 038/040 were live but uncommitted), goal triage gate now emits an action, skills layer transactions fixed for concurrency, policy refusals return 403 instead of 500
• v0.1.70 — Every remaining cross-agent read path closed: esources/read, ed_publish laundering/attribution forgery, and raverse/ imeline/ race now apply the trust filter; amily.db follows MEMALL_DB_PATH. Five red/blue duels now guard these.
• v0.1.71 — The four remaining P1s: security permit is now authorised (no self-escalation), contract level/category can no longer be rewritten through update(), destructive gateway routes require a credential even from loopback, and the two identity normalisers are unified. Seven red/blue duels guard them. Also fixes a convergence regression my own identity change introduced.
• v0.2.0 — Web dashboard, user system, Pro tier gating
• v0.3.0 — Cloud sync, team collaboration, API gateway

Known gaps (stated, not hidden)

• claim_task is not atomic across processes. mcp/tasks.py does read → modify → UPDATE ... WHERE id = ? with no state predicate and no row lock, so two concurrent claims end last-writer-wins and claimed_by is silently overwritten. Planned: add a state predicate or a unique index on (task_id, status).
• Goal-level block reasons are not observable. Cards already carry a two-value last_block_reason enum; goals still return None when they are stuck, so "why this goal is not moving" is invisible.
• The guard suite is slow by design. Every guard replays all migrations via init_db(), so a full run is measured in hours rather than minutes. Treat a green card guard set as evidence for that set, not for the whole repository.
• check_fixes.py leaves scratch directories under %TEMP% (mkdtemp without rmtree).
• The 2026-10-31 red/blue P1s are closed, with two exceptions. security permit now requires authorisation, contract level/category are immutable through update(), destructive gateway routes need a credential even from loopback, and the two identity normalisers are unified into core/agent_names.py. Still open from that report: the gateway's loopback carve-out is narrower but not gone (SPA reads remain tokenless by design), and claim_task is still not atomic across processes.
• Write-side attribution is not refused. By the chosen policy ("writes pass, reads are locked") an explicit agent_name can still create work on another agent's behalf; impersonation is made observable via wake_audit/ops_log rather than rejected.

🤝 Contributing

PRs welcome! See CONTRIBUTING.md for guidelines.

• Report bugs → Issues
• Ask questions → Discussions
• Browse the code → Repository

📄 License

MIT License. See LICENSE for details.

[¹] Cross-encoder reranking requires pip install memall-os[rerank] (downloads PyTorch + ~560MB model on first use). Core search works without it using RRF fusion of FTS5 + vec0.