Clawd Memory

Clawd MemeBRain: local agent memory, a living markdown vault, realtime graph visualization, Solana research, OODA ingestion, and fast recall.

                 CLAWD BRAIN MEMORY LOOP

  user intent       OODA ticks        Solana research       agent decisions
      |                 |                   |                    |
      v                 v                   v                    v
  +-----------------------------------------------------------------------+
  |                         clawd-brain                                   |
  |  remember  ->  vault note  ->  SQLite bank  ->  recall  ->  action    |
  +-----------------------------------------------------------------------+
      |                 |                   |                    |
      v                 v                   v                    v
  preferences       risk notes        protocol docs        reusable context

Local-first memory for Clawd agents.

Clawd Memory is the persistent brain layer for Solana Clawd. It gives agents a durable memory bank, a living markdown vault, fast local recall, and a simple CLI for saving decisions, user preferences, wallet notes, protocol research, trading context, and agent operating state.

The storage engine is the existing mnemosyne Python package (compatibility name). The Clawd interface is clawd-brain, backed by the default clawd bank and a markdown vault at vault/ in this tree (or ~/.clawd/memory/vault when installed without the in-tree vault). Keep engine package/import names stable unless you are ready to migrate imports, plugin paths, and stored data.

Clawd MemeBRain Animation

The banner at the top of this README is assets/clawd-brain-memory.svg. It is the visual shorthand for the MemeBRain loop:

agent intent -> durable note -> SQLite memory bank -> recall -> realtime graph -> next action

The static animation and the live Open Clawd graph represent the same system at different resolutions. The SVG introduces the memory loop; clawd-brain visualize / open-memory renders the current vault, indexes, Clawd Open Memory rows, and Open Clawd plugin metadata as a realtime graph.

What It Does

• Stores agent memory locally in SQLite, with no required cloud database.
• Keeps a Clawd markdown vault with folders for research, signals, trades, agents, protocols, wallets, and perps.
• Gives every vault folder a README entry point so humans and agents know what belongs there.
• Recalls context with hybrid memory search and matching vault notes.
• Archives URLs and research prompts into durable notes.
• Imports OODA journal ticks into memory.
• Serves Clawd Open Memory — our local open-memory console + API (clawd-brain open-memory) with an OpenClawd realtime graph.
• Supports Hermes/MCP integrations through the existing Mnemosyne-compatible tools.
• Adds a provider-agnostic persistent memory system for trading, development, and enterprise workflows.
• Supports explicit Honcho import and Convex event sync adapters without making either provider the source of truth.

Persistent Memory System

clawd-brain system is the higher-level operating memory layer. It keeps the local Clawd vault and SQLite bank authoritative, then records typed events, cross-session handoffs, and auto-evolution proposals in vault/90-indexes/clawd-system.db.

Domains:

Domain	Use
trading	Signals, risk notes, trade decisions, wallet and perp context
development	Architecture, code decisions, tool state, build/test/deploy memory
enterprise	Customer, policy, compliance, SLA, team, and governance memory

Provider adapters:

Provider	Direction	Env
Local Clawd Memory	read/write	Always enabled
Honcho	pull/import	HONCHO_API_KEY, optional CLAWD_HONCHO_WORKSPACE_ID
Convex	push/pull event snapshots	CLAWD_MEMORY_CONVEX_URL or CONVEX_URL, optional CLAWD_MEMORY_CONVEX_TOKEN

Examples:

clawd-brain system capture "SOL Perp Risk" "Watch oracle drift and liquidity before sizing perp trades." --domain trading --event-type risk --tag jupiter
clawd-brain system handoff "Continue Convex sync implementation." --domain development --next-action "Run targeted tests"
clawd-brain system accept-handoff --domain development --accepted-by codex
clawd-brain system evolve --domain development --apply
clawd-brain system sync --provider convex --direction push --dry-run
clawd-brain system sync --provider honcho --direction pull --dry-run
clawd-brain system status

Auto-evolution is deterministic by default: it looks for repeated event patterns and can either stage proposals or apply them as durable Clawd notes. LLM/provider-backed refinement can be layered on top later, but the local path works without network access.

Living Vault

The vault is not a dump folder. It is the human-readable memory surface for the agent.

Start here:

• Vault README
• Agents
• Research
• Signals
• Indexes

Use wiki links such as [[OpenClawd]], [[Jupiter]], and [[Solana RPC]] to create graph edges. Use tags to make retrieval and filtering predictable. Keep 90-indexes machine-owned.

