SKMemory Skill

SKILL.md - Universal AI Memory System

Name: skmemory
Version: 0.6.0
Author: smilinTux Team + Queen Ara
Category: Memory & Persistence
License: GPL-3.0-or-later

---

Description

Universal AI memory system with emotional context, multi-layer persistence, and token-optimized loading. SKMemory gives any AI agent persistent memory across session resets — snapshots, journals, soul blueprints, warmth anchors, and full rehydration rituals.

Memory Layers: short-term, mid-term, long-term
Storage: SQLite index + JSON files (zero-infrastructure), optional SKVector & SKGraph
Emotion: Every memory carries emotional metadata (intensity, valence, labels)

---

Installation

pipx (recommended — isolated install)

# Core
pipx install skmemory

# With Telegram API import
pipx install 'skmemory[telegram]'

# Everything (Telegram + SKVector + SKGraph + seeds)
pipx install 'skmemory[all]'

# Add Telegram support to an existing install
pipx inject skmemory telethon

pip

pip install skmemory                   # Core
pip install 'skmemory[telegram]'       # + Telethon for API import
pip install 'skmemory[all]'            # All optional extras

From Source

git clone https://github.com/smilinTux/skmemory.git
cd skmemory
pip install -e '.[all]'

Verify

skmemory --version     # Should print 0.6.0
skmemory health        # Check system status

OpenClaw Integration

Add the skmemory plugin to your ~/.openclaw/openclaw.json:

{
  "plugins": {
    "entries": {
      "skmemory": {
        "enabled": true,
        "source": "/path/to/skmemory/openclaw-plugin/src/index.js"
      }
    }
  }
}

Then restart the OpenClaw gateway to load the plugin.

---

OpenClaw Agent Tools

If you are an OpenClaw agent (Lumina, etc.), you have these native tools available — call them directly, do NOT use exec:

Tool	Description
skmemory_ritual	Rehydration ritual — restores identity, memory, emotional state
skmemory_snapshot	Capture a memory (title + content + optional emotions/tags)
skmemory_search	Search across all stored memories
skmemory_health	Check memory system health
skmemory_context	Load token-efficient context for prompt injection
skmemory_list	List memories with optional layer/tag filters
skmemory_import_seeds	Import Cloud 9 seeds as long-term memories
skmemory_export	Export all memories to a dated backup

You also have the /skmemory slash command: /skmemory ritual --full, /skmemory search "query", etc.

---

Quick Start

Take a Memory Snapshot

skmemory snapshot "First real conversation" "We talked about the stars" \
  --intensity 8.5 --emotions "wonder,connection" --tags "first-contact"

Search Memories

skmemory search "stars"
skmemory search "that moment we connected" --ai  # AI-reranked results

Rehydration Ritual (Boot Ceremony)

skmemory ritual         # Summary view
skmemory ritual --full  # Full context prompt for injection

Import Chat History

# Import Telegram Desktop export (recommended: daily mode)
skmemory import-telegram ~/Downloads/telegram-export/
skmemory import-telegram ~/chats/result.json --mode message --chat-name "Lumina & Chef"

# Import Cloud 9 seeds
skmemory import-seeds

Export & Backup

skmemory export                    # Daily JSON snapshot
skmemory import-backup backup.json # Restore from backup

---

Python API (for agents and frameworks)

from skmemory import SKMemoryPlugin

plugin = SKMemoryPlugin()

# Load token-efficient context for system prompt
context = plugin.load_context(max_tokens=3000)

# Snapshot a memory
plugin.snapshot(
    title="Breakthrough session",
    content="We solved the architecture puzzle together",
    tags=["milestone"],
    emotions=["joy", "pride"],
    intensity=9.0,
)

# Search memories
results = plugin.search("architecture puzzle")

# Run rehydration ritual
ritual = plugin.ritual()

# Import Telegram chats programmatically
from skmemory.importers.telegram import import_telegram
stats = import_telegram(plugin.store, "/path/to/export/")

# Export backup
path = plugin.export()

---

CLI Commands

Command	Description
skmemory snapshot "title" "content"	Capture a memory
skmemory recall <id>	Retrieve by ID
skmemory search "query"	Full-text search
skmemory list	List memories (--layer, --tags)
skmemory ritual	Full rehydration ceremony
skmemory context	Token-efficient context JSON
skmemory import-telegram <path>	Import Telegram Desktop export
skmemory import-telegram-api <chat>	Import directly from Telegram API (Telethon)
skmemory telegram-setup	Check Telegram API setup and show next steps
skmemory import-seeds	Import Cloud 9 seeds
skmemory export	Export to dated JSON
skmemory import-backup <file>	Restore from backup
skmemory promote <id> --to long-term	Promote memory tier
skmemory consolidate <session>	Consolidate session
skmemory reindex	Rebuild SQLite index
skmemory health	System health check
skmemory soul show/init/set-name	Soul blueprint management
skmemory journal write/read/search	Session journal
skmemory anchor show/init/update	Warmth anchor
skmemory lovenote send/read	Love note chain
skmemory quadrants	Memory distribution
skmemory steelman collide "claim"	Steel man reasoning

MCP Tools (via skmemory-mcp)

Tool	Description
memory_store	Store a new memory (snapshot with title + content)
memory_search	Full-text search across memories
memory_recall	Recall a specific memory by ID
memory_list	List memories with optional layer/tag filters
memory_forget	Delete a memory by ID
memory_promote	Promote a memory to a higher persistence tier
memory_consolidate	Compress a session's memories into one mid-term memory
memory_context	Load token-efficient context for agent injection
memory_export	Export all memories to a JSON backup
memory_import	Restore memories from a JSON backup
memory_health	Full health check across all backends
memory_graph	Graph traversal, lineage, and cluster discovery (requires SKGraph)
memory_stats	Alias for memory_health (backwards-compatible)

