OpenMem v1.3.0#

SQLite-backed long-term memory.

MIT License — free to use, modify, redistribute. No attribution required.

Privacy & Scope#

Read this before installing.

• Full session transcripts are read during compression. Both manual ( compress.py read) and automated ( auto_compress.py) compression read the complete raw JSONL session files. The full content is passed to the extractor — everything in that session is visible. Only 3–10 selected items are written to the DB; the raw content is never stored permanently. This is intentional but privacy-sensitive: sessions may contain passwords, keys, or personal data entered during a conversation.

• Automated compression destroys original session files. auto_compress.py replaces session JSONL files older than 24h with a one-line stub after memories are confirmed. This is irreversible. Run with --no-wipe to disable this behaviour, or skip auto-compression entirely.

• Network calls are made during auto-compression. auto_compress.py calls openclaw capability model run to extract memories using the user's configured model. OpenClaw handles all provider routing and auth — session excerpts are passed as a prompt through the local gateway. The MCP server itself makes no network calls.

• Cache file is plaintext. After every memory write, top memories are written to openmem-cache.json in the same directory as the DB, unencrypted. Trust level is identical to the DB file.

• Persistent presence. setup.py registers an MCP server and an hourly cron job with your OpenClaw gateway. OpenMem has ongoing read access to session files and write access to the local DB while enabled. Run uninstall.py to remove all registered components.

Filesystem & Credential Access#

What this skill reads and writes — declared up-front.

Reads:

• ~/.openclaw/agents/main/sessions/*.jsonl — session transcripts, read in full during compression (see Privacy above).

Writes:

• ~/.openclaw/workspace/memory/openmem.db — SQLite memory database
• ~/.openclaw/workspace/memory/openmem-cache.json — plaintext top-memory cache, written after every memory write
• ~/.openclaw/workspace/memory/auto_compress_state.json — last-run state for the daily guard
• ~/.openclaw/logs/openmem-compress.log — compression log

All paths are overridable via env vars (see Environment Variables).

MCP Tool Calls#

When the OpenMem MCP server is registered, use these native tool calls directly:

ToolPurposememory_addStore a new memory (content, category, importance, source)memory_searchFTS search with relevance + importance + recency rankingmemory_updateChange content, category, or importance by IDmemory_deleteRemove a memory by IDmemory_listList memories sorted by importance / recency / accessmemory_statsTotal count, breakdown by category, date range

Installation#

After openclaw skills install openmem, run setup once:

bash

python3 ~/.openclaw/workspace/skills/openmem/scripts/setup.py

This creates the database, checks requirements, registers the MCP server, registers the auto-compression launchd job (macOS), and prints the next steps (hook enable).

Uninstall#

Removes the cron job, MCP server, and bootstrap hook. Your database is not deleted — its path is printed so you can export or remove it yourself.

bash

python3 ~/.openclaw/workspace/skills/openmem/scripts/uninstall.py

CLI Quick Reference#

bash

SCRIPTS=~/.openclaw/workspace/skills/openmem/scripts

# Add a memory
python3 $SCRIPTS/mem.py add "User prefers concise responses" --category preference

# Search
python3 $SCRIPTS/mem.py search "response style"

# List top memories
python3 $SCRIPTS/mem.py list --limit 20

# Stats
python3 $SCRIPTS/mem.py stats

# --- Session compression ---
# List uncompressed sessions
python3 $SCRIPTS/compress.py pending

# Read a session (then you summarize it into mem.py add calls)
python3 $SCRIPTS/compress.py read <session-id>

# Mark compressed after adding memories
python3 $SCRIPTS/compress.py mark-done <session-id> --memory-count 5

Categories#

fact · insight · preference · correction · event · general

Compression Workflow#

Automatic (default)#

After setup, an OpenClaw cron job runs auto_compress.py every hour (via --tools exec, so it can only run the script — no loops possible). The script itself handles all guards:

1. Checks it hasn't already run today
2. Checks the agent has been inactive for 2+ hours
3. Finds all uncompressed sessions (skipping the most recently active one)
4. Calls Ollama to extract 3–8 memories per session (falls back to heuristics if Ollama is unavailable)
5. Deduplicates each candidate against existing memories (word-overlap check)
6. Inserts and confirms each memory is in the DB before proceeding
7. Wipes sessions older than 24h to a stub after memories are confirmed
8. Logs everything to ~/.openclaw/logs/openmem-compress.log

To run it manually:

bash

python3 $SCRIPTS/auto_compress.py --force          # skip guards, compress now
python3 $SCRIPTS/auto_compress.py --dry-run        # preview without writing
python3 $SCRIPTS/auto_compress.py --no-wipe        # compress but keep session files

On-demand (agent)#

You can also trigger compression by saying:

• "compress my sessions"
• "save this to long-term memory"

Step by step:

1. python3 $SCRIPTS/compress.py pending — find sessions not yet compressed
2. python3 $SCRIPTS/compress.py read <id> — read the conversation
3. Extract 3–10 key facts, corrections, preferences, and insights
4. Use memory_add tool call (or mem.py add) for each memory
5. python3 $SCRIPTS/compress.py mark-done <id> --memory-count <N>

What to extract:

• Facts the user stated about their system, preferences, or projects
• Mistakes made and the correct approach
• Decisions reached and why
• Important events (deploys, incidents, milestones)

What to skip: Raw command output, transient errors, small talk.

Deduplication#

memory_add automatically checks for similar existing memories before inserting (word-overlap similarity ≥ 65%). If a near-duplicate is found, it returns the existing memory ID instead of inserting. Pass "check_duplicate": false to force an insert.

Importance Guide#

ScoreMeaning0.9–1.0Critical — always surface (key preferences, major corrections)0.7–0.8Important — surface often0.5–0.6Normal (default)0.3–0.4Low — background context0.0–0.2Archive only

OpenAuto Integration#

If OpenAuto is installed alongside OpenMem, the two work together:

• OpenAuto defers long-term writes to OpenMem — when memory_add is available, OpenAuto uses it instead of writing directly to MEMORY.md
• OpenMem replaces MEMORY.md searches — memory_search handles ranked FTS lookup so OpenAuto doesn't need to grep flat files
• Session compression feeds OpenMem — OpenAuto's Working Buffer and daily notes are the source material; saying "compress my sessions" extracts durable memories into OpenMem
• Bootstrap injection bridges both — OpenMem injects top memories as OPENMEM.md at session start, which OpenAuto reads alongside its own workspace files

Both skills work independently. If both are installed and OpenMem's MCP server is registered, the integration activates automatically — no extra setup required.

Bootstrap Hook#

The bootstrap hook auto-injects your top memories at session start.

Enable once:

bash

openclaw hooks enable openmem

Memories appear in OPENMEM.md at the start of every session. Control injection count with OPENMEM_BOOTSTRAP_LIMIT (default: 12).

Database Schema#

See references/schema.md for full schema details.

Environment Variables#

VariableDefaultDescriptionOPENMEM_DB``~/.openclaw/workspace/memory/openmem.dbDatabase pathOPENMEM_BOOTSTRAP_LIMIT``12Memories injected at bootstrapOPENMEM_SESSIONS_DIR``~/.openclaw/agents/main/sessionsSession files locationOPENMEM_COMPRESS_INACTIVITY``2Minimum inactivity hours before auto-compress runs