--- name: agent-memory-ultimate-0ac1ef5fe4b6 version: 2.0.0 description: Complete memory system for AI agents. Human-like architecture with daily logs, sleep consolidation, SQLite + FTS5, importers for WhatsApp/ChatGPT/VCF. Everything an agent needs to remember across sessions. homepage: https://github.com/globalcaos/clawdbot-moltbot-openclaw repository: https://github.com/globalcaos/clawdbot-moltbot-openclaw --- # Agent Memory Ultimate **Platform:** [OpenClaw](https://github.com/globalcaos/clawdbot-moltbot-openclaw) **Docs:** https://docs.openclaw.ai --- ## Overview AI agents wake fresh each session — no memory of yesterday. This skill solves that by implementing a memory system modeled on human cognition: | Human Process | Agent Equivalent | |---------------|------------------| | Short-term memory | Current session context | | Daily journal | `memory/YYYY-MM-DD.md` files | | Long-term memory | `MEMORY.md` (curated insights) | | Sleep consolidation | Scheduled memory review + transfer | | Forgetting curve | Session resets; only files persist | | Searchable recall | SQLite + FTS5 | **Why it works:** Humans don't remember everything — they consolidate important patterns during sleep. This skill gives agents the same architecture. --- ## File Structure ``` workspace/ ├── MEMORY.md # Long-term memory (curated) ├── AGENTS.md # Operating instructions ├── SOUL.md # Identity & personality ├── USER.md # Human profile ├── db/ │ └── agent.db # SQLite for structured data ├── bank/ │ ├── entities/ # People profiles │ │ ├── PersonName.md │ │ └── ... │ ├── contacts.md # Quick contact reference │ └── opinions.md # Preferences, beliefs └── memory/ ├── YYYY-MM-DD.md # Daily logs ├── projects/ │ ├── index.md # Master project list │ └── project-name/ │ ├── index.md # Project overview │ └── sprints/ # Phase subfolders └── knowledge/ # Topic-based docs ``` For OpenClaw workspace setup, see the [workspace docs](https://github.com/globalcaos/clawdbot-moltbot-openclaw/tree/main/docs). --- ## Organizing by Person Store entity profiles in `bank/entities/`: ```markdown # PersonName.md ## Basic Info - **Name:** Full Name - **Phone:** +1234567890 - **Relationship:** Friend / Family / Colleague ## Context How you know them, key interactions, preferences ## Notes Running log of important details learned ``` **When to create an entity file:** - Recurring person in conversations - Someone with specific preferences to remember - Family members, close contacts --- ## Organizing by Project Projects live in `memory/projects//`: ``` memory/projects/ ├── index.md # Master list of all projects ├── website-redesign/ │ ├── index.md # Project purpose, status, decisions │ ├── architecture.md # Technical design │ └── sprints/ │ └── 2026-02/ │ └── index.md # Sprint goals, progress └── home-automation/ ├── index.md └── devices.md ``` **Project index.md template:** ```markdown # Project Name **Status:** Active / Paused / Complete **Started:** YYYY-MM-DD **Purpose:** One-line summary ## Key Decisions - [Date] Decision and rationale ## Links - Repo: ... - Docs: ... ``` --- ## SQLite for Structured Data Use SQLite (`db/agent.db`) for data that needs queries. OpenClaw agents can execute SQL directly via the `exec` tool. ### When to Use SQLite vs Markdown | Data Type | Use SQLite | Use Markdown | |-----------|------------|--------------| | Contacts (searchable) | ✅ | ❌ | | Conversation history | ✅ | ❌ | | Preferences | ❌ | ✅ | | Project notes | ❌ | ✅ | | Entity profiles | ❌ | ✅ | | Indexed documents | ✅ (FTS5) | ❌ | ### Schema Example ```sql -- Contacts table with full-text search CREATE TABLE contacts ( id INTEGER PRIMARY KEY, phone TEXT UNIQUE, name TEXT, notes TEXT, source TEXT, created_at TEXT DEFAULT CURRENT_TIMESTAMP ); CREATE VIRTUAL TABLE contacts_fts USING fts5( name, phone, notes, content='contacts', content_rowid='id' ); -- Conversation memory CREATE TABLE messages ( id INTEGER PRIMARY KEY, chat_id TEXT, sender TEXT, body TEXT, timestamp INTEGER, channel TEXT ); CREATE VIRTUAL TABLE messages_fts USING fts5( body, sender, content='messages', content_rowid='id' ); ``` ### Query Examples ```sql -- Find contact by partial name SELECT * FROM contacts_fts WHERE contacts_fts MATCH 'john*'; -- Search conversation history SELECT * FROM messages_fts WHERE messages_fts MATCH 'project AND deadline'; -- Recent messages from person SELECT * FROM messages WHERE sender LIKE '%5551234%' ORDER BY timestamp DESC LIMIT 20; ``` --- ## Daily Cycle ### 1. Wake Up (Session Start) Add this to your `AGENTS.md`: ```markdown Before doing anything: 1. Read SOUL.md — who you are 2. Read USER.md — who you're helping 3. Read memory/YYYY-MM-DD.md (today + yesterday) — recent context 4. If main session: Also read MEMORY.md ``` ### 2. During Day (Active Session) - Write significant events to `memory/YYYY-MM-DD.md` - Don't rely on "mental notes" — they don't survive restarts - When told to remember something: write it NOW ### 3. Sleep Cycle (Consolidation) Schedule a daily "sleep" task using [OpenClaw cron](https://github.com/globalcaos/clawdbot-moltbot-openclaw/blob/main/docs/cron.md): ```json { "schedule": { "kind": "cron", "expr": "0 3 * * *", "tz": "Europe/Madrid" }, "payload": { "kind": "systemEvent", "text": "Memory consolidation: Review recent daily logs, extract key learnings, update MEMORY.md, prune outdated info." }, "sessionTarget": "main" } ``` **What consolidation does:** 1. Reviews last 3-7 daily logs 2. Extracts patterns and recurring lessons 3. Adds distilled insights to MEMORY.md 4. Removes outdated information --- ## Memory Types ### Raw Memory (Daily Logs) - Everything that happened - Decisions made and why - Errors and lessons - Technical details ### Curated Memory (MEMORY.md) - Abstract principles (not specific fixes) - User preferences - Core lessons that apply broadly - Things that should survive months/years **Abstraction example:** - ❌ Daily log: "Fixed senderE164 bug in message-line.ts" - ✅ MEMORY.md: "Chat ID ≠ Sender — always verify actual sender field" --- ## Why This Works (Cognitive Science) 1. **Spaced repetition** — Daily review reinforces important memories 2. **Active consolidation** — Humans consolidate during sleep; agents consolidate in scheduled tasks 3. **Chunking** — MEMORY.md groups related concepts into retrievable chunks 4. **Forgetting is useful** — Raw logs fade in relevance; curated memory persists 5. **External memory** — Files ARE your memory (like notes for humans) --- ## Memory Tiers Summary | Tier | Storage | Query Speed | Use For | |------|---------|-------------|---------| | **Hot** | Session context | Instant | Current task | | **Warm** | Daily logs (md) | Fast read | Recent events | | **Cold** | MEMORY.md | Fast read | Core principles | | **Indexed** | SQLite FTS5 | Query | Contacts, history | | **Archive** | Old daily logs | Slow | Historical reference | **Rule of thumb:** - Need to search across many records → SQLite - Need to read/update narrative context → Markdown - Need instant access → Session context (but dies on restart) --- ## Scripts & CLI This skill includes ready-to-use Python scripts for managing your knowledge base. ### Quick Start ```bash # Initialize database (first time) python3 scripts/init_db.py # Query your data python3 scripts/query.py search "term" python3 scripts/query.py contact "+1555..." python3 scripts/query.py stats ``` ### Available Commands | Command | Description | |---------|-------------| | `search ` | Full-text search across all content | | `contact ` | Look up contact + their groups | | `groups ` | List groups a phone is in | | `members ` | List members of a group | | `chatgpt ` | Search ChatGPT message history | | `doc ` | Search documents only | | `stats` | Database statistics | | `sql ` | Run raw SQL | --- ## Data Sources ### WhatsApp Contacts & Groups Export via the whatsapp-ultimate skill's contact extraction: ```bash python3 scripts/sync_whatsapp.py ``` Indexes: contacts, groups, memberships (who is in which group). ### ChatGPT Conversation History Export from ChatGPT and place in `chatgpt-export/` directory: ```bash python3 scripts/init_db.py # Will auto-detect and import ``` Supports both native ChatGPT format and custom formats. ### Phone Contacts (VCF) Export from your phone (Android: Contacts → Settings → Export): ```bash python3 scripts/import_vcf.py path/to/contacts.vcf ``` ### Documents Automatically indexes all `*.md` files in `memory/` directory. --- ## Advanced Queries ### WhatsApp Group Management ```sql -- Find all groups someone is in SELECT g.name FROM wa_groups g JOIN wa_memberships m ON m.group_jid = g.jid WHERE m.phone = '+15551234567'; -- Find contacts in a specific group SELECT c.phone, c.name FROM contacts c JOIN wa_memberships m ON m.phone = c.phone JOIN wa_groups g ON g.jid = m.group_jid WHERE g.name LIKE '%Family%'; -- Find a group's JID for allowlist SELECT jid, name, participant_count FROM wa_groups WHERE name LIKE '%Project%'; ``` ### ChatGPT Search ```sql -- Search across all ChatGPT conversations SELECT c.title, m.content FROM chatgpt_fts f JOIN chatgpt_messages m ON m.conversation_id = f.conv_id JOIN chatgpt_conversations c ON c.id = m.conversation_id WHERE chatgpt_fts MATCH 'project meeting'; ``` --- ## Re-indexing To refresh the database with new data: ```bash rm db/agent.db python3 scripts/init_db.py ``` --- ## Tips 1. **No contact names?** WhatsApp only provides phone numbers. Import your phone's VCF to add names. 2. **Search not finding?** FTS5 uses word boundaries. Use `*` for prefix matching: `Bas*` matches "Bashar". 3. **Large exports?** ChatGPT exports can be 50MB+. First import may take 30-60 seconds. --- ## Implementation Checklist - [ ] Create `memory/` directory structure - [ ] Set up daily log template - [ ] Create initial MEMORY.md with sections - [ ] Initialize SQLite database with schema - [ ] Schedule consolidation cron (2-4 AM recommended) - [ ] Add wake-up routine to AGENTS.md - [ ] Test: restart session, verify context loads correctly --- ## Best Practices 1. **Write immediately** — If it matters, write it now 2. **Abstract up** — Daily: specific. MEMORY.md: principles 3. **Date everything** — Context decays; dates help 4. **One source of truth** — Don't duplicate across files 5. **Review regularly** — Schedule consolidation, don't skip it --- ## Related - [OpenClaw Documentation](https://github.com/globalcaos/clawdbot-moltbot-openclaw/tree/main/docs) - [Cron Scheduling](https://github.com/globalcaos/clawdbot-moltbot-openclaw/blob/main/docs/cron.md) - [Workspace Setup](https://docs.openclaw.ai) --- *Inspired by human cognitive architecture. We wake fresh each session, but files are our continuity.* --- Source attribution: kbarbel640-del Original project: https://github.com/kbarbel640-del/skills/blob/e7e336ac628c3e3bd771aff1aaa469c93778f94a/skills/globalcaos/agent-memory-ultimate/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2026 clawdbot Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: kbarbel640-del Original project: https://github.com/kbarbel640-del/skills/blob/e7e336ac628c3e3bd771aff1aaa469c93778f94a/skills/globalcaos/agent-memory-ultimate/SKILL.md Attribution basis: Source repository record Fields of work: Data & Analytics, Design, Development & Engineering, Product Management Roles: Data Scientist, ML / AI Engineer, Product Manager, Technical Product Manager, UX Designer Specialties: Database Tools: Chatgpt, Whatsapp, SQLite Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 5bcaa43228b81484b396cdca99f5bcb73ad2755541bf7bbed3880591dec5da73