Skip to main content
Glama
skynetcmd

M3 Memory

by skynetcmd
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

🧠 m3 Memory

A memory layer that outlives your agents. You switch from Claude Code to Cursor, upgrade your model, start fresh next week — and everything your tools learned about your project is gone. You re-explain the same decisions, the same preferences, the same hard-won context, over and over.

m3 fixes that. It's a private, local-first memory your agents share and build on — so your project's knowledge accumulates instead of resetting every time the agent does. One memory store, on your machine, that your tools and agents read from and write to — whether that's Claude Code, Cursor, Gemini CLI, or any MCP-compatible agent.

Building something yourself? m3 is a memory backend, not a framework, and MCP is optional — every tool is a JSON-in/JSON-out CLI call, scriptable from any language, hook or CI job. Jump to the developer section ↓

Under the hood, m3 treats agent memory as a distributed-systems infrastructure problem, not a simple retrieval feature — a shared, evolving, bitemporal, contradiction-aware knowledge base that multiple heterogeneous agents and machines read and write, built to stay consistent over months and years.

The memory improves without being asked. m3 is not only a store you write to and read back. An autonomous Cognitive Loop (m3_cognitive_loop.py) runs in the background and keeps working on what you already saved: deferred enrichment — classification, embedding, and entity extraction — runs off the hot path, so a write stays fast while the understanding of it deepens afterwards, and the loop builds an entity relationship graph from memories that arrived as plain text. Curation is m3's own work, not an LLM's. Near-duplicate detection is cosine similarity over embeddings against a threshold; decay and pruning are age-and-signal rules; and applying a curation plan — bulk deletes, merges, supersessions — is one deterministic function issuing direct SQL, with no model in the loop. That is deliberate: the apply step used to be an LLM agent, and it failed by looping single-row deletes across hundreds of IDs until it ran out of budget. An agent's judgement is still welcome for the genuinely subjective calls ("is this worth keeping?"), but it emits a plan and m3 executes it — one round-trip instead of N, and no model needed for the mechanical part.

Contradictions are caught on three paths, not one: deterministically on the write path (cosine similarity against a threshold, no model), by the loop's Reflector pass during enrichment (which writes supersedes edges), and by an explicit curation plan. Promotion of chat turns into long-term memory is the one thing that stays deliberate — nothing promotes on your behalf.

It runs where your data has to stay. A single pip install with no account, no API key, and no outbound calls — at home in a homelab, on a corporate or government network, or fully air-gapped. Embedding runs on your own hardware via a shared local embed server — one model in RAM that every m3 process reuses, rather than a copy per process — the store is a file you own, and installation works with no internet at all. On the metric that isolates the memory layer — retrieval accuracy, no answer model or judge involved — m3 reaches 99.2% session-hit-rate @ k=10 and 100% @ k=20 on LongMemEval-S.

🎬 Quick video overview

One decision saved from a conversation, then recalled by a different agent in a new session, on a different machine. Captioned throughout, so it reads fine muted.

https://github.com/user-attachments/assets/09ab194a-d2a0-4fe5-a7db-69ae8225e39b

Player not loading? Download the video to play locally.

Related MCP server: memento

⚡ Quickstart

pip install m3-memory   # or: pipx install m3-memory — pick ONE and stay with it
m3 setup            # detects your agents, wires the MCP server, provisions the local embedder
m3 doctor           # verify: health, memory count, embedder, and which agents got wired

That's the whole install. No cloud account, no API key, no external embedding service.

What it does, in four lines

Save a decision — your AI agent, or you from the shell:

$ m3 memory memory_write --type decision --title "auth-jwt-algorithm" \
    --content "The auth service uses RS256 JWTs. HS256 was rejected because we need asymmetric verification at the edge."
"Created: 84a944fb-ef3e-403b-9240-f53ab3c015f7"

Next week, in a different agent, on a different model — ask in your own words:

$ m3 memory memory_search --query "which signing algorithm did we pick for tokens?" --k 3
{
  "count": 1,
  "items": [
    {
      "id": "84a944fb-ef3e-403b-9240-f53ab3c015f7",
      "score": 0.7501,
      "type": "decision",
      "title": "auth-jwt-algorithm",
      "content": "The auth service uses RS256 JWTs. HS256 was rejected because we need asymmetric verification at the edge."
    }
  ]
}

Prefer the rendered form for reading? Add --no-as_records.

The query shares no keywords with the stored text — no "RS256", no "JWT" — and still finds it. That's the hybrid engine: BM25 for exact terms, local BGE-M3 vectors for meaning, MMR for diversity. Your agent calls the same tools over MCP, so it recalls this automatically instead of asking you again.

New here? The 5-Minute Getting Started Guide walks the same path with more context, and Core Tools lists the five you'll use most.

🛠️ For developers: a memory backend, not a framework

MCP is optional. m3 is a memory layer — it owns durable, searchable, multi-agent memory and stops there, so it drops into whatever you already have instead of asking you to adopt a stack.

Every tool in the catalog reads JSON on stdin and writes JSON on stdout, so m3 is scriptable from any language or runtime — and from hooks, CI, and cron. No SDK, no client library, no MCP server required:

echo '{"query":"auth","k":3}' | m3 memory memory_search --json-file - | jq '.items[].id'

Results compose, so one tool's output drives the next:

# Pin everything matching a query — search, transform, bulk-update.
m3 memory memory_search --query "deployment runbook" --k 20 \
  | jq '{updates: [.items[] | {memory_id: .id, pinned: 1}]}' \
  | m3 memory memory_update_bulk --json-file -

Language-specific work stays on your side of the boundary — by design. Code parsing and VCS watching are integrations, not missing features, and each is a few lines of your own code:

# AST indexing with any parser you already trust — ast, tree-sitter, ts-morph.
symbols = [n.name for n in ast.walk(ast.parse(src))
           if isinstance(n, (ast.FunctionDef, ast.ClassDef))]
subprocess.run(["m3", "memory", "memory_write", "--json-file", "-"],
               input=json.dumps({"type": "reference", "title": path,
                                 "content": "\n".join(symbols)}), text=True)

That is what keeps one memory layer serving a Python monorepo, a Rust service and a TypeScript frontend without forking it.

Using m3 for coding work → — the full integration guide: composing tools, git hooks, CI steps, and where the layer boundary sits.

(jq is not a dependency — it just reads well in examples. m3 emits plain JSON, so any parser works.)

🧩 Beyond the core

The Quickstart above is the whole product for most people: shared memory, wired into your agents, working offline. Everything below is optional surface you can ignore until you want it — each row says what it costs to turn on.

Also a drop-in memory backend for LangChain / LangGraph, CrewAI, and PydanticAI — see the framework guides.

Every path gains automatic contradiction supersession, bitemporal historical queries, local sovereign embedding, and the full 100+ MCP tool set.

⚖️ How m3 Compares

A full, feature-by-feature comparison table — m3 vs Mem0, Letta, Zep, Graphiti, LangChain Memory / LangMem, agentmemory, Chronos, Hindsight, Mastra OM, Memento, and more — with sourced benchmarks and honest "when to choose the other tool" guidance, lives in COMPARISON.md.

Short version: m3 is the local-first, MCP-native option that stays yours and works across every agent — where cloud services (Mem0), full agent runtimes (Letta), and graph-database systems (Zep, Graphiti) each ask you to adopt their infrastructure. See the comparison guide for the row-by-row detail.

🚀 Quick Links & Badges

💡 Get Started Quickly:

📑 Table of Contents

⚡ m3 at a Glance

Feature

Details

Works With

Claude Code · Cursor · Cline · Gemini CLI · Aider · Google Antigravity · OpenCode · OpenClaw · Hermes · LangChain/LangGraph · CrewAI · PydanticAI · Any MCP Agent

m3 Is

A persistent memory layer · An MCP server · A hybrid retrieval engine · A bitemporal knowledge base

m3 Is Not

An LLM · A chatbot · A plain vector database · A RAG framework · An IDE