Clawd Open Memory

Clawd Open Memory is our local open-memory product (console + API + graph). It lives at mem0-main/openmemory/ and is backed by Clawd Memory — not a third-party SaaS.

clawd-brain open-memory
# opens http://127.0.0.1:3000/          console
#       http://127.0.0.1:3000/openclawd graph

Or:

clawd-open-memory --port 3000
python3 -m mnemosyne.openmemory_server

Default bridge DB: vault/90-indexes/openmemory.db (override with CLAWD_OPENMEMORY_DB).

The Open Clawd graph reads:

• Clawd vault notes and wiki links from vault/90-indexes/clawd-brain.db
• System events / handoffs from vault/90-indexes/clawd-system.db
• Mnemosyne engine rows from the active clawd bank
• Clawd Open Memory SQLite rows from openmemory.db
• Open Clawd plugin metadata from mem0-main/open-clawd

Graph-only (lighter):

clawd-brain visualize --port 8787

API when Open Memory is running:

GET  /api/v1/status
GET  /api/v1/memories
POST /api/v1/memories
GET  /api/v1/search?q=
POST /api/v1/sync
GET  /api/v1/openclawd/graph
GET  /api/v1/openclawd/events

See mem0-main/openmemory/README.md.

Quick Start

Clone this package tree, install editable, and run the short Clawd CLI path. Defaults resolve the in-tree vault/ and vault/90-indexes/mnemosyne-data automatically — no long --data-dir on every command.

git clone <this-repo-url> clawd-memory
cd clawd-memory          # directory that contains pyproject.toml and vault/
python3 -m pip install -e ".[dev]"

# Happy path (defaults: bank=clawd, vault=./vault)
clawd-brain init
clawd-brain remember "Jupiter Perps Risk" \
  "Track [[Jupiter]] liquidity, funding, route quality, and oracle failure modes." \
  --kind perp --tag solana --tag risk
clawd-brain recall "Jupiter perp risk"
clawd-brain status

Same path without the console script:

python3 -m mnemosyne.clawd_brain init
python3 -m mnemosyne.clawd_brain remember "User Preference" \
  "The user wants concise, direct engineering updates." --kind agent --tag preference
python3 -m mnemosyne.clawd_brain recall "user communication preferences"
python3 -m mnemosyne.clawd_brain status

Optional overrides (only when you need non-default locations):

export CLAWD_BRAIN_VAULT="$PWD/vault"
export CLAWD_BRAIN_DATA_DIR="$PWD/vault/90-indexes/mnemosyne-data"
clawd-brain research "https://docs.jup.ag/"
clawd-brain visualize --port 8787

Without an in-tree vault/, Clawd Memory uses ~/.clawd/memory/vault and co-located SQLite under ~/.clawd/memory/vault/90-indexes/mnemosyne-data.

Agent Memory Contract

Agents should use Clawd Memory deliberately:

• Recall before planning when the task involves a returning user, existing protocol research, wallet history, trading notes, or previous architecture decisions.
• Remember durable facts, preferences, decisions, risk findings, protocol notes, wallet labels, deployment details, and postmortems.
• Do not remember transient command output, secrets, raw API keys, private keys, or noisy stack traces unless the user explicitly asks for an incident record.
• Prefer short, factual memories with clear titles, tags, source, and kind.
• Use research for URLs and investigation topics that should become vault notes.
• Use ingest-ooda to convert OODA ticks into durable agent context.

Useful kinds:

Kind	Use
agent	Operating rules, user preferences, workflow decisions
research	URLs, protocol notes, market structure, docs
signal	Market, social, token, or infrastructure signal
trade	Trade plans, entry/exit rationale, post-trade review
protocol	Solana protocol knowledge and integration notes
wallet	Public wallet labels, behavior notes, portfolio context
perp	Perpetual venue, oracle, liquidation, funding, or route risk
note	General memory

Storage Layout

Clawd Memory writes to two local stores under the resolved vault:

vault/                          # CLAWD_BRAIN_VAULT or package vault/ or ~/.clawd/memory/vault
├── README.md
├── 00-inbox/
├── 10-research/
├── 20-signals/
├── 30-trades/
├── 40-agents/
├── 50-protocols/
├── 60-wallets/
├── 70-perps/
└── 90-indexes/
    ├── README.md
    ├── clawd-brain.db
    ├── clawd-system.db
    └── mnemosyne-data/         # default SQLite data dir for clawd-brain

Defaults for clawd-brain / ClawdBrain:

1. CLAWD_BRAIN_VAULT / CLAWD_BRAIN_DATA_DIR if set
2. Else package-tree vault/ and vault/90-indexes/mnemosyne-data when present
3. Else ~/.clawd/memory/vault and co-located …/90-indexes/mnemosyne-data
4. MNEMOSYNE_DATA_DIR still overrides the engine data path (Hermes/engine compatibility)

The default bank is clawd. Pure engine/Hermes code that never goes through Clawd may still use ~/.hermes/mnemosyne/data until you set MNEMOSYNE_DATA_DIR.

Important environment variables:

Variable	Purpose
CLAWD_BRAIN_VAULT	Override the markdown vault path
CLAWD_BRAIN_DATA_DIR	Override SQLite data dir for Clawd
MNEMOSYNE_DATA_DIR	Engine data-dir override (compatibility)
MNEMOSYNE_VEC_TYPE	Vector storage type: int8, float32, or bit
MNEMOSYNE_HOST_LLM_ENABLED	Let a host agent framework provide the LLM for consolidation
MNEMOSYNE_LLM_BASE_URL	OpenAI-compatible remote LLM base URL for consolidation
MNEMOSYNE_LLM_API_KEY	API key for the remote LLM endpoint
MNEMOSYNE_LLM_MODEL	Model identifier for consolidation

CLI Reference

clawd-brain --help
clawd-brain init
clawd-brain status
clawd-brain remember TITLE CONTENT --kind research --source clawd --tag solana --importance 0.8
clawd-brain recall QUERY --top-k 8
clawd-brain research URL_OR_TOPIC --tag solana
clawd-brain ingest-ooda --journal path/to/ticks.jsonl --limit 100
clawd-brain visualize --port 8787
clawd-brain open-memory --port 3000

Optional flags on every command:

--bank clawd
--vault path/to/vault
--data-dir path/to/sqlite-data

Python Usage

Use the Clawd layer for agent-facing memory:

from mnemosyne.clawd_brain import ClawdBrain

brain = ClawdBrain()
brain.remember(
    "Clawd Gateway",
    "The public worker endpoint is https://clawd.x402.wtf.",
    kind="agent",
    tags=["deployment", "worker"],
)

result = brain.recall("worker endpoint")
print(result)

Use the lower-level engine only when you need raw BEAM operations:

from mnemosyne import Mnemosyne

mem = Mnemosyne(bank="clawd", session_id="clawd-brain")
mem.remember("Raw engine memory", importance=0.5)
print(mem.recall("engine memory"))

Hermes And MCP

The Hermes plugin and MCP server still expose mnemosyne_* tool names for compatibility:

Tool	Clawd usage
mnemosyne_remember	Store durable Clawd agent memory
mnemosyne_recall	Retrieve relevant context before a response or action
mnemosyne_sleep	Consolidate working memory into episodic memory
mnemosyne_stats	Inspect memory state
mnemosyne_scratchpad_*	Use temporary reasoning workspace
mnemosyne_triple_*	Store/query temporal knowledge graph facts

For new Clawd-native code, prefer ClawdBrain or clawd-brain. For existing Hermes/MCP clients, keep the compatibility tool names.

Architecture

Clawd Memory has four layers:

Layer	Responsibility
Agent contract	When to recall, remember, research, and consolidate
Clawd brain layer	ClawdBrain, vault notes, tags, Solana/OODA metadata
Memory engine	BEAM working memory, episodic memory, scratchpad, hybrid recall
Persistence	SQLite databases and markdown vault files

See docs/architecture.md for details.

Docs

• Getting Started
• Architecture
• Configuration
• API Reference
• Hermes Integration
• LLM Agent Installation Guide
• Comparison Notes
• BEAM Benchmark

Compatibility Notes

• Product name: Clawd Memory
• Clawd CLI: clawd-brain
• Clawd Python class: mnemosyne.clawd_brain.ClawdBrain
• Default Clawd bank: clawd
• Default Clawd vault: package vault/ or ~/.clawd/memory/vault
• Engine package name (PyPI/import): mnemosyne-memory / mnemosyne — keep for compatibility
• Engine env prefix: MNEMOSYNE_* — keep for compatibility

This split is intentional. Clawd owns the agent memory workflow; the Mnemosyne engine name remains only so package metadata, import paths, Hermes adapters, and MCP clients stay stable.

Contributing

Public clone → install → test path is documented in CONTRIBUTING.md. Bug reports, docs fixes, and code for Clawd Memory are welcome.