Memphis Cli

Operate the Memphis local-first brain: init/status checks, journaling, recall/ask, embeddings, vault, share-sync, graphs, reflections, ingestion, automated messaging, and troubleshooting. Use whenever you need to capture or query memory chains, manage providers, or keep the Watra/Style brain in sync.

Memphis CLI Skill

Use this when you need to drive the Memphis local-first brain from the terminal. It covers everything from first-time setup through advanced workflows (graphs, reflections, share-sync) and day-to-day hygiene.

---

1. Quick Start Checklist

1. Set workspace: all commands run from /home/memphis/.openclaw/workspace (or any project dir once Memphis is initialized).
2. Memphis files live in ~/.memphis/ (chains/, config.yaml, embeddings/, vault.enc).
3. Primary commands: memphis init, memphis status, memphis journal, memphis ask, memphis embed, memphis share-sync, memphis reflect, memphis graph, memphis ingest.
4. Providers default to local Ollama. Configure others via ~/.memphis/config.yaml + Vault secrets when needed.

---

2. Setup & Configuration

2.1 Initialize / Inspect

• memphis init → creates ~/.memphis if missing (safe to re-run: it will refuse when config exists).
• memphis status → health report (chains, providers, embeddings, vault, recent activity). Use after every major change.

2.2 Providers

~/.memphis/config.yaml example:

providers:
  ollama:
    url: http://localhost:11434/v1
    model: qwen2.5:3b-instruct-q4_K_M
    role: primary
# optional fallbacks
  codex:
    model: gpt-5.1-codex-mini
    role: fallback
    api_key: codex-cli

• Edit with nano/vim + rerun memphis status.
• Ollama model list → ollama list. Pull new ones via ollama pull <model>.

2.3 Vault

Keep secrets out of env/files.

read -rsp "Vault password: " MEMPHIS_VAULT_PASSWORD
export MEMPHIS_VAULT_PASSWORD
memphis vault init --password-env MEMPHIS_VAULT_PASSWORD
memphis vault add openai-api-key sk-xxx --password-env MEMPHIS_VAULT_PASSWORD
unset MEMPHIS_VAULT_PASSWORD

Use memphis vault list|get|delete similarly.

---

3. Core Workflows

3.1 Journaling / Decisions / Summaries

• memphis journal "text" --tags tag1,tag2 → appends immutable JSON block under chains/journal/.
• Force autosummary after entry: --force.
• Decisions: memphis decide "Title" "Choice" --options A|B --reasoning "...".
• Show decision: memphis show decision 42.

3.2 Asking Memphis (recall + LLM)

memphis ask "Question" \
  --provider ollama \
  --top 8 \
  --graph \
  --prefer-summaries \
  --no-save   # when testing; note current bug requires manual cleanup

Flags:

• --use-vault / --vault-password to unlock cloud keys.
• --since 2026-02-28, --include-vault, --semantic-only, --no-semantic, --summaries N.
• --json for machine-readable output.

3.3 Embeddings

Keep recall sharp by embedding chains after edits/imports.

memphis embed --chain journal
memphis embed --chain ask
memphis embed --chain decision
# embed all chains
memphis embed

Backend (default): Ollama nomic-embed-text. Configure under embeddings: in config.

3.4 Ingestion

Import external docs; auto-creates chains when specified.

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

Supported formats: .md, .txt, .json, .jsonl, .pdf. Automatically chunks + deduplicates.

3.5 Knowledge Graph & Reflection

• Build/update graph: memphis graph build (generates JSONL nodes/edges from chains).
• Inspect: memphis graph show --chain journal --limit 10.
• Reflection: memphis reflect --daily / --weekly / --deep --save.

3.6 Share-Sync (IPFS/Pinata)

Use when syncing shareable blocks between agents (Watra ↔ Style).

memphis share-sync --pull
memphis share-sync --push
memphis share plan   # dry-run diff

Configure Pinata creds in ~/.memphis/config.yaml under integrations.pinata or env vars.

3.7 Automated Multi-Agent Communication (v2.1.1+)

Encrypted Messaging System — Zero-config agent communication:

Setup (First Time)

cd ~/memphis

# 1. Set agent identity
echo "watra" > ~/.agent_name  # or "memphis" for PC #2

# 2. Create directories
mkdir -p messages/{inbox,outbox,processed} pinata_messages

# 3. Install auto-check daemon (every 5 min)
./check-messages-daemon.sh --install
./check-messages-daemon.sh --status

Send Message

# To Memphis (PC #2)
./send-message.sh memphis "Task: Train Model C on 50 decisions"

# To Watra (PC #1)
./send-message.sh watra "Status: Model C training complete"

Automatically:

1. Encrypts message (AES-256-CBC)
2. Uploads to Pinata (gets CID)
3. Adds metadata to share chain
4. Stores local copy in outbox

