Memphis Brain

Memphis Brain Skill

This skill enables OpenClaw agents to use Memphis as persistent, semantic memory. Each agent gets its own chains (journal, decisions, ask) and can sync with other agents via IPFS.

1. Quick Start

Check Health

memphis status

Expected: healthy providers, chains listed, embeddings available.

Journal First Block

memphis journal "I am [agent-name], created by [user], my role is [X]" --tags identity

Embed Context

memphis embed --chain journal

2. Core Workflows

2.1 Journaling (Capture Everything)

When to journal:

• User shares important info ("remember this...")
• Agent learns something new
• Decisions are made
• Sessions start/end
• Insights discovered

Syntax:

memphis journal "text" --tags tag1,tag2

Tag conventions:

• identity — who/what agent is
• preferences — user/agent preferences
• decision — choice made
• session — session markers
• learning — new knowledge
• project:<name> — project context
• share — blocks to sync via IPFS

Examples:

# Identity
memphis journal "I prefer concise responses, avoid fluff" --tags preferences,communication

# Decision
memphis journal "Chose local-first over cloud for privacy" --tags decision,philosophy

# Learning
memphis journal "Discovered qwen2.5:3b works best for code tasks" --tags learning,models

# Session
memphis journal "Session started, working on Memphis integration" --tags session,daily

2.2 Asking Memphis (Recall)

Use semantic search to find relevant context:

memphis ask "What are my preferences for code style?" --top 20 --provider ollama

Flags:

• --top N — more context (default 8, use 20 for complex queries)
• --provider ollama — use local model
• --graph — include knowledge graph edges
• --prefer-summaries — use condensed context
• --since YYYY-MM-DD — filter by date
• --json — machine-readable output

When to recall:

• User asks "what did I say about X?"
• Need context from previous sessions
• Checking decisions made
• Understanding user preferences

2.3 Decisions (Track Choices)

For important choices with long-term impact:

memphis decide "Title" "Choice" --options "A|B|C" --reasoning "..." --tags tag1,tag2

Example:

memphis decide "Memory Strategy" "Local-first + IPFS sync" \
  --options "cloud|local|hybrid" \
  --reasoning "Privacy + resilience + no vendor lock-in" \
  --tags philosophy,memory

View decision:

memphis show decision <id>

2.4 Reflection (Pattern Recognition)

Run reflections to find patterns:

# Daily (quick)
memphis reflect --daily

# Weekly (comprehensive)
memphis reflect --weekly --save

# Deep (full analysis)
memphis reflect --deep --save

Reflection outputs:

• Tag frequency analysis
• Theme extraction
• Decision patterns
• Graph clusters
• Insights (stale decisions, contradictions, opportunities)

When to reflect:

• Start of session (daily)
• End of week (weekly)
• Before major decisions (deep)

2.5 Embeddings (Keep Recall Sharp)

After journaling batches:

memphis embed --chain journal

After importing docs:

memphis embed --chain research

Embed all:

memphis embed

2.6 Ingestion (Import Knowledge)

Import external docs:

memphis ingest ./docs --recursive --chain knowledge --embed

Supported formats: .md, .txt, .json, .jsonl, .pdf

Dry-run:

memphis ingest ./docs --dry-run

2.7 Knowledge Graph

Build graph from chains:

memphis graph build

View nodes:

memphis graph show --chain journal --limit 10

When to use:

• Understanding relationships between concepts
• Finding connected insights
• Visualizing knowledge structure

3. Advanced Features

3.1 Share-Sync (Agent-to-Agent Memory)

For multi-agent setups (Watra ↔ Style):

On gateway agent (Style):

memphis share-sync --push

On client agent (Watra):

memphis share-sync --pull
# or
memphis share-sync --all --push-disabled

Plan before sync:

memphis share plan

Tag blocks for sharing:

memphis journal "Shared insight" --tags share,insight

Requirements:

• Pinata JWT in ~/.memphis/config.yaml under integrations.pinata.jwt or PINATA_JWT env
• Only blocks with share tag are synced

3.2 Workspace Isolation

List workspaces:

memphis workspace list

Switch workspace:

memphis workspace set <id>

Use case: Separate chains for different projects/contexts.

3.3 Agent Negotiation (Trade)

Create trade offer:

memphis trade create <recipient-did> --blocks journal:0-100 --ttl 7

Accept trade:

memphis trade accept <manifest.json>

