smart-memory

name	smart-memory
description	Persistent local transcript-first memory via FastAPI (127.0.0.1:8000). Use for semantic recall, durable memory commits, transcript inspection, and pending insight retrieval through the Smart Memory v3.1 backend.
metadata	{"openclaw":{"emoji":"??","requires":{"bins":["curl"]}}}

Smart Memory OpenClaw Skill

This skill wraps the Smart Memory backend running at http://127.0.0.1:8000.

The wrapper package lives in skills/smart-memory-openclaw/, and the backend it targets is Smart Memory v3.1 with transcript-first ingestion, SQLite-backed durable memory, evidence-backed revision chains, status-aware retrieval, and explicit core and working memory lanes.

When to Use

Use this skill when you need to:

• recall prior decisions, preferences, goals, or project state
• persist important new facts, pivots, completions, or blockers
• inspect transcript-backed evidence behind a memory
• inspect pending insights from background cognition
• ground an OpenClaw session in local memory continuity

Do not use it when the recent context window already fully answers the question or when the local memory server is unavailable.

Prerequisites

curl -s http://127.0.0.1:8000/health

If the server is not running, start it from the repo root:

.\.venv\Scripts\python -m uvicorn server:app --host 127.0.0.1 --port 8000

OpenClaw Configuration

Disable OpenClaw's built-in file-search memory tools so this skill's semantic path takes precedence:

openclaw config set tools.deny '["memory_search", "memory_get"]'
openclaw gateway restart

Core Operations

Search memory

curl -s -X POST http://127.0.0.1:8000/retrieve \
  -H "Content-Type: application/json" \
  -d '{"user_message":"What did we decide about the database migration?"}'

Notes:

• retrieval excludes superseded and expired memories by default
• use natural-language queries instead of keyword fragments
• use transcript and evidence endpoints when you need deeper inspection

Commit memory

curl -s -X POST http://127.0.0.1:8000/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "user_message":"Deployment is blocked on config diff review.",
    "assistant_message":"Captured as active task state.",
    "source_session_id":"session-123"
  }'

Notes:

• semantic changes become revision actions such as SUPERSEDE
• metadata-only changes can UPDATE
• failed commits are queued in .memory_retry_queue.json by the wrapper

Check insights

curl -s http://127.0.0.1:8000/insights/pending

Useful inspection endpoints

curl -s http://127.0.0.1:8000/memories
curl -s http://127.0.0.1:8000/memory/<memory_id>
curl -s http://127.0.0.1:8000/memory/<memory_id>/evidence
curl -s http://127.0.0.1:8000/memory/<memory_id>/history
curl -s http://127.0.0.1:8000/memory/<memory_id>/active
curl -s http://127.0.0.1:8000/memory/<memory_id>/chain
curl -s http://127.0.0.1:8000/transcripts/<session_id>
curl -s http://127.0.0.1:8000/lanes/core
curl -s http://127.0.0.1:8000/lanes/working
curl -s -X POST http://127.0.0.1:8000/rebuild

Prompt guidance

If pending insights appear in context and they genuinely relate to the current conversation, surface them naturally. Do not force them in.

Operational notes

• the wrapper health-checks the backend before tool calls
• failed commits queue locally and flush on later healthy calls
• session-arc capture and prompt injection still live in this package
• transcript rows are canonical truth and memories are derived