MemMesh — persistent, local-first memory for AI agents. Bi-temporal knowledge graph, typed/scoped recall, and local↔server sync, over MCP; runs from one binary on SQLite with no mandatory LLM calls (your agent's own model does any extraction). Calibrated prediction & behavior discovery available in hosted mode.

version
0.1.1
GitHub stars
358

Install

/plugin install memmesh@memmesh-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add ThinkfleetAI/memmesh.

Contents

Discovered from source

Skills 18

behaviors

⚙️ Requires MemMesh hosted mode. Calibrated prediction and behavior discovery run on the hosted engine — set your mm- API key. On a local / open-source install these tools (memory_predict, memory_build_context) are not registered; if a call returns "unknown tool", tell the user this is a hosted capability and fall back to search / recall for what's already known.

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)

{ "name": "memory_search",
  "arguments": { "type": "behavior_pattern", "projectId": "<repo>", "limit": 50 } }

Or scope to one subject and read them out of the context bundle:

{ "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:

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.

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/:

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.

context-loader

⚙️ Requires MemMesh hosted mode. Calibrated prediction and behavior discovery run on the hosted engine — set your mm- API key. On a local / open-source install these tools (memory_predict, memory_build_context) are not registered; if a call returns "unknown tool", tell the user this is a hosted capability and fall back to search / recall for what's already known.

Prime the session with the right memory before you act.

General project/session context

{ "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:

{ "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:

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

dream

Agent-driven consolidation. MemMesh keeps provenance, so consolidation is supersede/reject, not destructive rewrite.

1. Survey

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

export

Dump memory to a portable file.

Pull the set

{ "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:

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

forget

Remove or correct what's in memory. Always confirm before deleting.

1. Find it

{ "name": "memory_search", "arguments": { "query": "<what to forget>", "projectId": "<repo>", "limit": 10 } }

Show the matches (id + content) and ask which to remove.

2. Delete

{ "name": "memory_delete", "arguments": { "id": "<id>" } }          // soft: status→rejected, sync-safe
{ "name": "memory_delete", "arguments": { "id": "<id>", "hard": true } }  // physical: GDPR / cleanup only

Default to soft delete — it stops surfacing in search and propagates the rejection to peer stores over sync. Use hard: true only for right-to-forget or operator cleanup.

Correction vs deletion

If the fact changed (not "was wrong to store"), don't delete — record a correction so provenance survives: memory_observe the new statement, then memory_supersede the stale id byId the new one. The engine also supersedes automatically when you observe a contradiction, so plain memory_observe is often enough.

Undo a just-added memory

If the user says "undo that" right after a save, search for the most recent item in scope (memory_list), confirm it's the one, and memory_delete it.

graph

⚙️ Graph reasoning requires MemMesh hosted mode. Building the graph works locally: memory_extract_pending → memory_commit_extraction populate typed entities/edges. Multi-hop reasoning/traversal (memory_graph_reason, memory_query_graph, memory_prefetch_related) runs on the hosted engine — set your mm- API key. If those return "unknown tool" on a local install, say so and use search over the extracted entities instead.

MemMesh links memories into a knowledge graph whose edges are bi-temporal (each has valid_from / valid_to). That enables answers a flat store can't give.

Multi-hop reasoning

Answer questions that require chaining edges — "who acquired the company Sarah founded":

{ "name": "memory_graph_reason",
  "arguments": { "anchorEntityId": "<entity id>", "maxHops": 3, "maxPaths": 20 } }

Returns ranked paths (scored by edge weight × recency). The anchor is an entity id — resolve names to ids via a graph query first.

Point-in-time — what did we believe then?

{ "name": "memory_query_graph",
  "arguments": { "subjectId": "<entity id>", "asOf": "2026-01-01T00:00:00Z" } }

Omit asOf for the current view. This reconstructs the graph as it stood on any date — the bi-temporal record, not just the latest state.

Anticipatory retrieval (spreading activation)

Given the memories a session is working with, surface what's most likely needed next:

{ "name": "memory_prefetch_related", "arguments": { "seedMemoryIds": ["<id>","<id>"], "limit": 10 } }

Building the graph

Edges come from client-LLM extraction — the engine hands you a prompt, your own model extracts entities/edges, you commit them (zero engine-side LLM cost):

{ "name": "memory_extract_pending", "arguments": { "projectId": "<repo>", "limit": 10 } }
// run each prompt through your model, then:
{ "name": "memory_commit_extraction", "arguments": { "memoryId": "…", "contentHash": "…", "entities": [...], "edges": [...] } }

Run this loop until extract_pending returns empty to fully populate the graph for reasoning.

health

Diagnose the MemMesh plugin when something seems off.

1. Wiring

memmesh doctor        # binary on PATH, MCP config written, skill present, hooks

If the MCP server isn't listed by the agent, the config didn't take — re-run npx @thinkfleet/memmesh install --force and restart the tool.

2. Read/write round-trip

Prove the engine actually works, end to end:

  1. memory_save a throwaway item (type: "fact", scope: "session", content "memmesh healthcheck <runid>").
  2. memory_search for "healthcheck <runid>" — assert it comes back.
  3. memory_delete (hard) the throwaway so nothing lingers.

If step 1 fails with a cap error, you're at the free-tier 500-item limit — see stats and suggest forget/dream.

3. Common failures

SymptomLikely causeFix
No MemMesh tools visibleMCP config missingmemmesh install --force, restart tool
rejected: ... capfree-tier 500 cap hitdream / forget, or upgrade tier
Search always emptywrong projectId scopecheck switch-project; try userId only
Hosted calls 401bad/missing MEMMESH_API_KEYre-set key in config.toml

4. Report

State clearly what works and what doesn't — don't claim healthy if the round-trip didn't complete.

import

Load durable knowledge into MemMesh.

1. Read the source

Accept: a MemMesh export (Markdown or JSONL), a native MEMORY.md / CLAUDE.md, an ADR folder, or a mem0 export dump.

2. Feed it in — prefer observe

For prose / notes / decisions, memory_observe each item so the engine re-extracts and builds the knowledge graph:

{ "name": "memory_observe", "arguments": { "text": "<one fact/decision>", "projectId": "<repo>" } }

For a MemMesh JSONL backup where you must preserve exact ids/timestamps, use memory_save per row instead.

3. Scope it

Project rules/decisions → scope: "project" with projectId. Personal preferences → scope: "user" with userId. Batch by scope so it's consistent.

4. Idempotency & verify

memory_observe dedupes re-observed text, so a re-run is safe. After import, run stats to confirm the count, and peek a couple of known facts to confirm they're retrievable.

Importing a full mem0/Zep setup (not just a file)? Use memmesh-migrate — it audits call sites, maps the API, and reconciles counts.

onboard

Get a project ready to use MemMesh.

1. Verify wiring

memmesh doctor        # binary + MCP config + skill presence

If the MCP server isn't connected, run npx @thinkfleet/memmesh install (see the memmesh-cli skill), then re-check.

2. Local or hosted?

  • Local (default): SQLite, no key, offline. Good for dev tools.
  • Hosted: set MEMMESH_API_KEY / sync.url in ~/.thinkfleet-memory/config.toml. Needed for cross-device sync, the full SDK, and server-side prediction/verticals.

3. Seed existing knowledge

If the repo already has durable context, import it (see the import skill): MEMORY.md, CLAUDE.md, an ADR folder, or a mem0 export (then consider memmesh-migrate for a full switch). Feed each item via memory_observe so the engine extracts + builds the graph, scoped project.

4. Confirm

Run stats to show what's now in scope, and remind the user of the two-rule loop: the agent will observe their messages and recall at session start automatically (the always-on memmesh skill). Nothing else to configure.

peek

Fast, low-noise lookup.

By query

{ "name": "memory_search", "arguments": { "query": "<term>", "projectId": "<repo>", "limit": 8 } }

Render each hit as a single line: [id-prefix] content — scope/type. Don't dump full JSON.

By id

{ "name": "memory_recall", "arguments": { "id": "<id>" } }

memory_recall also bumps recency (marks the item recently used). Use it to resolve a [memmesh:<id>] citation to its full content.

When to escalate

If the user wants everything grouped by category, use tour. If they want a synthesized picture of one subject (profile + patterns + predictions), use context-loader / memory_build_context.

pin

Mark a memory as protected. MemMesh has no separate "pinned" flag — pinning is expressed through importance + impact + confirmation, which the dream consolidation pass treats as do-not-retire.

Pin

  1. Find the item (memory_search) and read it (memory_recall).
  2. Re-assert it at maximum durability with memory_save (upsert on the same id):
{ "name": "memory_save",
  "arguments": { "id": "<same id>", "platformId": "local", "scope": "project",
                 "type": "rule", "content": "<verbatim content>",
                 "importance": 10, "metadata": { "pinned": true, "impact": "HIGH" } } }

Setting importance: 10 and metadata.pinned: true is the signal the dream skill checks before deleting/superseding anything.

Unpin

Re-save the same id with importance back to a normal value (≈5) and metadata.pinned: false. The item stays in memory but becomes eligible for consolidation again.

When to pin

Architecture decisions, security constraints, compliance rules, immutable conventions — anything where losing it silently would cause real harm. Don't pin routine preferences; let the engine manage those.

predict

⚙️ Requires MemMesh hosted mode. Calibrated prediction and behavior discovery run on the hosted engine — set your mm- API key. On a local / open-source install these tools (memory_predict, memory_build_context) are not registered; if a call returns "unknown tool", tell the user this is a hosted capability and fall back to search / recall for what's already known.

Turn accumulated memory into a forward forecast. Unlike search ("what do we know"), predict answers "what happens next" — and it tells you how confident it honestly is, or abstains.

Forward behavior prediction (local MCP)

{ "name": "memory_predict",
  "arguments": { "subjectKind": "user", "subjectId": "<id>",
                 "horizonDays": 30, "minConfidence": 0.5, "limit": 20 } }

Returns ranked predictions, each with a confidence decayed over the horizon and the provenance behind it. Confidence is calibrated — 0.8 means it's right ~80% of the time — not a raw model logit.

Read the result honestly

  • Present the top predictions with their confidence and horizon.
  • If a prediction abstains (not enough evidence), say so plainly — "not enough signal yet" is a valid, correct answer, and the point of MemMesh.
  • Cite the evidence ids so the user can trace why. Use the why skill to dig into calibration/provenance.

Predict ANY target (hosted / SDK)

The declarative "predict anything" surface (lattice.predictTarget with target.kind ∈ event_occurrence | numeric | event_time | anomaly) lets you add a new prediction with no code change — just name the target. It runs on the hosted gRPC/SDK path:

await memory.lattice.predictTarget({
  subject: { kind: "account", externalId: "acme" },
  target:  { kind: "event_occurrence", name: "churn" },
});

Prereq

Predictions come from mined behavior_pattern memories. If memory_predict returns nothing, the subject may not have enough observed history yet — feed more via observe, or check what patterns exist with the behaviors skill.

remember

Persist something the user asked you to keep.

Default: observe (let the engine extract)

For almost everything, call memory_observe with the user's raw statement. The engine runs deterministic extraction and saves what's memorable — you don't judge.

{ "name": "memory_observe",
  "arguments": { "text": "<the user's exact statement>", "role": "user",
                 "projectId": "<git repo name or null>", "userId": "<OS user>" } }

Verbatim: save (rare)

Only when the user says "save this exactly / verbatim" or you have structured data the extractor would mangle, use memory_save with an explicit id, type, and scope:

{ "name": "memory_save",
  "arguments": { "id": "<21+ char id>", "platformId": "local", "type": "preference",
                 "scope": "user", "content": "prefers pnpm over npm" } }

Pick scope: user (personal preference/identity), project (a repo's rule/ decision/fact), else let the engine default.

After saving

Briefly confirm what was stored and at which scope, so the user can correct it. If they're changing an existing fact, see the pin/correction note: observe the new statement and let the engine supersede — don't delete.

stats

Summarize what's in memory.

{ "name": "memory_stats", "arguments": { "projectId": "<repo>" } }

Scope it with projectId / userId / scope; omit for everything under the platform. Returns total, byType, byScope, byStatus, oldest, newest, and scanCapped (true if the count hit the scan limit — raise limit for an exact number on very large stores).

Present it

Lead with the total, then the type breakdown (the useful one), then flag health signals:

  • a large superseded / rejected share ⇒ suggest dream (consolidation).
  • approaching the free-tier 500-item cap ⇒ mention it and suggest forget/dream.

For a per-subject picture (not aggregate counts) use context-loader.

switch-project

Change which scope memory operations target.

Default detection

By default projectId = the git repo directory name, userId = the OS user, platformId = local. That's usually right.

Point at another project

Pass an explicit projectId on the call:

{ "name": "memory_search", "arguments": { "projectId": "other-repo", "limit": 20 } }

For the rest of the task, keep using that projectId on observe / save / search so reads and writes stay consistent.

Widen the search

  • User-level (personal preferences, cross-project): drop projectId, pass userId and scope: "user".
  • Everything under the platform: pass only platformId (and optionally scope). Use sparingly — it can be noisy.

Confirm the switch

Tell the user which scope you're now reading/writing, and switch back when the cross-project detour is done, so you don't accidentally write memories into the wrong project.

tour

Show the full contents of memory, organized.

Pull the set

{ "name": "memory_list", "arguments": { "projectId": "<repo>", "limit": 100 } }

For a personal overview, pass userId and scope: "user" instead.

Present it

Group by type (preference / fact / rule / decision / behavior_pattern / …), then within each show content with a short id prefix. Call out anything status: superseded separately so the user sees what's been replaced.

End with a one-line summary: total count and the type breakdown (that's exactly what the stats skill returns if you want the numbers).

Big memory sets

If memory_list hits the limit, page with offset, or narrow by scope / type. Suggest dream (consolidation) if the tour reveals lots of duplicates or contradictions.

why

⚙️ Requires MemMesh hosted mode. Calibrated prediction and behavior discovery run on the hosted engine — set your mm- API key. On a local / open-source install these tools (memory_predict, memory_build_context) are not registered; if a call returns "unknown tool", tell the user this is a hosted capability and fall back to search / recall for what's already known.

Make MemMesh's outputs auditable. Every prediction and consolidated fact carries provenance and a calibrated confidence — this skill exposes them so a human can check the reasoning.

Provenance — what is this based on?

A prediction (from predict / memory_build_context) returns evidence memory ids. Resolve each to its content:

{ "name": "memory_recall", "arguments": { "id": "<evidence id>" } }

List the actual memories that drove the conclusion. If a fact was consolidated, its superseded ancestors show the history — that's the audit trail.

Calibration — is the confidence trustworthy?

MemMesh confidences are calibrated: 0.8 should be right ~80% of the time. To show the reliability curve (predicted vs. observed), use the hosted SDK:

const cal = await memory.lattice.getCalibration({ subjectKind: "user" });

Report the calibration error alongside the confidence, so "80%" is backed by evidence it means 80%.

Abstention — the honest "I don't know yet"

If a prediction abstained, explain the reason (insufficient/contradictory evidence, subject too new). Frame abstention as a feature: MemMesh declines rather than fabricate a confident-looking number. This is what makes it usable for EU AI Act / regulated decisions where a wrong confident answer is worse than no answer.

For regulated use

Pair this with the SDK's compliance.listAuditEvents / exportSubject to produce a full defensible record of what was known, when, and what drove a decision.

MCP servers 1

Sponsors

Details

Marketplace
ThinkfleetAI/memmesh
Source
integrations/memmesh-plugin
Category
Community