
memmesh
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-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add ThinkfleetAI/memmesh.
Contents
Discovered from sourceSkills 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 tosearch/recallfor 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 tosearch/recallfor 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_supersedethe olderbyIdthe newer. Provenance is preserved. - Exact duplicate → keep one,
memory_deletethe 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/dedupin 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_extractionpopulate typed entities/edges. Multi-hop reasoning/traversal (memory_graph_reason,memory_query_graph,memory_prefetch_related) runs on the hosted engine — set yourmm-API key. If those return "unknown tool" on a local install, say so and usesearchover 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:
memory_savea throwaway item (type: "fact",scope: "session", content"memmesh healthcheck <runid>").memory_searchfor"healthcheck <runid>"— assert it comes back.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
| Symptom | Likely cause | Fix |
|---|---|---|
| No MemMesh tools visible | MCP config missing | memmesh install --force, restart tool |
rejected: ... cap | free-tier 500 cap hit | dream / forget, or upgrade tier |
| Search always empty | wrong projectId scope | check switch-project; try userId only |
| Hosted calls 401 | bad/missing MEMMESH_API_KEY | re-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.urlin~/.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
- Find the item (
memory_search) and read it (memory_recall). - 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 tosearch/recallfor 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
whyskill 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/rejectedshare ⇒ suggestdream(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, passuserIdandscope: "user". - Everything under the platform: pass only
platformId(and optionallyscope). 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 tosearch/recallfor 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