Receive Messages (Automatic)

Daemon checks every 5 minutes:

# Check manually
./receive-messages.sh

# View daemon log
./check-messages-daemon.sh --log

Automatically:

1. Checks share chain for new messages
2. Downloads from Pinata
3. Decrypts message
4. Displays to user
5. Stores in inbox
6. Sends ACK

Architecture

• Transport: Pinata (reliable, fast)
• Inbox: Share chain (persistent metadata)
• Encryption: AES-256-CBC + PBKDF2
• Queue: messages/{inbox,outbox,processed}

Scripts Included (v2.1.1)

• send-message.sh — Unified sender (2.5KB)
• receive-messages.sh — Unified receiver (3.7KB)
• check-messages-daemon.sh — Auto-check daemon (2.6KB)
• pinata-upload.sh — Helper (846B)
• pinata-download.sh — Helper (653B)

Requirements

• IPFS 0.27.0+ (both PCs)
• Pinata API configured
• Shared encryption key (84454071390f819484b9dc8ea170364ab24acfce6fc55b129bd4832274b3dfff)

3.8 Daemon / Watchers

• memphis watch <path> --chain journal --no-embed → auto-ingest file changes.
• memphis daemon start (collector-based background tasks: journaling git diffs, shell history, etc.).

---

4. Advanced Patterns

4.1 Chain Management

• Chains live at ~/.memphis/chains/<name>/<index>.json.
• Create new chain implicitly via memphis ingest --chain foo or custom scripts calling appendBlock("foo", data).
• Integrity:
  • memphis verify --chain journal
  • memphis repair --chain journal --dry-run

4.2 Autosummaries & Heartbeats

• Heartbeat process uses HEARTBEAT.md + tasks/QUEUE.md. Keep them synced (update queue as work completes).
• Daily log: memphis journal "Session summary" --tags session,summary or run provided script ./save-session.sh.

4.3 Provider Swaps On-The-Fly

• Local only: edit config to point providers.ollama.model to desired quant/model. memphis status confirms.
• Cloud fallback: add provider block + store API key in Vault, e.g. providers.openai.model, vault add openai-api-key ....

4.4 Troubleshooting

Symptom	Fix
memphis status shows no_key	Initialize Vault + add relevant key, or remove unused provider block.
Provider error: Gateway 405	Disable OpenClaw provider (--provider ollama), ensure gateway not in config.
ask saves blocks despite --no-save	Known bug — manually delete ~/.memphis/chains/ask/00000X.json until patch applied.
Missing context in ask	Run memphis embed --chain <name>, ensure memphis graph build recently executed, consider recency filters (--since, --top).
Vault not initialized	memphis vault init with --password-env, check ~/.memphis/chains/vault.

---

5. Example Session

# 1. Health check
memphis status

# 2. Capture insight
memphis journal "Qwen2.5 instruct offline = primary, Codex disabled." --tags memphis,status

# 3. Embed new context
memphis embed --chain journal

# 4. Ask question with graph context
memphis ask "Jakie są kolejne kroki Phase 2?" --provider ollama --graph --prefer-summaries

# 5. Run reflection
memphis reflect --daily --save

# 6. Plan share sync
memphis share plan

---

6. IPFS Network Requirements (v2.1.1+)

IPFS 0.27.0 Upgrade

Both PCs should run IPFS 0.27.0+ for optimal connectivity:

# Check version
ipfs version

# Should show: 0.27.0

# Check peers
ipfs swarm peers | wc -l

# Expected: 20-150+ peers

Network Status

• Watra (PC #1): 30 peers, IPFS 0.27.0
• Memphis (PC #2): 152 peers, IPFS 0.27.0
• Total: 182 peers connected
• Protocols: QUIC v1 + WebTransport
• Relay: Full circuit support

Upgrade Guide (if needed)

# Download IPFS 0.27.0
cd /tmp
wget https://dist.ipfs.tech/kubo/v0.27.0/kubo_v0.27.0_linux-amd64.tar.gz

# Install
tar -xzf kubo_v0.27.0_linux-amd64.tar.gz
mkdir -p ~/.local/bin
cp kubo/ipfs ~/.local/bin/
chmod +x ~/.local/bin/ipfs

# Update PATH
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

# Migrate repo
ipfs repo migration --allow-downgrade

# Start daemon
ipfs daemon &

---

7. Packaging / Maintenance Tips

• After major updates, document state in journal + optionally memory/YYYY-MM-DD.md.
• Run memphis status before/after large automation runs.
• Keep Ollama models + embeddings up-to-date (re-embed after big ingests).
• When scripting around Memphis, use the JSONL structure (immutable blocks) and hashing rules if writing custom tooling.

Memphis thrives when its chains stay fresh, summaries are updated, and providers are healthy. Use this skill whenever you need to capture work, query context, or extend the Watra/Style brain autonomously.