AGENTS/skills/mem0-memory/SKILL.md

name, description, compatibility

name	description	compatibility
mem0-memory	Store and retrieve memories using Mem0 REST API. Use when: (1) storing information for future recall, (2) searching past conversations or facts, (3) managing user/agent memory contexts, (4) building conversational AI with persistent memory. Triggers on keywords like 'remember', 'recall', 'memory', 'store for later', 'what did I say about'.	opencode

Mem0 Memory

Store and retrieve memories via Mem0 REST API at http://localhost:8000.

Quick Reference

Operation	Method	Endpoint
Store memory	POST	/memories
Search memories	POST	/search
Get all memories	GET	/memories?user_id=X
Get single memory	GET	/memories/{id}
Update memory	PUT	/memories/{id}
Delete memory	DELETE	/memories/{id}
Delete all	DELETE	/memories?user_id=X

Core Operations

Store a Memory

curl -X POST http://localhost:8000/memories \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "I prefer dark mode in all apps"},
      {"role": "assistant", "content": "Noted, you prefer dark mode."}
    ],
    "user_id": "user123"
  }'

Required: messages array with role (user/assistant) and content. Optional: user_id, agent_id, run_id, metadata object.

Search Memories

curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are my UI preferences?",
    "user_id": "user123"
  }'

Required: query string. Optional: user_id, agent_id, run_id, filters object.

Retrieve All Memories

curl "http://localhost:8000/memories?user_id=user123"

Filter by user_id, agent_id, or run_id.

Get Single Memory

curl http://localhost:8000/memories/{memory_id}

Update Memory

curl -X PUT http://localhost:8000/memories/{memory_id} \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated preference: light mode"}'

Delete Memory

curl -X DELETE http://localhost:8000/memories/{memory_id}

Delete All Memories

curl -X DELETE "http://localhost:8000/memories?user_id=user123"

Identity Scopes

Mem0 supports three identity scopes for organizing memories:

Scope	Use Case
user_id	Per-user memories across sessions
agent_id	Per-agent memories (shared across users)
run_id	Per-session memories (temporary)

Combine scopes for fine-grained control:

{
  "messages": [...],
  "user_id": "alice",
  "agent_id": "support-bot",
  "run_id": "session-456"
}

Memory Categories

Memories are classified into 5 categories for organization:

Category	Definition	Obsidian Path	Example
preference	Personal preferences	80-memory/preferences/	UI settings, workflow styles
fact	Objective information	80-memory/facts/	Tech stack, role, constraints
decision	Choices with rationale	80-memory/decisions/	Tool selections, architecture
entity	People, orgs, systems	80-memory/entities/	Contacts, APIs, concepts
other	Everything else	80-memory/other/	General learnings

Metadata Pattern

Include category in metadata when storing:

{
  "messages": [...],
  "user_id": "user123",
  "metadata": {
    "category": "preference",
    "source": "explicit"
  }
}

• category: One of preference, fact, decision, entity, other
• source: "explicit" (user requested) or "auto-capture" (automatic)

Workflow Patterns

Pattern 1: Remember User Preferences

User says "Remember I like X" -> Store with their user_id:

curl -X POST http://localhost:8000/memories \
  -d '{"messages":[{"role":"user","content":"Remember I like dark mode"}], "user_id":"USER_ID"}'

Pattern 2: Recall Past Context

User asks "What did I tell you about X?" -> Search:

curl -X POST http://localhost:8000/search \
  -d '{"query":"dark mode preferences", "user_id":"USER_ID"}'

Pattern 3: Session Memory

Store conversation context for current session only:

curl -X POST http://localhost:8000/memories \
  -d '{"messages":[...], "run_id":"SESSION_ID"}'

Dual-Layer Sync

Memories are stored in BOTH Mem0 AND the Obsidian CODEX vault for redundancy and accessibility.

Sync Pattern

1. Store in Mem0 first - Get mem0_id from response
2. Create Obsidian note - In 80-memory/<category>/ using memory template
3. Cross-reference:
   • Add mem0_id to Obsidian note frontmatter
   • Update Mem0 metadata with obsidian_ref (file path)

Example Flow

# 1. Store in Mem0
RESPONSE=$(curl -s -X POST http://localhost:8000/memories \
  -d '{"messages":[{"role":"user","content":"I prefer dark mode"}],"user_id":"m3tam3re","metadata":{"category":"preference","source":"explicit"}}')

# 2. Extract mem0_id
MEM0_ID=$(echo $RESPONSE | jq -r '.id')

# 3. Create Obsidian note (via REST API or MCP)
# Path: 80-memory/preferences/prefers-dark-mode.md
# Frontmatter includes: mem0_id: $MEM0_ID

# 4. Update Mem0 with Obsidian reference
curl -X PUT http://localhost:8000/memories/$MEM0_ID \
  -d '{"metadata":{"obsidian_ref":"80-memory/preferences/prefers-dark-mode.md"}}'

When Obsidian Unavailable

• Store in Mem0 only
• Log sync failure
• Retry on next access

Response Format

Memory objects include:

{
  "id": "mem_abc123",
  "memory": "User prefers dark mode",
  "user_id": "user123",
  "created_at": "2025-12-31T12:00:00Z",
  "updated_at": "2025-12-31T12:00:00Z"
}

Search returns array of matching memories with relevance scores.

Health Check

Verify API is running:

curl http://localhost:8000/health

Pre-Operation Check

Before any memory operation, verify Mem0 is running:

if ! curl -s http://localhost:8000/health > /dev/null 2>&1; then
  echo "WARNING: Mem0 unavailable. Memory operations skipped."
  # Continue without memory features
fi

Error Handling

Mem0 Unavailable

When curl http://localhost:8000/health fails:

• Skip all memory operations
• Warn user: "Memory system unavailable. Mem0 not running at localhost:8000"
• Continue with degraded functionality

Obsidian Unavailable

When vault sync fails:

• Store in Mem0 only
• Log: "Obsidian sync failed for memory [id]"
• Do not block user workflow

API Errors

Status	Meaning	Action
400	Bad request	Check JSON format, required fields
404	Memory not found	Memory may have been deleted
500	Server error	Retry, check Mem0 logs

Graceful Degradation

Always continue core functionality even if memory system fails. Memory is enhancement, not requirement.

API Reference

See references/api_reference.md for complete OpenAPI schema.