feat(plugin): MemMesh Claude Code plugin + 23 agent skills

.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "name": "memmesh-plugins",
+  "owner": {
+    "name": "ThinkFleet",
+    "email": "support@memmesh.ai"
+  },
+  "metadata": {
+    "description": "Official MemMesh plugins for Claude Code and other agents"
+  },
+  "plugins": [
+    {
+      "name": "memmesh",
+      "source": "./integrations/memmesh-plugin",
+      "description": "MemMesh — a memory + calibrated-prediction + behavior-discovery engine for AI apps. Persistent hierarchical memory, a bi-temporal knowledge graph, and forward predictions with provenance and abstention. The engine decides what to save; your agent's own model does any extraction (zero engine-side LLM cost).",
+      "version": "0.1.0"
+    }
+  ]
+}

README.md

@@ -73,12 +73,24 @@ memmesh mcp
 
 ### Tools exposed over MCP
 
+Underscore names are canonical; dot names are accepted as legacy aliases.
+
 | Tool | What it does |
 |---|---|
-| `memory.save` | Upsert a memory item with scope, type, content, importance |
-| `memory.recall` | Fetch by id (reinforces the item on access) |
-| `memory.search` | Filter by scope/project/agent/user/session + content match |
-| `memory.list` | Most-recent items in a scope |
+| `memory_observe` | Feed raw text; the engine decides what to save (primary write path) |
+| `memory_save` | Upsert a memory item with scope, type, content, importance (rare) |
+| `memory_recall` | Fetch by id (reinforces the item on access) |
+| `memory_search` | Filter by scope/project/agent/user/session + content match |
+| `memory_list` | Most-recent items in a scope |
+| `memory_delete` | Forget an item — soft-reject (default, sync-safe) or hard delete |
+| `memory_supersede` | Record a correction (old item kept for provenance) |
+| `memory_stats` | Counts by type/scope/status + age span |
+| `memory_extract_pending` / `memory_commit_extraction` | Client-LLM knowledge-graph extraction |
+| `memory_graph_reason` | Multi-hop reasoning over the knowledge graph |
+| `memory_query_graph` | Point-in-time (bi-temporal) edge query |
+| `memory_prefetch_related` | Anticipatory retrieval via spreading activation |
+| `memory_build_context` | Full subject context bundle (profile + patterns + predictions) |
+| `memory_predict` | Forecast a subject's next events, calibrated + with provenance |
 
 ## Architecture
 

integrations/memmesh-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "memmesh",
+  "version": "0.1.0",
+  "description": "Persistent memory + calibrated prediction for AI agents. Remembers decisions, preferences, and patterns across sessions; predicts what a subject will do next — with provenance and honest abstention.",
+  "author": {
+    "name": "ThinkFleet",
+    "email": "support@memmesh.ai"
+  },
+  "homepage": "https://memmesh.ai",
+  "repository": "https://github.com/ThinkfleetAI/memmesh",
+  "license": "Apache-2.0",
+  "keywords": ["memory", "prediction", "personalization", "mcp", "knowledge-graph", "calibration", "semantic-search"],
+  "userConfig": {
+    "api_key": {
+      "type": "string",
+      "title": "MemMesh API Key (hosted mode only)",
+      "description": "Optional. Your MemMesh hosted API key (starts with mm-) for the Mesh Router / app.memmesh.ai. Leave blank to run fully local over SQLite — no key required.",
+      "sensitive": true,
+      "required": false
+    }
+  }
+}

integrations/memmesh-plugin/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "memmesh": {
+      "command": "memmesh",
+      "args": ["mcp"],
+      "env": {}
+    }
+  }
+}

integrations/memmesh-plugin/README.md