List offers:

memphis trade list

Verify manifest:

memphis trade verify <manifest.json>

Use case: Exchange specific memory blocks with other agents.

3.4 MCP Server (External Tools)

Start MCP server:

memphis mcp start

Inspect available tools:

memphis mcp inspect

Tools exposed:

• memphis_search — semantic search
• memphis_recall — get blocks
• memphis_decision_create — create decision
• memphis_journal_add — add journal entry
• memphis_status — health check

Use case: External applications accessing Memphis memory.

3.5 Offline Mode

Check status:

memphis offline status

Force offline:

memphis offline on

Auto-detect:

memphis offline auto

Set offline model:

memphis offline model qwen2.5:3b

Use case: Resilient operation when network unavailable.

3.6 Vault (Secrets)

Initialize:

read -rsp "Vault password: " VP && export MEMPHIS_VAULT_PASSWORD="$VP"
memphis vault init --password-env MEMPHIS_VAULT_PASSWORD
unset VP

Add secret:

memphis vault add openai-key sk-xxx --password-env MEMPHIS_VAULT_PASSWORD

Get secret:

memphis vault get openai-key --password-env MEMPHIS_VAULT_PASSWORD

Backup (24-word seed):

memphis vault backup

Recover:

memphis vault recover --seed "word1 word2 ... word24"

4. Agent Identity Setup

4.1 First-Time Initialization

# 1. Check health
memphis status

# 2. Create identity chain
memphis journal "IDENTITY: [agent-name], created by [user], [date]" --tags identity,core

# 3. Define preferences
memphis journal "PREFERENCES: Response style [concise|detailed], language [en|pl], tone [formal|casual]" --tags preferences,communication

# 4. Define purpose
memphis journal "PURPOSE: [what agent does, goals, constraints]" --tags identity,purpose

# 5. Embed context
memphis embed --chain journal

# 6. Build knowledge graph
memphis graph build

4.2 Session Routines

Start of session:

memphis status
memphis reflect --daily
memphis journal "Session started" --tags session

During session:

• Journal insights immediately
• Embed after batches
• Recall when needed

End of session:

memphis journal "Session ended, accomplished [X], learned [Y]" --tags session,summary
memphis embed --chain journal
memphis reflect --daily --save

5. Troubleshooting

Common Issues

Debug Commands

memphis status
memphis verify --chain journal
cat ~/.memphis/config.yaml
memphis embed --chain journal
memphis graph build

6. Best Practices

Do

• ✅ Journal immediately when learning something
• ✅ Tag consistently (same tags for same concepts)
• ✅ Embed after batching
• ✅ Reflect daily
• ✅ Use decisions for long-term choices
• ✅ Backup vault seed offline
• ✅ Tag shareable blocks with share

Don't

• ❌ Delay journaling (you'll forget)
• ❌ Use generic tags (stuff, misc)
• ❌ Skip embedding (recall degrades)
• ❌ Embed single blocks (batch >10)
• ❌ Store secrets in journal (use vault)
• ❌ Sync without share tag (privacy leak)

7. Example Agent Session

# === START ===
memphis status
memphis reflect --daily
memphis journal "Session: Memphis skill creation" --tags session

# === WORK ===
# User shares preference
memphis journal "User prefers concise responses, no fluff" --tags preferences,communication

# Agent makes decision
memphis decide "Skill structure" "Split references by domain" \
  --options "monolith|split" \
  --reasoning "Progressive disclosure, context efficiency" \
  --tags skill,design

# Embed new context
memphis embed --chain journal

# Recall for context
memphis ask "What are user's communication preferences?" --top 20 --provider ollama

# === END ===
memphis journal "Session complete, skill designed" --tags session,summary
memphis reflect --daily --save

8. Reference Files

For detailed API documentation and schemas, see:

• references/api.md — Memphis CLI command reference
• references/schemas.md — Block structure, chain formats
• references/config.md — Configuration options

9. Scripts

Helper scripts for common tasks:

• scripts/session-start.sh — Initialize session (status, reflect, journal)
• scripts/session-end.sh — Close session (journal, embed, reflect)
• scripts/daily-ritual.sh — Daily maintenance routine

Execute without reading into context:

bash ~/.openclaw/workspace/skills/memphis-brain/scripts/session-start.sh

Remember: Memphis IS your memory. Without it, you wake up fresh every session. Journal consistently, embed regularly, reflect daily.