memory

name	memory
description	Use when user invokes /memory with a subcommand (search, trace, add, episode, status). Also triggers on "search my memory for X", "add to memory", "what do I know about X" (when membrain is available), "memory status", "memory trace". Searches and manages the membrain knowledge graph via MCP tools or HTTP API.

membrain Memory

Overview

Interface with the membrain knowledge graph — search entities, trace BFS traversals, add observations, create episodes, and check graph health.

Graceful degradation: If membrain MCP tools are not available, print install instructions and exit. If the HTTP server is not running, skip HTTP-dependent subcommands and say so.

Subcommands

Parse the argument after /memory to determine which operation to run.

Invocation	Operation
/memory search <topic>	Search the graph for entities matching the topic
/memory trace <query>	Run BFS traversal and display token savings
/memory add <entity> <observation>	Add an observation to an existing entity
/memory episode <text>	Create a timestamped episode from free text
/memory status	Show graph statistics (entity/relation counts)
/memory (no args)	Show usage and subcommand list

---

Step 1: Check MCP Availability

Before any graph operation, confirm membrain MCP tools are available.

Test: Can you call search_nodes? If the tool is missing from the tool list:

membrain MCP tools are not connected.

To connect them:
  1. Install mem: go install github.com/siracusa5/membrain/cmd/mem@latest
  2. Add to Claude Code settings (or via /plugin install membrain@harness-kit):
     {
       "mcpServers": {
         "membrain": { "command": "mem", "args": ["mcp"] }
       }
     }
  3. Restart Claude Code

For the desktop UI: mem serve   (opens http://localhost:3131)

---

Step 2: Route to Subcommand

search <topic>

Search the graph for entities and relations related to the topic.

1. Call search_nodes with the topic as the query
2. If results < 3, try decomposing the topic into individual keywords and search each (max 2 additional calls)
3. Format results:

## Memory: "<topic>"

Found N entities  ·  saved X% tokens vs full graph dump

### <EntityName> (Type)
- observation 1
- observation 2
- observation 3

### <EntityName> (Type)
...

Relations: A → relationType → B

Caps: Max 10 entities shown. Max 3 observations per entity. Max 3 search_nodes calls.

If no results: "No entities found for '[topic]'. Try a broader term or check /memory status to confirm the graph has data."

---

trace <query>

Run a BFS traversal to show how topics connect through the graph.

Requires: membrain server running on http://localhost:3131

1. Call GET http://localhost:3131/api/v1/trace?focus=<query> (URL-encode the query)
2. Parse the response — it includes traversal frames and token stats
3. Display:

## Trace: "<query>"

Traversal: N nodes  ·  depth D  ·  saved X% vs full dump

Starting node → relation → Node B → relation → Node C
                                               → relation → Node D
...

Token savings: retrieved ~X tokens of ~Y total (Z% saved)

Open in browser: http://localhost:3131/trace?focus=<query>

If the server is not running: "membrain server is not running. Start it with: mem serve"

---

add <entity> <observation>

Add an observation to an existing entity in the graph.

Parse the argument: everything before the first quoted string or : is the entity name; the rest is the observation.

Examples:

• /memory add Claude "ships membrain MCP integration" → entity: Claude, obs: ships membrain MCP integration
• /memory add Claude: ships membrain MCP integration → same

1. Call add_observations with:

   [{ "entityName": "<entity>", "contents": ["<observation>"] }]
   

2. On success: "Added observation to ."
3. If entity not found: "Entity '' not found. Create it first with create_entities or use /memory episode to capture a session."

---

episode <text>

Create a timestamped episode capturing a chunk of session knowledge.

1. Extract a short name from the text (first sentence or ≤60 chars)
2. Scan the text for entity names that exist in the graph (use recent search_nodes results if available)
3. Call add_episode with:

   {
     "name": "<short-name> (YYYY-MM-DD)",
     "summary": "<full text>",
     "occurred_at": "<current ISO timestamp>",
     "mentioned_entities": ["Entity1", "Entity2"]
   }
   

   mentioned_entities auto-links the episode to existing graph entities — always include them when identifiable.
4. On success: "Episode created: "

---

status

Show graph health and statistics.

Requires: membrain server running on http://localhost:3131

1. Call GET http://localhost:3131/api/v1/graph/stats
2. Display:

## membrain Status

Entities:  N
Relations: N
Episodes:  N

Server:    http://localhost:3131  ✓
Graph:     <path to graph file>

Desktop UI:  http://localhost:3131/

If server not running: note that the server is offline and MCP-only stats are not available (membrain does not support entity count queries via MCP without the HTTP server).

---

No args

Print usage:

## /memory — membrain knowledge graph

  /memory search <topic>          search entities
  /memory trace <query>           BFS traversal with token stats
  /memory add <entity> <obs>      add an observation
  /memory episode <text>          create timestamped episode
  /memory status                  graph health and counts

---

Common Mistakes

Mistake	Fix
Calling read_graph	NEVER. Use search_nodes for all queries.
Treating entity name as case-sensitive	membrain names are case-sensitive — match exact name from prior search results
Running HTTP calls when server might be down	Always note if server is unreachable; MCP tools still work offline
Showing raw JSON	Format output as human-readable markdown
Exceeding search caps	Max 3 search_nodes calls per /memory search invocation