OpenMem - Longterm Compressed Memory

MCP Tools

SQLite long-term memory compression system for extended memory life. Adds tools for agents to control their memory functions.

Install

openclaw skills install openmem

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:

Tool	Purpose
`memory_add`	Store a new memory (content, category, importance, source)
`memory_search`	FTS search with relevance + importance + recency ranking
`memory_update`	Change content, category, or importance by ID
`memory_delete`	Remove a memory by ID
`memory_list`	List memories sorted by importance / recency / access
`memory_stats`	Total count, breakdown by category, date range

Installation

After openclaw skills install openmem, run setup once:

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.

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

CLI Quick Reference

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

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:

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

To run it manually:

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:

python3 $SCRIPTS/compress.py pending — find sessions not yet compressed
python3 $SCRIPTS/compress.py read <id> — read the conversation
Extract 3–10 key facts, corrections, preferences, and insights
Use memory_add tool call (or mem.py add) for each memory
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

Score	Meaning
0.9–1.0	Critical — always surface (key preferences, major corrections)
0.7–0.8	Important — surface often
0.5–0.6	Normal (default)
0.3–0.4	Low — background context
0.0–0.2	Archive 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:

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

Variable	Default	Description
`OPENMEM_DB`	`~/.openclaw/workspace/memory/openmem.db`	Database path
`OPENMEM_BOOTSTRAP_LIMIT`	`12`	Memories injected at bootstrap
`OPENMEM_SESSIONS_DIR`	`~/.openclaw/agents/main/sessions`	Session files location
`OPENMEM_COMPRESS_INACTIVITY`	`2`	Minimum inactivity hours before auto-compress runs