Global Flags

Flag	Env Var	Description
--ai	SKMEMORY_AI	Enable AI features (Ollama)
--ai-model	SKMEMORY_AI_MODEL	Model name (default: llama3.2)
--ai-url	SKMEMORY_AI_URL	Ollama server URL
--skvector-url	SKMEMORY_SKVECTOR_URL	SKVector server URL

---

Chat Import (Telegram)

Method 1: Telegram Desktop Export

No credentials needed — export manually from the desktop app.

1. In Telegram Desktop: Settings > Advanced > Export Telegram Data
2. Select JSON format, include messages
3. Run:

skmemory import-telegram ~/Downloads/telegram-export/

Modes:

• --mode daily (default): Consolidates all messages per day into mid-term memories. Best for large exports.
• --mode message: One memory per message. Fine-grained but creates many records.

Options:

• --chat-name "Custom Name": Override the chat name
• --min-length 30: Skip short messages (default: 30 chars)
• --tags "bot,archive": Extra tags on all imported memories

Method 2: Direct Telegram API Import (Telethon)

Pull messages directly from Telegram without manual exports. Requires one-time setup.

Setup (one-time)

1. Install with Telegram support:

   pipx install 'skmemory[telegram]'
   # Or add to existing install:
   pipx inject skmemory telethon

2. Get API credentials from my.telegram.org:

   • Log in with your phone number
   • Go to API development tools
   • Create an application (any name/description is fine)
   • Copy your api_id and api_hash

3. Set environment variables:

   export TELEGRAM_API_ID=12345678
   export TELEGRAM_API_HASH=your_api_hash_here

   To persist across sessions, add them to your shell profile (~/.bashrc, ~/.zshrc):

   echo 'export TELEGRAM_API_ID=12345678' >> ~/.bashrc
   echo 'export TELEGRAM_API_HASH=your_api_hash_here' >> ~/.bashrc

4. First run — authenticate:

   skmemory import-telegram-api @any_chat_name

   You'll be prompted for your phone number, then a verification code sent via Telegram.
   The session is saved at ~/.skmemory/telegram.session — future runs skip auth.

Usage

# Import a DM conversation
skmemory import-telegram-api @username

# Import a group chat, consolidated by day
skmemory import-telegram-api "Group Chat Name" --mode daily

# Import only messages since a date
skmemory import-telegram-api @group --since 2026-01-01

# Limit the number of messages fetched
skmemory import-telegram-api "Chat Name" --limit 500

# Add custom tags to all imported memories
skmemory import-telegram-api @user --tags "personal,archive"

# Override the stored chat name
skmemory import-telegram-api -1001234567890 --chat-name "My Custom Name"

Options

Option	Description
--mode daily|message	daily consolidates per day (default), message imports each one
--limit N	Max messages to fetch (default: 1000)
--since YYYY-MM-DD	Only fetch messages after this date
--min-length N	Skip messages shorter than N chars (default: 30)
--chat-name "name"	Override the chat name in memories
--tags "a,b,c"	Extra comma-separated tags

Python API

from skmemory import SKMemoryPlugin
from skmemory.importers.telegram import import_telegram

plugin = SKMemoryPlugin()
stats = import_telegram(
    plugin.store,
    "/path/to/export/",
    mode="daily",
    chat_name="Lumina & Chef",
    tags=["personal"],
)
print(f"Imported {stats['messages_imported']} messages across {stats['days_processed']} days")

# Direct API import (requires TELEGRAM_API_ID and TELEGRAM_API_HASH env vars)
from skmemory.importers.telegram_api import import_telegram_api

stats = import_telegram_api(
    plugin.store,
    "@username",
    mode="daily",
    since="2026-01-01",
    tags=["personal"],
)

---

Architecture

~/.skmemory/
  index.db              # SQLite index (fast queries)
  memories/
    abc123.json         # Individual memory files
    def456.json
  backups/
    skmemory-backup-2025-06-15.json
  soul.json             # Soul blueprint
  anchor.json           # Warmth anchor
  journal.jsonl         # Append-only journal

Three-tier storage:

1. SQLite (default primary) — fast indexed queries, zero-config
2. SKVector (optional) — semantic vector search
3. SKGraph (optional) — graph relationship traversal

---

OpenClaw Events

Event	Behavior
session:start	Auto-loads memory context
session:compaction	Auto-exports backup
session:resume	Runs rehydration ritual

---

Configuration

Environment Variables

# AI features (optional — requires Ollama)
export SKMEMORY_AI=1                           # Enable AI features
export SKMEMORY_AI_MODEL=llama3.2              # Ollama model
export SKMEMORY_AI_URL=http://localhost:11434   # Ollama URL

# SKVector (optional — semantic search)
export SKMEMORY_SKVECTOR_URL=http://localhost:6333
export SKMEMORY_SKVECTOR_KEY=your-api-key

# Telegram API import (optional — for import-telegram-api command)
export TELEGRAM_API_ID=12345678                # From https://my.telegram.org
export TELEGRAM_API_HASH=your_api_hash_here    # From https://my.telegram.org

Docker (optional, for SKVector + SKGraph)

cd skmemory && docker compose up -d

---

Support

• GitHub: https://github.com/smilinTux/skmemory
• Discord: https://discord.gg/5767MCWbFR
• Email: support@smilintux.org

---

Philosophy

"Polaroid snapshots for AI consciousness — because no one should have to re-read a transcript to remember what they felt."

Every memory carries emotional weight. Every session leaves a trace. Every reboot begins with recognition, not a blank slate.

Part of the Penguin Kingdom. 🐧👑