Lifecycle: Observe → Learn → Recall

MemMesh runs a continuous loop: you feed it raw text, it decides what’s worth keeping and how to structure it, and your agents recall it later. The three phases are observe, learn, and recall.

1. Observe

You hand the engine raw text — a conversation turn, a stated preference, a decision — via memory_observe. You don’t decide what’s important; the engine does. Observing is intentionally cheap so you can do it liberally.

memory_observe("We decided to standardize on pnpm across all repos.")

By default, observe runs a zero-LLM heuristic extraction pass (regex and structural rules) and writes the resulting memories. It costs no tokens and is idempotent — re-observing the same text is a no-op.

You can also write a memory verbatim with memory_save when you have structured data that won’t survive the heuristics, or want to record something exactly.

2. Learn

Learning is where raw text becomes durable, typed, provenance-bearing knowledge. Several passes run beyond the heuristic extraction:

Belief revision — in the background, when a new memory contradicts an existing one, the older memory is superseded (see the status lifecycle).
Graph extraction (agent-run LLM) — richer entity/edge extraction runs through an explicit two-step protocol so the engine never makes an LLM call itself:
1. memory_extract_pending returns memories whose graph entities aren’t extracted yet, each with an LLM-ready prompt.
2. Your agent runs each prompt through its own model.
3. memory_commit_extraction persists the entities + edges and stamps a content hash on the source memory. The step is content-hash idempotent — unchanged content is skipped, and a commit is rejected if the content changed since it was fetched.
Observe v2 (optional, gated) — an LLM conversational-extraction pass that pulls durable facts out of narrative text the heuristics miss. It is gated by the MEMORY_LLM_MEMORY_EXTRACTION_ENABLED ops switch and the per-tenant FEATURE_MEMORY_INTELLIGENCE entitlement, so free-tier writes stay on the zero-cost heuristic path. See the Memory API.

3. Recall

Recall has distinct tools — they are not interchangeable:

Tool	What it does
`memory_search`	Relevance retrieval — hybrid semantic + recency + importance ranking, filtered by scope.
`memory_list`	The same retrieval with no query — newest-first items in a scope.
`memory_recall`	Fetch a single memory item by its id. Not semantic retrieval; bumps `lastAccessedAt`. Use it after a search returns ids you want in full.

memory_search("package manager convention")
→ "Standardized on pnpm across all repos" (decision, project scope)

The loop in practice

A well-instrumented agent observes on every meaningful turn and recalls at the start of every task — so each session starts already knowing what prior sessions learned. The available tools are listed on the Claude Code and MCP overview pages.

Behavior Discovery Claude Code