🦞 ClawMemory

ClawMemory is a local-first memory layer for OpenClaw/OpenKrab ecosystem.
It gives agents persistent memory, semantic recall, session buffering, reminder commitments, and a self-host dashboard.

Features

• Persistent Memory: Markdown source of truth + SQLite index (memory/events, memory/index.sqlite3).
• Smart Recall: Hybrid lexical + semantic retrieval with snippets and prompt-ready context.
• Session Buffer: Append/peek/flush short-term memory safely.
• Intent Scheduler: pending/overdue/completed reminders (better than plain cron).
• Dashboard TUI: Timeline, search, health cards, sessions, and commitments directly in your terminal.
• Claw Integrations:
  • ClawReceipt: recurring purchase patterns (finance/recurring)
  • ClawFlow: cron setup memory + fail follow-up reminders
  • ClawWizard: preference memory (interactive vs cli)
  • ClawGraph: entity & relationship sync (projects, clients, tasks, expenses)
• Privacy First: Self-host/local by default, no cloud API required.
• Optional Real Vector DB: Chroma + sentence-transformers (local).

---

Memory Flow

flowchart TD
    A([User/Tool Event]) --> B{Capture Type}
    B -->|Direct Fact| C[memory_write]
    B -->|Conversation Turn| D[memory_session_append]
    D --> E{Flush condition met?}
    E -->|yes| F[memory_session_flush]
    E -->|no| D

    C --> G[(Markdown + SQLite)]
    F --> G

    G --> H[memory_search]
    H --> I[snippet + prompt_context]

    G --> J[memory_distill]
    J --> K[MEMORY.md]
    J --> L[profile.md]

    M[reminder_set] --> N[(commitments.sqlite3)]
    N --> O[reminder_poll/watch]
    O --> P[overdue or completed]

Loading

---

Getting Started

Prerequisites

• Python 3.10+
• OpenClaw CLI (recommended for plugin usage)

Installation

1. Clone repo

git clone https://github.com/OpenKrab/ClawMemory.git
cd ClawMemory

1. Create virtual environment and install

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

1. Run tests

pytest -q tests --capture=no

---

OpenClaw Plugin Setup

Install plugin from local path:

openclaw plugins install --link /absolute/path/to/ClawMemory
openclaw plugins enable clawmemory

Set memory slot:

{
  "plugins": {
    "slots": {
      "memory": "clawmemory"
    }
  }
}

Plugin Config

• pythonBin (default: python3)
• memoryRoot (default: memory)
• timeoutMs (default: 20000)
• autoFlushMaxTurns (default: 24)
• minConfidence (default: 0.7)
• reminderDefaultSeconds (default: 300)
• vectorBackend (hashed | chroma)
• embedModel (default: all-MiniLM-L6-v2)

---

Core Commands

Memory

clawmemory write --payload '{"text":"User prefers interactive wizard","source":"clawwizard/session","tags":["preference"],"confidence":0.9}'
clawmemory search --query "wizard preference" -k 5
clawmemory get --id <memory_id>

Session Buffer

clawmemory session-append --session-id s1 --role user --content "I prefer wizard setup"
clawmemory session-peek --session-id s1 --limit 20
clawmemory session-flush --session-id s1 --min-confidence 0.7

Distill

clawmemory distill --days 7

Reminders

clawmemory reminder-set --text "check build result" --in-seconds 300
clawmemory reminder-list --status pending
clawmemory reminder-poll --limit 100
clawmemory reminder-complete --id <reminder_id> --note "done"
clawmemory reminder-snooze --id <reminder_id> --seconds 120
clawmemory reminder-watch --interval 1.0 --max-sleep 30

---

Integration Commands

ClawReceipt pattern capture

python -m clawmemory.openclaw_bridge integration_capture_receipts --root memory <<'JSON'
{"events":[{"merchant":"Shopee","amount":500,"timestamp":"2026-01-25T10:00:00+00:00"},{"merchant":"Shopee","amount":700,"timestamp":"2026-02-26T10:00:00+00:00"}]}
JSON

ClawFlow cron setup

python -m clawmemory.openclaw_bridge integration_flow_cron_setup --root memory <<'JSON'
{"cron_expression":"0 9 * * *","job_name":"daily-report"}
JSON

ClawFlow failure follow-up

python -m clawmemory.openclaw_bridge integration_flow_job_failure --root memory <<'JSON'
{"job_name":"daily-report","fail_reason":"timeout","remind_in_seconds":300}
JSON

ClawWizard preference mode

python -m clawmemory.openclaw_bridge integration_wizard_preference --root memory <<'JSON'
{"mode":"interactive"}
JSON

ClawGraph entity sync

python -m clawmemory.openclaw_bridge integration_graph_sync --root memory <<'JSON'
{"entities":{"projects":[{"id":"p1","name":"ClawMemory","deadline":"2026-03-31"}],"clients":[{"id":"c1","name":"OpenKrab"}]}}
JSON

---

TUI Dashboard

(In progress) The TUI provides a rich terminal interface for managing your memories.

clawmemory tui

---

Semantic Backend Options

Default lightweight mode

No extra install needed.

Real local vector mode

pip install -e .[vector]
export CLAWMEMORY_VECTOR_BACKEND=chroma
export CLAWMEMORY_EMBED_MODEL=all-MiniLM-L6-v2

---

Project Structure

• clawmemory/store.py - storage + retrieval
• clawmemory/vector_semantic.py - semantic backend abstraction
• clawmemory/session_buffer.py - short-term memory buffer
• clawmemory/distill.py - distillation pipeline
• clawmemory/commitments.py - reminder engine
• clawmemory/integrations.py - ClawReceipt/Flow/Wizard capture helpers
• clawmemory/dashboard.py - local UI server
• clawmemory/openclaw_bridge.py - OpenClaw bridge command entrypoint
• index.js - OpenClaw runtime plugin bindings
• openclaw.plugin.json - OpenClaw plugin manifest
• skills/clawmemory/SKILL.md - skill instructions

---

Testing

pytest -q tests --capture=no

---

Contributing

PRs are welcome. Please include tests for behavior changes and keep self-host/privacy defaults intact.

---

Built for the Lobster Way 🦞