@@ -0,0 +1,59 @@
+# MemMesh plugin for Claude Code
+
+Persistent memory **and calibrated prediction** for your AI agent. MemMesh
+remembers decisions, preferences, and patterns across sessions, links them into a
+bi-temporal knowledge graph, and forecasts what a subject will do next — with
+provenance and honest abstention.
+
+## Install
+
+```bash
+# Add the marketplace, then install the plugin:
+/plugin marketplace add ThinkfleetAI/memmesh
+/plugin install memmesh
+
+# Or wire the MCP server + skills directly (local, no account):
+npx @thinkfleet/memmesh install
+```
+
+Local mode runs fully offline over SQLite and needs **no API key**. For hosted
+mode (cross-device sync, full SDK, server-side prediction/verticals), set
+`MEMMESH_API_KEY` — see the `memmesh-sdk` skill.
+
+## Skills in this plugin
+
+The agent invokes these by name; the MCP tools they call appear to Claude Code as
+`mcp__memmesh__memory_*`.
+
+**Everyday memory**
+- `remember` — save what the user asks to keep (observe / verbatim)
+- `forget` — delete or correct a memory (confirm first; soft vs hard)
+- `peek` — quick one-liner lookup or fetch-by-id
+- `tour` — browse everything, grouped by type
+- `stats` — counts by type/scope/status + age span
+- `context-loader` — load relevant context before a task (incl. subject bundle)
+- `dream` — consolidate duplicates/contradictions (respects pins)
+- `pin` — protect a critical memory from consolidation
+- `export` / `import` — portable backup, restore, or seed from MEMORY.md / mem0
+- `onboard` — set up MemMesh in a new project
+- `switch-project` — target another project scope or widen the search
+- `health` — diagnose connectivity + read/write round-trip
+
+**Prediction & graph (what a plain memory layer can't do)**
+- `predict` — forecast a subject's next move, calibrated + with provenance
+- `why` — explain a prediction: evidence, calibration, and abstention
+- `behaviors` — surface emergent, mined behavior patterns
+- `graph` — multi-hop reasoning + point-in-time + anticipatory retrieval
+- `benchmark` — run the LOCOMO/BEAM harness head-to-head vs Mem0 / Zep
+
+## Standalone skills (outside the plugin)
+
+For SDK/CLI reference and repo integration, see the top-level [`skills/`](../../skills):
+`memmesh-sdk`, `memmesh-cli`, `memmesh-integrate`, `memmesh-test-integration`,
+`memmesh-migrate`.
+
+## The always-on loop
+
+The bundled `memmesh` skill runs the core loop automatically: **observe** every
+user message (the engine decides what to save) and **recall** at session start.
+You don't have to trigger it.

integrations/memmesh-plugin/skills/behaviors/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: behaviors
+description: >
+  Surface emergent behavior patterns MemMesh has mined from a subject's history —
+  recurring habits nobody predefined, each with prevalence, stability, and the
+  evidence behind it. Use when the user asks "what patterns do you see", "what
+  are this user's habits", or wants the patterns that drive predictions.
+---
+
+# behaviors
+
+Show the patterns MemMesh discovered on its own. These `behavior_pattern`
+memories are what `predict` projects forward — inspecting them explains the
+forecasts.
+
+## List mined patterns (local MCP)
+```jsonc
+{ "name": "memory_search",
+  "arguments": { "type": "behavior_pattern", "projectId": "<repo>", "limit": 50 } }
+```
+Or scope to one subject and read them out of the context bundle:
+```jsonc
+{ "name": "memory_build_context",
+  "arguments": { "subjectKind": "user", "subjectId": "<id>", "include": ["patterns"] } }
+```
+
+## Discover new patterns (hosted / SDK)
+
+The discovery pass that finds patterns nobody predefined runs on the SDK:
+```ts
+const behaviors = await memory.behaviors.discover({ projectId: "myapp" });
+// each: { pattern, prevalence, stability, evidenceMemoryIds }
+```
+
+## Present them
+
+For each pattern show: the behavior, how often it holds (prevalence), how stable
+it is over time (stability), and a couple of evidence memories. Rank by
+stability × prevalence — the strongest, most reliable habits first.
+
+## Why it matters
+
+A vector-recall memory layer can only return facts you already stated. MemMesh
+*derives* structure — "books gym classes on Mondays", "reorders ~every 6 weeks" —
+from raw observations. That derived structure is the input to `predict` and the
+reason the predictions have provenance.

integrations/memmesh-plugin/skills/benchmark/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: benchmark
+description: >
+  Run MemMesh's competitive benchmark harness (LOCOMO / BEAM) to compare
+  retrieval quality, tokens, latency, and cost against Mem0, Zep, full-context,
+  and naive-RAG baselines. Use when the user wants proof MemMesh is better, is
+  evaluating a migration, or asks "how does this compare to mem0".
+---
+
+# benchmark
+
+Put numbers on the comparison. MemMesh ships a real benchmark harness that runs
+the public LOCOMO dataset end-to-end against competing systems.
+
+## What it compares
+
+Systems: `thinkfleet` (MemMesh) vs `full_context` vs `naive_rag`, and — with keys
+— Mem0 / Zep. Metrics: answer accuracy (rubric-scored), tokens consumed, latency,
+and cost per conversation.
+
+## Run it
+
+The harness lives in the engine repo at `crates/eval/competitive/`:
+```bash
+cd crates/eval/competitive
+python bench.py --systems thinkfleet,mem0,full_context --dataset locomo
+# results land in results/
+```
+(Set the competitors' API keys via env for a head-to-head; without them you still
+get MemMesh vs full-context vs naive-RAG.)
+
+## Report honestly
+
+MemMesh's positioning is **calibration over raw accuracy** — "80% means 80%" and
+honest abstention beat a slightly higher accuracy with overconfident wrong
+answers. So report the full picture:
+
+- accuracy **and** calibration error,
+- tokens / latency / cost (MemMesh's retrieval is far cheaper than full-context),
+- where MemMesh abstained vs. where a competitor answered confidently and wrong.
+
+Don't cherry-pick a single accuracy number. If a competitor wins on one axis, say
+so, and show where MemMesh's calibration/cost advantage pays off.
+
+## Cost gating
+
+Prove the win on the cheap tiers (LOCOMO, BEAM-100K) before spending on
+BEAM-1M/10M — a single 10M-token conversation is expensive. Escalate tiers only
+once the cheaper tier shows a clear, defensible lead.

integrations/memmesh-plugin/skills/context-loader/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: context-loader
+description: >
+  Load relevant MemMesh context before starting work — searches memory and, for
+  a specific subject, assembles a token-budgeted bundle (profile + behavior
+  patterns + forward predictions + top memories) in one call. Use when beginning
+  a task, switching context, or when project history / past decisions / a
+  subject's profile would help.
+---
+
+# context-loader
+
+Prime the session with the right memory before you act.
+
+## General project/session context
+```jsonc
+{ "name": "memory_search", "arguments": { "projectId": "<repo>", "limit": 20 } }
+```
+Skip only on pure pleasantries; the moment the task is substantive, load first.
+
+## A specific subject — the synthesized bundle
+
+When you're about to reason about one entity (a user, contact, account), don't
+fire five searches — get the assembled picture in one call:
+
+```jsonc
+{ "name": "memory_build_context",
+  "arguments": { "subjectKind": "user", "subjectId": "<id>", "maxTokens": 2000,
+                 "include": ["profile","patterns","predictions","memories"] } }
+```
+
+This returns the profile, active behavior patterns, **forward predictions**, and
+top memories — with provenance ids — ready to drop at the top of your prompt.
+That prediction section is the differentiator: you enter the task already knowing
+what the subject is likely to do next.
+
+## Anticipatory follow-on
+
+Once you're working with a few memories, pull what's most likely needed next via
+spreading activation over the graph:
+
+```jsonc
+{ "name": "memory_prefetch_related", "arguments": { "seedMemoryIds": ["<id1>","<id2>"], "limit": 10 } }
+```
+
+## Cite what you use
+
+When a loaded memory shapes your response, mention it briefly so the user can
+correct stale info.

integrations/memmesh-plugin/skills/dream/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: dream
+description: >
+  Consolidate MemMesh memories — find duplicates and contradictions, merge or
+  supersede them, and retire stale entries — to keep search results clean. Use
+  when memory count is high, search feels noisy/repetitive, or for periodic
+  hygiene. Respects pinned memories.
+---
+
+# dream
+
+Agent-driven consolidation. MemMesh keeps provenance, so consolidation is
+*supersede/reject*, not destructive rewrite.
+
+## 1. Survey
+```jsonc
+{ "name": "memory_stats", "arguments": { "projectId": "<repo>" } }
+```
+A high `total` or a large `superseded`/`rejected` share signals it's worth a pass.
+
+## 2. Find redundancy
+
+Pull the set (`memory_list`) or search hot topics, and identify:
+- **Duplicates** — same fact stored multiple times.
+- **Contradictions** — two memories that can't both be true.
+- **Stale** — superseded facts still cluttering results, or one-off noise.
+
+## 3. Consolidate (confirm first; never touch pinned items)
+
+- **Contradiction / changed fact** → keep the newest, `memory_supersede` the
+  older `byId` the newer. Provenance is preserved.
+- **Exact duplicate** → keep one, `memory_delete` the rest (soft).
+- **Stale noise** → `memory_delete` (soft) after confirming with the user.
+
+Do **not** delete anything marked pinned (high importance / impact HIGH /
+confirmed) — see the `pin` skill. When in doubt, supersede rather than delete.
+
+## 4. Report
+
+Summarize: N duplicates merged, M contradictions resolved, K stale retired, and
+the new total. Suggest re-running when stats drift again.
+
+> Hosted tenants can offload this to the server-side consolidator
+> (`memory.consolidate` / `dedup` in the SDK); locally, this agent-driven pass is
+> the consolidation path.

integrations/memmesh-plugin/skills/export/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: export
+description: >
+  Export MemMesh memories for a project/user to a portable Markdown (or JSONL)
+  file for backup, migration, or sharing. Use when backing up, moving to another
+  project, sharing memory state with teammates, or archiving before a cleanup.
+---
+
+# export
+
+Dump memory to a portable file.
+
+## Pull the set
+```jsonc
+{ "name": "memory_list", "arguments": { "projectId": "<repo>", "limit": 1000 } }
+```
+Page with `offset` if the store is large (check `memory_stats` for the total).
+
+## Write the file
+
+Default to Markdown grouped by `type`, one memory per bullet with its id, so it
+round-trips through the `import` skill:
+
+```markdown
+# MemMesh export — <project> — <count> items
+## preference
+- [<id>] prefers pnpm over npm  <!-- scope:user importance:6 -->
+## rule
+- [<id>] all API routes require auth middleware  <!-- scope:project impact:HIGH -->
+```
+
+For a machine-readable backup, write JSONL (one memory object per line) instead —
+preserves ids, timestamps, and status for exact restore.
+
+## Where
+
+Ask for a path, or default to `./memmesh-export-<project>-<date>.md` in the repo.
+For a full compliance-grade export of one subject (audit trail included), use the
+SDK's `compliance.exportSubject` instead.
+
+## Next
+
+To move onto another project or a teammate's machine, hand the file to `import`.
+To switch off another vendor entirely, use `memmesh-migrate`.