Core Promise

Private, offline-capable, locally owned memory shared securely across all your developer tools — with FIPS 140-3-ready crypto and atomic multi-agent writes for regulated and multi-agent environments.

Deploys In

Homelabs and self-hosted stacks · corporate and government networks · air-gapped and classified environments · regulated industries (FIPS 140-3-ready, GDPR tooling, audit logs). No account, no API key, no outbound calls. See Sovereign & Air-Gapped Deployments.

Speed

A deferred write — which includes validation, bitemporal logic, contradiction checking, hashing, and storing to SQLite with WAL — takes just ~2.16 ms (p50) / 3.66 ms (p95). To ensure the caller never waits, m3 intentionally defers the heavy vector embedding to a background cognitive loop. The memory is immediately full-text searchable (hybrid search takes ~45 ms p50 / ~48 ms p95), and vector search picks it up as soon as the background pass completes. Warehouse sync upserts 3,000 rows in 25 ms. Measured on a stock Windows desktop; see Performance for the hardware, the CPU-only numbers, and the caveats.

Retrieval Accuracy

State-of-the-art for a local-first substrate — 99.2% session-hit-rate @ k=10, 100% @ k=20 on LongMemEval-S (no oracle routing), with a gold session as the #1 result for 91.8% of questions. SHR measures the memory layer alone — no answer model, no judge — which is why it, not end-to-end QA, is the like-for-like comparison between memory systems. See Benchmarks.

Entity & Relationship Enrichment

Yes. m3 includes LLM-based entity extraction and relationship enrichment (Observer + Reflector), running as background cognitive passes over raw text — automatic once a local or cloud LLM endpoint is configured. Observer emits entities, facts and typed relationships from unstructured text; Reflector resolves contradictions and writes supersedes edges. Any OpenAI-compatible endpoint (LM Studio / Ollama / llama.cpp auto-probed locally, or a cloud model). See Enrichment Guide.

Context Efficiency

Exposes 100+ tools but occupies just ~2% of a 200K context window at startup — the 10 registered schemas absorb 95% of real tool calls; lazy domain-gating loads the rest on demand.

Maturity

Stable, battle-tested core engine (3,600+ tests) that's safe to build on today; new features and integrations are added actively. SQLite by default; PostgreSQL as a first-class primary backend (M3_DB_BACKEND=postgres) via a pluggable SQL storage seam. (See features.json)

🧠 Memory Model at a Glance

m3 is a typed, bitemporal, confidence-scored, self-maintaining knowledge base. Every feature listed below is implemented natively (see Memory Model Details):

  • Structured Metadata: Every memory contains a type, source, confidence, scope, provenance (change_agent), and salience (importance, decay_rate).

  • Verbatim, Non-Destructive Storage: Memory content is stored exactly as written and never altered in place — the raw text is always retrievable byte-for-byte. Corrections don't overwrite: a superseded fact is closed (its validity interval ends) and the new fact is linked to it, so both the original wording and its full edit history stay queryable. You get true verbatim recall and an audit trail, not one or the other.

  • Bitemporal History: Distinguishes valid-time from transaction-time. Because superseded facts are closed rather than deleted, you can query what the agent believed at any specific point in time.

  • Contradiction Management: Conflicting facts are resolved automatically on write. The stale fact is marked as superseded, and confidence values are updated dynamically via Bayesian confidence posteriors. Supersession fires above a deliberately conservative cosine bar (CONTRADICTION_THRESHOLD, default 0.92), so near-restatements of a claim close the old fact while genuinely different-but-related facts are both kept — use memory_supersede to close one explicitly. (See Technical Details.)

  • Self-Maintaining Lifecycle: Implements memory decay, deduplication, automatic consolidation into higher-order beliefs, TTL expiry, and GDPR erasure.

  • Procedural Memory: A first-class procedure type (skill / runbook / how-to / checklist) that is auto-distilled from successful task runs — the background loop rolls up a completed task and its step/result memories into a reusable, step-by-step procedure, preserved with distills_from provenance back to its sources. A "how do I…" query surfaces it via a procedural retrieval boost.

  • Write-Gating & Content Safety: Filters out low-signal noise via an enrichment queue and content safety guardrails before storage.

  • Explainable Retrieval: Hybrid engine combining vector similarity, BM25 (FTS5), MMR diversity, and reranking. memory_suggest returns the exact score breakdown per result. (See Confidence and Trust Guide).

  • Proven Accuracy: On LongMemEval-S, m3 delivers state-of-the-art retrieval for a local-first substrate — 99.2% session-hit-rate @ k=10 and 100% @ k=20 (no oracle routing), with a gold session as the #1 result for 91.8% of questions. End-to-end QA accuracy is 92.0% with no oracle metadata (see Benchmarking Report).

📦 Installation

⚠️ Python 3.12+ required (changed in 2026.9.13.0)

m3 now requires Python 3.12 or newer. Releases up to and including 2026.9.12.0 supported Python 3.11; from 2026.9.13.0 onward, pip will refuse to install m3 on 3.11 and will silently keep you on the last 3.11-era release instead of upgrading.

On Python 3.11? Check with python --version. To upgrade:

  • macOS: brew install python@3.14 && brew link --overwrite python@3.14

  • Windows: winget install -e --id Python.Python.3.14

  • Debian/Ubuntu: use deadsnakes or a distro release shipping 3.14.

After a Python minor-version bump, recreate your virtualenv (rm -rf .venv && python3 -m venv .venv) — see HOW-TO-UPGRADE.md. Your memories are unaffected: the databases live outside the venv under ~/.m3/engine.

We recommend 3.14 or newer for new installs. Python 3.13 enters security-fix-only maintenance upstream on October 1st (no further bug fixes), so a future m3 release will raise the floor again — announced at least one minor release in advance.

The Quickstart above covers the common path (pip install m3-memory → m3 setup). This section adds the alternatives: the shell installer, per-agent wiring, and manual MCP configuration.

The One-Liner (macOS & Linux)

curl -fsSL https://raw.githubusercontent.com/skynetcmd/m3-memory/main/install.sh | bash

Developer Setup Wizard

If you are developing inside python environments:

pip install m3-memory
m3 setup

The m3 setup wizard automatically detects your installed agents — Claude Code, Cursor, Cline, Gemini CLI, OpenCode, Antigravity, OpenClaw, Hermes — and wires the m3 memory MCP server into each, installs settings files/hooks, provisions the sovereign CPU embedder, and performs a system diagnostic. Detection and wiring re-run on every m3 update/m3 setup, and m3 doctor --fix repoints any config whose paths have moved — so an agent you install later gets picked up automatically the next time you run setup or update.

Integrating with AI Coding Tools

🤖 Claude Code

Install as a plugin to unlock /m3:* slash commands, curation subagents, and automatic hooks:

/plugin marketplace add skynetcmd/m3-memory
/plugin install m3@skynetcmd

See Claude Code Plugin Reference and Claude.ai Connector Guide.

▷ Cursor

Auto-detected and wired by the setup wizard — it writes the m3 memory MCP server into ~/.cursor/mcp.json:

m3 setup

Re-run after installing Cursor and it's picked up automatically; m3 doctor --fix repoints the entry if paths move. See MCP Client Install Guide.

◧ Cline (VS Code)

Auto-detected and wired by the setup wizard — it writes the m3 memory MCP server into Cline's cline_mcp_settings.json:

m3 setup

Also available from Cline's MCP marketplace (see llms-install.md). See MCP Client Install Guide.

🪐 Google Antigravity

Install the plugin directly:

agy plugin install https://github.com/skynetcmd/m3-memory

See Antigravity Plugin Reference.

🦊 Hermes Agent

Run the wizard to automatically wire up optimal memory providers:

m3 setup

See Hermes Plugin Integration Guide.

🐍 Python / LangChain & LangGraph

Use m3 as a drop-in Mem0 replacement or LangMem backend:

pip install m3-memory[langchain]

See LangChain Integration Guide.

👥 CrewAI (v1.x)

