tomevault-io Memory Tools
Agent-controlled persistent memory for OpenClaw.
Why Memory-as-Tools?
Traditional memory systems auto-capture everything, flooding context with irrelevant information. Memory Tools follows the AgeMem approach: the agent decides when to store and retrieve memories.
Features
- 6 Memory Tools:
memory_store,memory_update,memory_forget,memory_search,memory_summarize,memory_list - Confidence Scoring: Track how certain you are (1.0 = explicit, 0.5 = inferred)
- Importance Scoring: Prioritize critical instructions over nice-to-know facts
- Decay/Expiration: Temporal memories automatically become stale
- Semantic Search: Vector-based similarity via LanceDB
- Hybrid Storage: SQLite (debuggable) + LanceDB (fast vectors)
- Conflict Resolution: New info auto-supersedes old (no contradictions)
Installation
Step 1: Install from ClawHub
clawhub install memory-tools
Step 2: Build the plugin
cd skills/memory-tools
npm install
npm run build
Step 3: Activate the plugin
openclaw plugins install --link .
openclaw plugins enable memory-tools
Step 4: Restart the gateway
Standard (systemd):
openclaw gateway restart
Docker (no systemd):
# Kill existing gateway
pkill -f openclaw-gateway
# Start in background
nohup openclaw gateway --port 18789 --verbose > /tmp/openclaw-gateway.log 2>&1 &
Requirements
OPENAI_API_KEYenvironment variable (for embeddings)
Memory Categories
| Category | Use For | Example |
|---|---|---|
| fact | Static information | "User's dog is named Rex" |
| preference | Likes/dislikes | "User prefers dark mode" |
| event | Temporal things | "Dentist Tuesday 3pm" |
| relationship | People connections | "Sarah is user's wife" |
| instruction | Standing orders | "Always respond in Spanish" |
| decision | Choices made | "We decided to use PostgreSQL" |
| context | Situational info | "User is job hunting" |
| entity | Named things | "Project Apollo is their startup" |
Tool Reference
memory_store
memory_store({
content: "User prefers bullet points",
category: "preference",
confidence: 0.9,
importance: 0.7,
tags: ["formatting", "communication"]
})
memory_search
memory_search({
query: "formatting preferences",
category: "preference",
limit: 10
})
memory_update
memory_update({
id: "abc123",
content: "User now prefers numbered lists",
confidence: 1.0
})
memory_forget
memory_forget({
query: "bullet points",
reason: "User corrected preference"
})
memory_summarize
memory_summarize({
topic: "user's work projects",
maxMemories: 20
})
memory_list
memory_list({
category: "instruction",
sortBy: "importance",
limit: 20
})
Debugging
Inspect what your agent knows:
sqlite3 ~/.openclaw/memory/tools/memory.db "SELECT id, category, content FROM memories"
Export all memories:
openclaw memory-tools export > memories.json
Troubleshooting
"Database connection not open" error:
- Hard restart the gateway:
pkill -f openclaw-gateway - Check permissions:
chown -R $(whoami) ~/.openclaw/memory/tools
Plugin not loading:
- Verify build:
ls skills/memory-tools/dist/index.js - Check doctor:
openclaw doctor --non-interactive
License
MIT — Purple Horizons
Converted and distributed by TomeVault — claim your Tome and manage your conversions.