A drop-in StorageBackend for CrewAI's unified memory:

pip install m3-memory[crewai]   # crewai>=1.10,<2 · Python 3.12–3.13 (a 3.14 escape hatch is documented)

See CrewAI Integration Guide.

🧩 PydanticAI

m3 tools + auto-recall, or a formal M3MemoryToolset. Built on Pydantic v2 — runs natively on Python 3.14:

pip install m3-memory[pydantic-ai]   # pydantic-ai-slim>=2,<3

See PydanticAI Integration Guide.

⌨️ The m3 CLI — the same memory, without an agent

MCP is not the only way in. The m3 CLI and the MCP server are two front doors to the same database, so anything an agent can do over MCP you can do from a shell — the whole tool catalog, grouped as memory, files, chatlog, tasks, agent, admin, conversations, diagnostics and entity:

m3 memory memory_search --query "which signing algorithm did we pick?" --k 5
m3 memory memory_write --content "..." --type belief --title "..."
m3 memory memory_write_from_file --path notes.md --type belief --title "..."
m3 chatlog status

Content comes from a command-line argument (--content) or from a file (--path) — handy when the body is long enough that shell quoting would mangle it.

Results go to stdout and logs to stderr, so output pipes cleanly into jq, grep or a script:

m3 memory memory_search --query "postgres" --k 20 2>/dev/null | jq '.'

This matters when your MCP client drops the connection: that is not a memory outage. A dropped stdio session only the client can respawn leaves the store completely intact and fully usable from the CLI until you reconnect (/mcp in Claude Code). Check with m3 --version; if the CLI answers, m3 is up.

See the CLI Reference for the full command surface.

Manual MCP Server Configuration

To expose m3 to any Model Context Protocol host, add it to your configuration file:

{
  "mcpServers": {
    "memory": {
      "command": "m3"
    }
  }
}

🎚️ Domain Gating: the Full Catalog Without the Context Cost

m3 gives you the full 100+ tool surface while occupying just 2% of a 200K context window at startup — most MCP servers make you pay for every tool in every prompt. Tools are grouped into 9 domains (memory, chatlog, files, entity, agent, tasks, conversations, diagnostics, admin) and loaded lazily.

Only 10 schemas register at startup (~3,929 tokens). That set is chosen by measurement rather than judgement: across real-world multi-agent development sessions it absorbed 95% of all observed tool calls, so gating the rest costs almost nothing in practice. When your agent needs more, it calls tools_load_domain(domain="...") to fetch a domain on demand — or invokes any single tool by name through m3_call, with no domain load at all.

Gating Mode

Registered Tools

Tokens in Schema

% of 200K Window

Lazy (Default)

10

~3,929

2.0%

Typical Active Session (+memory +admin)

56

~17,548

8.8%

Eager Mode (M3_TOOLS_LAZY=0)

115

~29,658

14.8%

🛠️ Note: If your client does not support dynamic tool registration, set the environment variable M3_TOOLS_LAZY=0 to register all tools eagerly.

🛡️ Sovereign & Air-Gapped Deployments

m3 operates completely offline by default.

Sovereign Local Embedder

A high-performance BGE-M3 embedder runs locally after installation.

  • Default: one shared local embed server on 127.0.0.1:8082, running the m3-embed-server binary that ships inside the m3-core-rs wheel. CPU execution using GGUF format (_assets/models/bge-m3-Q4_K_M.gguf). Every m3 process reuses that single server — one model in host RAM — and one GPU context when a GPU wheel is installed — instead of each loading its own copy. It is local-only and never leaves the machine.

  • Optional (opt-in at m3 setup): additionally embed in-process via the m3-core-rs native module (llama.cpp linked in-process, zero IPC). On measured real text it is faster than the shared server — ~1.9× on short chunks, ~1.75× on medium — so the reason to prefer shared is memory, not latency: in-process loads one model copy per process, and a typical setup runs several (MCP server, cognitive loop, CLI), while the shared server keeps one model in RAM for all of them. Choose in-process when you have RAM to spare and a short-text workload. (measurements and caveats)

  • Hardware Acceleration (GPU): Execute m3 embedder install-gpu to compile with CUDA, Vulkan, or Metal.

  • External Provider Fallback: Set M3_EMBED_URL to point at any OpenAI-compatible /v1/embeddings endpoint (Ollama, LM Studio, vLLM, or another machine's m3 embed server), and M3_EMBED_FALLBACK_URL for a second endpoint to try if the first is unreachable.

Rust-Oxidized Performance Core

m3 ships a Rust compute core (m3_core_rs) that speeds up MMR re-ranking, batch cosine distance calculations, and FTS compilations by 90× to 800×. It is installed by default (the installer's --no-native-wheel is the opt-out), not an optional add-on. A pure-Python fallback covers every code path and is results-equivalent — exact for FTS compilation and graph traversal, and within float tolerance for vector math, enforced by tests/test_oxidation_parity.py, test_fts_parity.py and test_graph_neighbor_parity.py. So the core changes speed, never answers: if the wheel is absent, or you set M3_CORE_RS_DISABLE=1, m3 falls back automatically and returns the same results more slowly. (See Oxidation Benchmarks).

Enterprise Security & Compliance

  • FIPS 140-3 Ready: Standardized encryption pathways allow routing through validated cryptographic modules (e.g., wolfSSL via M3_FIPS_MODE=1).

  • Air-Gapped Install: Supports installation without internet access via pre-compiled python wheels. (See Sovereign Deployment Guide & FIPS Boundary Reference).

  • Storage Location: State lives under three roots, so databases and configuration can be relocated and secured independently:

    Root

    Default

    Holds

    M3_ENGINE_ROOT

    ~/.m3/engine

    Databases + runtime state (agent_memory.db, agent_chatlog.db, files_database.db)

    M3_CONFIG_ROOT

    ~/.m3/config

    Configuration (chatlog config, salt)

    M3_MEMORY_ROOT

    ~/.m3-memory

    Payload / repo clone

    All three are overridable. Set any of them to relocate that root. M3_MEMORY_ROOT also acts as a master override — if set and the other two are unset, engine and config derive from it as <root>/engine and <root>/config. Precedence is M3_ENGINE_ROOT / M3_CONFIG_ROOT → M3_MEMORY_ROOT/… → the ~/.m3/… default, so a specific root always wins over the master. (See Architecture.)

🔮 What m3 Does

  • Memory Persistence: Saves system architecture, project decisions, and preferences across tool boundaries using a local SQLite database.

  • Autonomous Cognitive Loop: Background worker (m3_cognitive_loop.py) that periodically sweeps chat logs to extract facts, reconcile contradictions, and construct an entity relationship graph.

  • LLM-Based Entity Extraction & Relationship Enrichment: m3 includes LLM-based entity extraction and relationship enrichment (Observer + Reflector), running as background cognitive passes over raw text — automatic once a local or cloud LLM endpoint is configured. The Observer pass reads unstructured text and emits entities, facts and typed relationships; the Reflector pass re-reads what is already stored, resolves contradictions and writes supersedes edges. Both run off the hot path, so a write stays fast while the understanding of it deepens afterwards. Any OpenAI-compatible endpoint works — point it at a local server (LM Studio, Ollama, llama.cpp — auto-probed on :1234 / :11434) to keep every token on your machine, or at a cloud model if you prefer. (See Enrichment Guide)

  • Hybrid Vector & Keyword Search: Seamlessly merges vector space, Full-Text Search (FTS5 BM25), and MMR diversity.

  • Hierarchical File Ingestion: A dedicated 26-tool files domain reads directories, chunks files, extracts facts, and reviews staleness — with ~4× faster incremental re-ingest (unchanged sections reuse cached embeddings).

  • Verbatim Chatlog Capture: A dedicated 10-tool chatlog domain records conversation turns before compaction, so prior Claude/Gemini sessions stay searchable and nothing is lost to context-window truncation.

  • Pluggable Storage Backend: SQLite by default; select PostgreSQL as a first-class primary store with M3_DB_BACKEND=postgres. Same semantics on either backend — the choice doesn't change behavior.

  • Cross-Device Sync: Optionally sync/federate to a PostgreSQL warehouse tier. Access the same memories on your laptop, desktop, or cloud environments.

📚 Documentation Index

Start here, in this order: Getting Started → Memory Model (what a memory is, and how supersession works) → Agent Instructions (how to make your agent use it well). Everything else below is reference — reach for it when you hit the specific thing it covers.

Quick & Core

Advanced & Architecture

Integrations & Compliance

🚀 Getting Started Guide

🏗️ System Architecture

🧩 LangChain/LangGraph

✨ Core Features

🔧 Technical Implementation

🧩 Hermes Agent

⚙️ Environment Variables

🧠 Memory Model Guide

🛡️ Compliance Guide (GDPR, FISMA)

🛠️ Operations Playbook

⚡ Rust Oxidation benchmarks

🛡️ FIPS Cryptographic Boundary

🤖 Agent Instructions & Rules

🔍 Myths & Facts Guide

🏠 Homelab Patterns

🧩 Tool Capability Matrix

🤖 AI Context Injection Profile

🔢 Machine-Readable Features

More Documentation

Guide

Guide

Guide

🗺️ Roadmap

🔄 Cross-Device Sync

👥 Multi-Agent Orchestration

⚖️ Comparison vs Alternatives

❓ FAQ

🔐 Security Policy

💻 Using m3 for Coding Work

🧠 Memory Model

🧪 Myths and Facts

🩹 Troubleshooting

⌨️ CLI Reference

📖 API Reference

📁 Files Memory

💬 Chat Log Subsystem

✨ Enrichment Guide

⬆️ Upgrade Guide

🩺 Health FAQ

🧬 Dual Embedding

📜 Changelog

🤝 Code of Conduct

🏗️ Build Wheels

📊 Web Dashboard

🧰 Underlying Tools

🐘 PostgreSQL Sync

⚡ Performance

🎯 Who This Is For

m3 is a great fit if...

  • You run a homelab or self-hosted stack: m3 is a single pip install with no account, no API key, and no outbound calls — it runs on the hardware you already own, alongside your other self-hosted services. SQLite by default (zero infrastructure); PostgreSQL when you want a shared store across machines.

  • You operate under sovereignty or data-residency requirements — corporate, government, defence, healthcare, or any regulated environment: memory and embeddings never leave your boundary. The embedder runs on your own hardware, the store is a file you control, and installation works fully air-gapped from pre-compiled wheels. FIPS 140-3-ready crypto (M3_FIPS_MODE=1), GDPR gdpr_forget / gdpr_export, audit logs, and relocatable storage roots so databases and configuration can be secured independently.

  • You want the freedom to switch or add agents without losing what they know: change tools on the fly or down the road — Claude Code, Gemini, OpenClaw, Hermes, whatever comes next — and your project's knowledge carries over instead of disappearing with the switch.

  • You build with LangChain/LangGraph: An advanced replacement for standard memory models, adding bitemporal queries, contradiction management, and local embeddings.

  • You build with CrewAI (v1.10–1.x): A drop-in StorageBackend (Memory(storage=M3StorageBackend(user_id="crew-alpha"))) that gives CrewAI bitemporal recall, contradiction-aware supersession, and local embeddings — plus the thing single-vector stores can't do: a CrewAI-written memory can also be searchable by every other m3 agent (Claude Code, Gemini, LangChain) if you want. pip install m3-memory[crewai]. See the CrewAI integration guide.

  • You build with PydanticAI: m3-backed memory as either drop-in tools + auto-recall (register_m3_tools, m3_recall_processor) or a formal M3MemoryToolset (a real PydanticAI AbstractToolset). Built on Pydantic v2, so it runs on Python 3.14 with a plain pip install m3-memory[pydantic-ai]. See the PydanticAI integration guide.

  • You need security and compliance: Built-in gdpr_forget and gdpr_export tools, air-gapped support, and audit logs.

  • You value privacy: Zero external cloud requests or subscriptions required.

m3 is NOT a fit if...

  • You need a hosted SaaS dashboard with managed infrastructure (use Letta).

  • You don't want persistent memory: you want each session to start fresh, with no ability to retrieve prior sessions' knowledge — m3 exists to do the opposite, so your agent's built-in defaults are the simpler fit.

🛡️ Why Trust This

  • Benchmarked Retrieval: State-of-the-art for a local-first substrate — 99.2% session-hit-rate @ k=10, 100% @ k=20 on LongMemEval-S — with a published, reproducible methodology and no oracle routing. See Benchmarks.

  • Robust Coverage: Over 3,600 tests guarding that your memories survive upgrades and schema migrations, that capture never silently stops, and that behavior is identical on SQLite and PostgreSQL. Every release runs the full suite on every lane — Linux, macOS and Windows × every supported Python version, each lane independent of the others. No subsets, no shortcuts. Warnings are treated as errors: a release does not pass until every warning is addressed, not just every failure.

  • Measured, Not Asserted: Latency for the write, search, sync and embed paths is published with its method, its hardware, and its limits — including what the numbers look like without a GPU (~7× slower on embedding). See Performance.

  • Audit Reports: Regular vulnerability reports (Bandit, secrets scans, pip-audit) published directly under docs/audits/.

  • Explainable Retrieval: No black-box queries; retrieval math is open, readable, and scoring parameters are outputted directly.

  • Open Source: Apache 2.0 licensed, free, with no SaaS walls or usage limits.

📊 Benchmarks

Read retrieval accuracy first — it is the only number that measures the memory layer.

Session Hit-Rate (SHR) asks one question: did the system surface the evidence that answers the query? No answer model is involved, so the score reflects the memory layer and nothing else. It is the like-for-like metric across memory systems.

End-to-end QA accuracy runs that retrieved context through an LLM and has a judge model grade the answer. Both choices move the score independently of retrieval: a stronger answerer lifts a weaker memory layer, a lenient judge lifts everyone, and neither is held constant across published comparisons. Two systems quoting QA numbers are usually not measuring the same thing.

Both are reported below. SHR is the headline; QA is context.

Retrieval Accuracy — Session Hit-Rate @ k (the memory-layer metric)

Evaluated on the 500-question LongMemEval-S dataset under default server configurations:

Retrieve Depth (k)

Session Hit-Rate (SHR) ⁂

Success Count

vs. Prior Version

1

91.8%

459 / 500

First Report †

5

98.2%

491 / 500

+2.0pp

10 (Default)

99.2%

496 / 500

+2.4pp

20

100.0%

500 / 500

First Report ‡

† SHR@1 is the strictest cut — a gold session as the single top-ranked result. m3 operates at k=10 (its default), where a gold session is present for 99.2% of questions; k=1 is reported here for completeness, not as the headline. Cross-system SHR/recall figures are usually quoted at k=5, k=10, k=20, or k=50, so comparing another system's k=10+ number against this k=1 figure is not a like-for-like comparison.

⁂ Which aggregation. These are binary per-question recall_any@k values — the convention adjacent LongMemEval submissions report. The benchmarking report's per-question-type table aggregates slightly differently and reads marginally higher at shallow depth (98.8% at k=5, 99.4% at k=10); k=20 is 100.0% either way. The table above quotes the more conservative figures.

‡ v3 improvement — the v3 engine reaches 100% SHR at k=20, exceeding the prior version's 97.8% measured at the deeper k=30 (LongMemEval issue #43) — higher recall at shallower depth. Both figures are retrieval-only SHR (no answerer). The "vs. Prior Version" deltas at k=5/k=10 compare v3 against the prior version's 96.2% / 96.8% at the same k.

End-to-End QA Accuracy (answer-model and judge dependent — not a memory-layer comparison)

92.0% accuracy (460/500 correct responses) with zero oracle metadata routing. Reported for completeness; see the note above on why this number is not comparable across systems the way SHR is:

Question Domain

Count (n)

Accuracy

single-session-user

70

94.3%

single-session-assistant

56

96.4%

single-session-preference

30

80.0%

multi-session

133

87.2%

temporal-reasoning

133

95.5%

knowledge-update

78

93.6%

Overall Summary

500

92.0%

Methodology and reproducibility details are located in the LongMemEval-S Benchmarking Report.

🧰 Core Tools

While m3 features 100+ tools, these five serve as your primary interface:

Tool Name

Operation Description

memory_write

Save a specific fact, project preference, or technical configuration.

memory_search

Run hybrid keyword (BM25) and semantic vector search.

memory_update

Edit existing facts to keep memory accurate.

memory_suggest

Query memories alongside a mathematically explicit score breakdown.

memory_get

Fetch details of a single memory using its unique ID.

Refer to the Agent Instructions Guide and Full MCP Tool Catalog for complete parameter definitions.

🤖 For AI Agents

You can drop the agent ruleset file examples/AGENT_RULES.md into your workspace to teach your agent best practices (e.g., query before writing, update existing records instead of duplicating).

Command Installation Prompts

Copy and paste these prompts into your terminal client to let your agent set up m3 for you:

Claude Code Prompt

Install m3-memory for persistent memory. Run: pip install m3-memory
Then run: m3 setup
That wires the m3 "memory" MCP server into my agents and provisions the
local BGE-M3 embedder — no external embedding service is needed. If it
doesn't detect Claude Code, add {"mcpServers":{"memory":{"command":"m3"}}}
to my ~/.claude/settings.json under "mcpServers". Then use /mcp to verify
the memory server loaded.

Gemini CLI Prompt

Install m3-memory for persistent memory. Run: pip install m3-memory
Then run: m3 setup
That wires the m3 "memory" MCP server into my agents and provisions the
local BGE-M3 embedder — no external embedding service is needed. If it
doesn't detect Gemini CLI, add {"mcpServers":{"memory":{"command":"m3"}}}
to my ~/.gemini/settings.json under "mcpServers".

Active Chatlog Capture Plugin

To configure instant conversation logging and backup, tell your active coding agent:

Install the m3-memory chat log subsystem.

The agent executes bin/chatlog_init.py and configures execution triggers (see Chat Log Architecture Guide).

🎬 See it in action

Contradiction Detection & Automatic Resolution

Hybrid Search Scoring Details

Multi-Device Database Sync

💬 Community

Discord Badge &nbsp; GitHub Issues Badge

How to Contribute · FAQ for Developers · Good First Issues

📜 License & Attributions

This project is licensed under the Apache License 2.0. See LICENSE for details.

Built with

m3 Memory is authored and maintained by skynetCMD. It was built with the help of AI coding assistants — Gemini CLI, Claude Code, and Google Antigravity — which contributed code under the author's direction. (They are tools that assisted; they are not maintainers, sponsors, or co-owners of the project.)

Asset & Icon Credits

The provider badges under docs/badges/ embed small logo glyphs:

  • OpenClaw & OpenCode icons are from the MIT-licensed LobeHub icon set (lobe-icons).

  • The Hermes badge uses a generic caduceus glyph.

See NOTICE for the full third-party attribution list.

⭐ Star History

Chart regenerated on a schedule by .github/workflows/star-history.yml using the repo's own token — no third-party embed. Click through for the live interactive version.

Available Tools

20 tools
agent_listB

List registered agents, optionally filtered by status and/or role.

ParametersJSON Schema
NameRequiredDescriptionDefault
roleNo
statusNo
timeoutNo
databaseNo
as_recordsNo

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only says 'List,' which implies a read operation, but it does not disclose whether the operation is read-only, expensive, requires authentication, or has side effects. For a tool with no annotation coverage, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that immediately states the primary action and the optional filters. There is no fluff or redundant information, and the core purpose is front-loaded. It earns a perfect score for efficiency and clarity of structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 5 parameters, no output schema, and no annotations, the description is severely under-specified. It does not explain return format, behavior of the extra parameters, or any edge cases. An agent would have to rely on the schema alone, which lacks descriptions, leaving many unknowns. The description is not complete enough for reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for all 5 parameters. It explicitly explains 'status' and 'role' as filters, but leaves 'timeout', 'database', and 'as_records' completely unexplained. The description adds minimal value beyond what the schema already provides for those two parameters, and fails to cover the majority.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('List') and resource ('registered agents'), making the core purpose clear. It also mentions optional filters for status and role, which adds specificity. However, it does not distinguish this tool from siblings like tools_list_domains or task_list, though the resource name is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving agents and mentions optional filters, giving some context on when to apply them. But it provides no explicit guidance on when not to use this tool or alternatives. Since there are no obvious competing listing tools among siblings, the lack of exclusion is a minor gap, but no when-to-use vs. alternatives is stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

chatlog_statusB

One-call health summary of the chat log subsystem: mode, DB paths, row counts, queue depth, spill files, embed backlog, hook timestamps, redaction state, warnings.

ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNo
databaseNo

TDQS

B3.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden. It states what is returned but does not clarify if the tool is read-only, requires permissions, or has side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the core purpose, though it lists many items which reduces readability slightly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description lists the summary contents but fails to describe parameter behavior or return format, which is insufficient for a health tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the description does not mention the timeout or database parameters at all, leaving the agent to infer their meaning from the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides a health summary of the chat log subsystem and lists specific metrics included. However, it does not explicitly differentiate from sibling health tools like files_health.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for checking chat log health but provides no guidance on when to use this tool vs alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

chatlog_writeB

Append one chat turn to the chat log DB. Provenance (host_agent, provider, model_id, conversation_id) is required. Writes are async-queued — returns the row id immediately.

ParametersJSON Schema
NameRequiredDescriptionDefault
roleYes
contentYes
timeoutNo
user_idNo
agent_idNo
cost_usdNo
databaseNo
metadataNo{}
model_idYes
providerYes
tokens_inNo
host_agentYes
latency_msNo
tokens_outNo
turn_indexNo
conversation_idYes

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that writes are async-queued and returns the row id immediately, but lacks further behavioral details (e.g., error handling, idempotency, rate limits). With no annotations, the description carries the burden but is only partially transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action and resource. No wasted words; every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 16 parameters and no output schema or annotations, the description is insufficient. It does not describe key parameters like role, content, or optional fields, and provides minimal return value information beyond 'row id'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must add meaning. It only names required provenance fields (host_agent, provider, model_id, conversation_id) but does not explain other required or optional parameters, leaving many parameters undefined.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('append') and resource ('chat log DB'), with a specific verb-object pair. It distinguishes itself from sibling tools like chatlog_search and chatlog_status by being a write operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool over alternatives or when not to use it. The description only states what it does, not the context or prerequisites for use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

files_corpus_listC

Enumerate corpora with row counts.

ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNo
databaseNo

TDQS

C2.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must convey behavioral traits. It only says 'Enumerate corpora with row counts,' lacking disclosure on whether it is read-only, whether authentication is needed, or any side effects. This is insufficient for safe agent usage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

At 4 words, the description is too short to be useful. While concise, it sacrifices necessary detail; it does not earn its place as it fails to inform adequately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (listing corpora with counts), the description covers the basic output. However, it omits context about what 'corpora' are, which database is used, and how results are structured, making it only minimally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description should compensate by explaining the parameters. It does not mention 'timeout' or 'database' at all, leaving agents without context for these fields beyond the schema defaults.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states 'Enumerate corpora with row counts,' which gives a basic verb and resource but fails to specify what 'corpora' refers to in context. It does not clearly distinguish from sibling tools like files_stats or files_search, leaving ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, typical use cases, or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

files_getA

Fetch one record by UUID. Tries file_nodes then leaves.

ParametersJSON Schema
NameRequiredDescriptionDefault
uuidYes
timeoutNo
databaseNo

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the lookup strategy (file_nodes then leaves), which is a key behavioral trait, but omits details on error handling, return format, or idempotency, especially important since no annotations exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise at one sentence, front-loading the core action and key behavioral detail without superfluous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and three parameters, the description is too minimal—it lacks info on return values, error states, parameter constraints, and practical usage context, leaving the agent underinformed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description only semantically enriches the required 'uuid' parameter by indicating it identifies the record; the 'timeout' and 'database' parameters are entirely unspecified.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches one record by UUID and specifies the lookup order across file_nodes and leaves, distinguishing it from sibling tools like files_search which search or files_index which index.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for fetching a single record by UUID but does not explicitly guide when to use this tool over alternatives like files_search or when the fallback behavior matters.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

files_healthC

DB integrity + FTS5 sync check. Set rebuild=True to fix drift.

ParametersJSON Schema
NameRequiredDescriptionDefault
rebuildNo
timeoutNo
databaseNo

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behaviors. It mentions a check and a rebuild action, but does not describe potential side effects (e.g., time consumption, data modification during rebuild), failure modes, or the effect of timeout and database parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with one sentence, which is efficient, but it omits essential information about parameters and usage, making it under-specified rather than effectively concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and annotations, the description is insufficient. It does not explain return values, how rebuild works, the effect of database selection, or timeout behavior. It fails to provide a complete understanding of the tool's capabilities and constraints.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must explain all parameters. Only 'rebuild' is mentioned. 'timeout' and 'database' have no description, leaving their purpose and acceptable values unclear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it performs a DB integrity and FTS5 sync check, and mentions the rebuild capability. It distinguishes itself from sibling tools like files_search and files_index by focusing on health rather than data retrieval or indexing, though it does not explicitly contrast them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool over alternatives, or any prerequisites or conditions. The description implies using rebuild to fix drift but does not explain when that is appropriate or what the default behavior is.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

files_indexA

Return file-level summaries for triage (wiki-index primitive). Cheap-first retrieval -- no leaf content. Use BEFORE files_search to decide which files are worth deep-reading.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
corpusNo
corporaNo
timeoutNo
databaseNo
filetypeNo
directoryNo
filename_globNo
include_historyNo

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description notes 'no leaf content' and 'cheap-first retrieval', indicating the tool returns summaries only and is low cost. Since no annotations are provided, the description carries the full burden; it does not contradict any annotations. However, it omits details about rate limits, authentication, or side effects, though these are not critical for a read-only index tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three short sentences that are front-loaded with the core purpose and usage recommendation. Every sentence adds value, with no redundancy or unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 9 parameters and no output schema, the description is minimalist. It captures the high-level intent but lacks details on output format, parameter usage, and behavioral boundaries. It is adequate for a simple index tool but incomplete for fully autonomous use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 9 parameters and zero schema description coverage, the description provides no explanation of parameters like limit, corpus, corpora, database, filetype, etc. This is a significant gap, as the agent would need to infer parameter meanings from names alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns file-level summaries for triage as a cheap-first retrieval primitive, distinguishing it from file_search and file_get. It explicitly says 'Use BEFORE files_search to decide which files are worth deep-reading', differentiating among sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit guidance on when to use: 'Use BEFORE files_search to decide which files are worth deep-reading'. It also characterizes the tool as 'cheap-first retrieval', implying it should be used before more expensive operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

files_statsC

Corpus-level counters: file_nodes, leaves, embed coverage, by-filetype.

ParametersJSON Schema
NameRequiredDescriptionDefault
corpusNo
timeoutNo
databaseNo

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It does not disclose whether the tool is read-only, destructive, requires authentication, or has any limitations. Only the output type is hinted but not detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise (one phrase) but lacks structure and completeness. While it has no wasted words, it is too minimal to be fully useful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description should provide more context about what the counters represent, how to use parameters, and expected behavior. It only gives a high-level list of outputs, leaving significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the tool description does not explain any of the parameters (corpus, timeout, database). The description adds no meaning beyond the bare schema names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool provides corpus-level counters such as file_nodes, leaves, embed coverage, and by-filetype. This specific verb and resource combination distinguishes it from sibling tools like files_health (health check) or files_search (search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description does not mention prerequisites, context, or when not to use it. Usage is only implied by its purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

m3_callA

Invoke ANY m3 catalog tool by name without loading its domain — the low-token path to the full tool surface. Single call: pass tool (e.g. 'files_stats') and args (an object). Batch: pass batch, a list of {tool, args} (each isolated — one failure won't abort the rest; capped at 100). Set dry_run to validate args + check the destructive gate WITHOUT executing. Returns JSON. Call m3_index first if you don't know a tool's args. Destructive tools require MCP_PROXY_ALLOW_DESTRUCTIVE=1.

ParametersJSON Schema
NameRequiredDescriptionDefault
argsNo
toolNo
batchNo
dry_runNo
timeoutNo
databaseNo

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description fully discloses batch isolation, cap at 100, dry_run validation, destructive gate requirement, and JSON return. This is comprehensive behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is well-structured and front-loaded with purpose. Every sentence adds value, though could be slightly tighter for the batch and dry_run explanations.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given tool complexity and no output schema, description covers invocation modes, error isolation, and destructive gate. Could expand on error handling or response format, but sufficient for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, description explains tool, args, batch, and dry_run but omits timeout and database parameters. Provides meaningful context for key parameters but not complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool invokes any m3 catalog tool by name without loading its domain. It distinguishes itself from siblings like m3_index by advising to call it first if args are unknown.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides guidance on when to use m3_index for unknown args, batch vs single call, and dry_run behavior. Missing explicit when-not-to-use scenarios but sufficiently covers common use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

m3_help_capabilitiesB

Discover m3-memory tool capabilities, parameters, and availability. Allows filtering by a logical domain (memory, chatlog, files, entity, agent, tasks, conversations, admin, diagnostics) or searching by keywords.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNo
domainNo
timeoutNo
databaseNo
as_recordsNo

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It doesn't mention any side effects, whether it's a read-only operation, any required authentication, or what happens when no filters are applied. It doesn't describe the output format or any limitations. Given the lack of annotations, this is a significant gap. However, it doesn't contradict any annotations since none exist.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with two sentences. It front-loads the primary purpose (discover capabilities) and then adds filtering options. Every sentence earns its place. The only minor issue is that it could be more explicit about the parameters, but overall it's well-structured and succinct.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 5 parameters but zero schema coverage and no output schema, the description is incomplete. It explains the high-level purpose but leaves out critical details like how to use 'query' and 'domain' together, what 'database' refers to, and what 'as_records' does. For a discovery tool that an agent might use to understand other tools, this is a moderate gap. The complexity is moderate, but the description could do more to fill the schema void.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning the schema provides no descriptions for the parameters. The description mentions 'query' and 'domain' indirectly (filtering by domain or keywords) and implies 'as_records' might affect output, but it doesn't explain 'timeout', 'database', or the exact format for 'query' and 'domain'. This leaves the agent with significant ambiguity, especially for a tool with 5 parameters and zero schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to discover m3-memory tool capabilities, parameters, and availability. It specifies the resource (m3-memory tools) and the actions (discover, filter). It distinguishes itself by mentioning filtering by domain or keyword search, which differentiates it from siblings like tools_list_domains or memory_search. However, it doesn't explicitly distinguish from all siblings, so it's not a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: it's for discovering tool capabilities and availability, with options to filter by domain or search by keywords. It implies when to use this tool (when needing to understand m3-memory tools), but does not explicitly state when not to use it or mention alternatives. Since it's a metadata/discovery tool, the context is clear enough, but lacks explicit exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

m3_indexA

List m3 catalog tools (optionally one domain) as structured rows: name, domain, one-line summary, destructive flag, and arg specs (name/type/required). Use this to discover the exact args for any tool before calling it via m3_call — cheaper than a failed call. Read-only catalog metadata; never returns tool output. Domains: memory, chatlog, files, entity, agent, tasks, conversations, diagnostics, admin.

ParametersJSON Schema
NameRequiredDescriptionDefault
domainNo
timeoutNo
databaseNo

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It states 'Read-only catalog metadata; never returns tool output', clearly indicating safety and no side effects. This is sufficient for a catalog tool, though it lacks details on rate limits or auth, which are less critical here.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at 4 sentences, each serving a clear purpose: stating output, providing usage advice, declaring read-only behavior, and listing domains. It is front-loaded with the core function and highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and 0% schema description coverage, the description is mostly adequate but misses details on the timeout and database parameters. It covers purpose, usage, behavior, and domains well, but the parameter gap reduces completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must explain all parameters. It partially explains the domain parameter with 'optionally one domain', but completely omits the timeout and database parameters, leaving them unexplained. This is a significant gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'List m3 catalog tools (optionally one domain) as structured rows'. It specifies the output fields and distinguishes itself from the sibling m3_call by advising to use this tool before calling m3_call.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'Use this to discover the exact args for any tool before calling it via m3_call — cheaper than a failed call'. It also lists the available domains for filtering. However, it does not specify when not to use it or mention alternatives beyond m3_call.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_getA

Retrieves a full MemoryItem; accepts full UUID or 8-char prefix; ambiguous prefixes return an error.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYes
timeoutNo
databaseNo

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses error behavior for ambiguous prefixes, which adds value beyond a simple 'retrieve'. However, no annotations exist, so the description carries full burden, but it omits details like idempotency or side effects, though implied by 'get'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no filler, all essential information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 3 parameters and no output schema, the description is incomplete: it fails to explain 'timeout' and 'database' parameters, and does not describe the return value structure beyond 'full MemoryItem'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must compensate. Only the 'id' parameter is partially described (accepts UUID or prefix), while 'timeout' and 'database' are entirely unmentioned.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it retrieves a full MemoryItem by full UUID or 8-char prefix, distinguishing it from sibling tools like memory_search and memory_write.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explains the acceptable ID formats and error on ambiguous prefixes, but does not explicitly mention when not to use or provide alternatives like memory_search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_supersedeA

Explicitly supersede an existing memory with a new one. Use this to record an intentional update — 'this fact replaces that specific memory' — when you know the old memory's id. Unlike memory_write's automatic contradiction detection (a cosine + title heuristic that may link the wrong prior memory or none at all), this targets the given old_id deterministically. Non-destructive: the old memory is retained, its validity interval is closed (is_deleted=1, valid_to set), and a 'supersedes' edge is recorded new -> old. The old memory stays retrievable by id and via memory_history, and as_of-filtered search still sees it valid before the supersession point — it is only dropped from default search. Fields you omit (type, title, importance, scope) are inherited from the old memory, so pass only what changed. To hard-delete instead, that is a separate gated tool (memory_delete). old_id MUST be the full UUID — a prefix is rejected (full UUID required for mutation safety; memory_get accepts a prefix, this does not). Note: each supersede creates a NEW successor memory; call it once with the full id, do not chain supersedes.

ParametersJSON Schema
NameRequiredDescriptionDefault
typeNo
embedNo
scopeNo
titleNo
old_idYes
sourceNoagent
contentYes
timeoutNo
user_idNo
variantNo
agent_idNo
databaseNo
metadataNo{}
model_idNo
embed_textNo
importanceNo
valid_fromNo
change_agentNo

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description bears full burden. It discloses key behaviors: non-destructive operation, retention of old memory, closure of validity interval, recording of 'supersedes' edge, inheritance of omitted fields, requirement for full UUID, and prohibition of chaining. However, it does not explain the many other parameters (e.g., embed, timeout, user_id, etc.) and their effects, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is detailed but somewhat lengthy, covering multiple aspects. It is front-loaded with purpose and usage, then behavioral details and parameter notes. While informative, it could be more concise by reducing redundancy (e.g., repeating 'non-destructive' and 'full UUID' points). Still, it is well-structured and readable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (18 parameters, no output schema, no annotations), the description explains the core functionality well but leaves many parameters (embed, timeout, source, etc.) unexplained. An agent may struggle to use these parameters correctly without additional information. The description is incomplete for fully autonomous use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains only a few parameters: old_id (full UUID required), content (required), and mentions type, title, importance, scope as inheritable. The other 13 parameters (embed, source, timeout, user_id, etc.) are not described, leaving the agent without guidance for their purpose or usage. This is insufficient for a schema with 18 parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: to explicitly supersede an existing memory with a new one. It contrasts with memory_write's automatic detection, provides specifics on the operation (non-destructive, validity interval closed, supersedes edge), and distinguishes from a hard-delete tool. This is specific and helps differentiate from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly explains when to use this tool: when the old memory's ID is known and an intentional update is needed. It contrasts with memory_write's automatic detection, advising against using this tool when that automatic linking is sufficient. It also warns not to chain supersedes. This provides clear guidance on usage vs. alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memory_writeA

Creates a MemoryItem and optionally embeds it for semantic search. Contradiction detection is automatic — if new content conflicts with an existing memory of the same type/title, the old one is superseded. Use type='auto' to let the LLM decide the best category.

ParametersJSON Schema
NameRequiredDescriptionDefault
typeYes
embedNo
scopeNoagent
titleNo
sourceNoagent
contentYes
timeoutNo
user_idNo
variantNo
agent_idNo
databaseNo
metadataNo{}
model_idNo
valid_toNo
embed_textNo
importanceNo
refresh_onNo
valid_fromNo
change_agentNo
auto_classifyNo
refresh_reasonNo
conversation_idNo

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description carries full burden. It discloses automatic contradiction detection and superseding behavior, but does not detail side effects or return values for the 22 parameters.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences efficiently convey the primary purpose and a key usage hint. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (22 parameters, no output schema, no annotations), the description is too brief. It fails to cover optional parameters and their effects, making it incomplete for reliable agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%. The description only explains 'type' and 'content' implicitly; the other 20 parameters (e.g., scope, metadata, importance) are undocumented, leaving the agent uninformed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Creates a MemoryItem' with specific verb and resource. It distinguishes from siblings like memory_search and memory_get by indicating creation and embedding for semantic search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description suggests using type='auto' but does not explicitly guide when to use this tool versus alternatives like memory_supersede. Usage context is implied rather than stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

task_listC

List tasks with optional filters. Newest updated first.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
stateNo
timeoutNo
databaseNo
as_recordsNo
owner_agentNo
parent_task_idNo

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full responsibility for disclosing behavior. It does state 'Newest updated first', which is a useful behavioral detail, but it omits critical aspects like whether the operation is read-only, any side effects, permission requirements, or what happens with filter combinations. For a list operation, the description gives minimal transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise, consisting of a single sentence with no fluff. The primary verb and resource are front-loaded. However, the structure is minimal and does not provide any breakdown of filters or usage context, which is acceptable given its brevity but could be improved with a second sentence explaining the filter options.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 7 parameters, no output schema, and no annotations. The description is severely incomplete: it does not explain what the output looks like, how filters interact, what each parameter means, or when to use this tool over siblings. An agent would be left guessing about the semantics of the parameters and the expected result format, making the description insufficient for effective tool selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% – the schema provides no descriptions for the 7 parameters. The description only says 'optional filters' without explaining any of the parameters (limit, state, timeout, database, as_records, owner_agent, parent_task_id). This is a critical gap; the description must compensate but fails to provide any semantic meaning for the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: 'List tasks' with optional filters. It is not a tautology and distinguishes itself from siblings like agent_list or memory_get by focusing on tasks. However, it does not explicitly differentiate itself from other list-type tools or clarify the scope of 'tasks', so it is slightly below a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions 'optional filters' but provides no guidance on when to use this tool versus alternatives such as agent_list or memory_get. There are no explicit exclusions or contextual cues. The only implied usage is that it is for tasks, but no reasoning or selection criteria are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tools_list_domainsA

List m3 tool domains (memory, chatlog, files, entity, agent, tasks, conversations, diagnostics, admin) and their tool counts. Call tools_load_domain to expose a domain's full tool surface.

ParametersJSON Schema
NameRequiredDescriptionDefault
timeoutNo
databaseNo

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries the full burden. It implies a read-only list operation but does not explicitly state safety, side effects, or permission requirements. Adequate for a simple read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with purpose. No wasted words; each sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a straightforward list tool with no output schema and simple optional parameters, the description provides the needed domain names and links to the follow-up tool. It does not detail output format or parameter usage, but given the simplicity, it is fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description does not mention or explain any of the two parameters (timeout, database). It adds no meaning beyond the schema, which is insufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool lists m3 tool domains and their tool counts, providing specific domain names. It also distinguishes the sibling 'tools_load_domain' by explaining what that tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context for when to use this tool (to list domains with counts) and points to an alternative (tools_load_domain) for exposing full tool surface. However, it does not explicitly state when not to use it or list other alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

tools_load_domainC

Register a tool domain's full surface for the current MCP session. Use when you need tools beyond the essentials (memory_search, memory_write, memory_get, chatlog_search, chatlog_write, files_search). Valid domains: memory, chatlog, files, entity, agent, tasks, conversations, diagnostics, admin.

ParametersJSON Schema
NameRequiredDescriptionDefault
domainYes
timeoutNo
databaseNo

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must fully disclose behavioral traits. It does not mention side effects, permissions, session-level impact, or whether loading is additive vs. replacement. Only states 'for the current MCP session' but no further details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences are concise and front-loaded with purpose, but missing parameter info and behavioral details means it is incomplete rather than efficiently written. Could be restructured to include parameter hints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 3 parameters, no output schema, and no annotations, the description should fully explain usage. It does not mention parameters, return values, or implications of loading a domain. Incomplete for effective tool invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and description adds no information about any of the three parameters (domain, timeout, database). The required 'domain' parameter is not mentioned, making it impossible for an agent to understand how to invoke correctly from description alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool registers a tool domain's full surface, and the use case distinguishes it from siblings like tools_list_domains. The verb 'register' and noun 'tool domain' are specific, though 'full surface' is slightly jargon.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use when you need tools beyond the essentials' and lists those essentials, providing clear context. Lacks explicit when-not-to-use or alternatives but adequate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.20
    • Changedagent_list1 field changed
      • addedInput schema / properties / as_records
        Added value: +{
+  "default": false,
+  "title": "As Records",
+  "type": "boolean"
+}
    • Changedm3_help_capabilities1 field changed
      • addedInput schema / properties / as_records
        Added value: +{
+  "default": false,
+  "title": "As Records",
+  "type": "boolean"
+}
    • Changedmemory_search1 field changed
      • addedInput schema / properties / as_records
        Added value: +{
+  "default": false,
+  "title": "As Records",
+  "type": "boolean"
+}
    • Changedtask_list1 field changed
      • addedInput schema / properties / as_records
        Added value: +{
+  "default": false,
+  "title": "As Records",
+  "type": "boolean"
+}
  2. 20 tool updatesv0.1.9
    • Addedagent_list
    • Addedchatlog_search
    • Addedchatlog_status
    • Addedchatlog_write
    • Addedfiles_corpus_list
    • Addedfiles_get
    • Addedfiles_health
    • Addedfiles_index
    • Addedfiles_search
    • Addedfiles_stats
    • Addedm3_call
    • Addedm3_help_capabilities
    • Addedm3_index
    • Addedmemory_get
    • Addedmemory_search
    • Addedmemory_supersede
    • Addedmemory_write
    • Addedtask_list
    • Addedtools_list_domains
    • Addedtools_load_domain
  3. 11 tool updatesv0.1.7
    • Removedagent_list
    • Removedfiles_corpus_list
    • Removedfiles_get
    • Removedfiles_health
    • Removedfiles_index
    • Removedfiles_stats
    • Removedmemory_search
    • Removedmemory_supersede
    • Removedmemory_write
    • Removedtask_list
    • Removedtools_list_domains
  4. 9 tool updatesv0.1.6
    • Removedchatlog_search
    • Removedchatlog_status
    • Removedchatlog_write
    • Removedfiles_search
    • Removedm3_call
    • Removedm3_help_capabilities
    • Removedm3_index
    • Removedmemory_get
    • Removedtools_load_domain
  5. 20 tool updatesv0.1.2
    • Changedagent_list1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedchatlog_search1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedchatlog_status1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedchatlog_write1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedfiles_corpus_list1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedfiles_get1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedfiles_health1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedfiles_index1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedfiles_search1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedfiles_stats1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedm3_call1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedm3_help_capabilities1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedm3_index1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedmemory_get1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedmemory_search3 fields changed
      • addedInput schema / properties / explain
        Added value: +{
+  "default": false,
+  "title": "Explain",
+  "type": "boolean"
+}
      • addedInput schema / properties / requesting_agent
        Added value: +{
+  "default": "",
+  "title": "Requesting Agent",
+  "type": "string"
+}
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedmemory_supersede1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedmemory_write1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedtask_list1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedtools_list_domains1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
    • Changedtools_load_domain1 field changed
      • addedInput schema / properties / timeout
        Added value: +{
+  "default": 30,
+  "title": "Timeout",
+  "type": "number"
+}
  6. 20 tool updatesv0.1.0
    • First observedagent_list
    • First observedchatlog_search
    • First observedchatlog_status
    • First observedchatlog_write
    • First observedfiles_corpus_list
    • First observedfiles_get
    • First observedfiles_health
    • First observedfiles_index
    • First observedfiles_search
    • First observedfiles_stats
    • First observedm3_call
    • First observedm3_help_capabilities
    • First observedm3_index
    • First observedmemory_get
    • First observedmemory_search
    • First observedmemory_supersede
    • First observedmemory_write
    • First observedtask_list
    • First observedtools_list_domains
    • First observedtools_load_domain
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3/5.0

Scored across 20 tools

Disambiguation2/5

Several meta-tools (tools_list_domains, m3_help_capabilities, m3_index, tools_load_domain, and m3_call) all occupy the discovery/loading/calling space, making their boundaries unclear at a glance. While the core memory/chatlog/files tools are mostly distinct, an agent could easily pick the wrong meta-tool for a given task.

Naming Consistency4/5

The vast majority of tools follow a consistent `{domain}_{action}` snake_case pattern, e.g. memory_get, chatlog_write, files_search, task_list. The m3_* and tools_* meta-tools deviate slightly but still use lowercase underscore naming and are readable.

Tool Count3/5

At 20 tools, the set sits in the 16-25 range that feels heavy, especially with five meta-tools that could be consolidated. However, the multi-domain scope (memory, chatlog, files, agents, tasks, admin, etc.) provides some justification for the count.

Completeness4/5

Core memory workflows are well covered with get, search, write, and supersede, and chatlog/files have solid read/search/status surfaces. Minor gaps remain, such as no direct memory_delete or explicit entity/conversation/admin tools, though the m3_index/m3_call meta-layer can reach those catalog tools if needed.

Maintenance

ActivityActive
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Smriti

    moltizmo
    A
    license
    Not graded
    quality
    D
    maintenance
    Local-first persistent memory for AI agents via MCP, enabling semantic search and memory sharing across agents with zero cloud cost and full privacy.
    12 npm
    1
    MIT

  • memento

    UmoLab
    A
    license
    Not graded
    quality
    A
    maintenance
    Provides persistent memory for AI coding agents via MCP, enabling agents to store and semantically recall facts, events, and lessons across sessions, all running locally without cloud dependencies.
    Apache 2.0

  • Cortex

    ryanfrigo
    A
    license
    Not graded
    quality
    D
    maintenance
    Local-first AI memory layer with hybrid retrieval and brain-inspired namespaces. Enables agents to save, search, and manage memories directly via MCP tools.
    3 npm
    MIT

  • rmbr

    SRock44
    A
    license
    A
    quality
    A
    maintenance
    Embedded memory and retrieval engine for AI agents, providing local-first memory with MCP support for multi-agent access control.
    3
    2
    MIT