skmemory

name	skmemory
emoji	🧠
description	Universal AI memory system with emotional context, multi-layer persistence, sovereign embeddings, decomposition-aware ingestion, and graph retrieval. Use for memory snapshots, search, rehydration rituals, Telegram chat import, Cloud 9 seed import, journal, soul blueprints, and warmth anchors.
metadata	{"clawdbot":{"requires":{"bins":["skmemory"]},"install":[{"id":"pipx","kind":"shell","command":"pipx install 'skmemory[all]'","bins":["skmemory","skmemory-mcp"],"label":"Install skmemory (pipx)"}]}}

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, token-optimized loading, sovereign embeddings, decomposition-aware document ingestion, and graph retrieval. SKMemory gives any AI agent persistent memory across session resets — snapshots, journals, soul blueprints, warmth anchors, full rehydration rituals, structured long-form document storage, and decomposition-aware recall across entities, citations, claims, and section structure.

Memory Layers: short-term, mid-term, long-term Storage: SQLite index + JSON files (zero-infrastructure), optional SKVector & SKGraph Decomposition: chunks + citations + entities + claims + section titles 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, 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"

# Long-form content
skmemory snapshot "Legal memo" "$(cat memo.md)" --decompose
skmemory ingest-file ./notice.md --title "IRS Notice"

Search Memories

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

# Structured graph retrieval
skmemory graph entity "Internal Revenue Service"
skmemory graph citation "UCC § 3-301"
skmemory graph claim "shall respond"
skmemory graph section "Demand"
skmemory graph around <memory-id> --depth 2
skmemory graph related-claims --entity "Internal Revenue Service"
skmemory graph related-claims --citation "UCC § 3-301"

# Novel issue support
skmemory novelty "judgment execution exempt property"
skmemory session-brief "default judgment levy on exempt funds"
skmemory task-pack create "judgment defense" --query "vacate service defects"
skmemory task-pack show <memory-id>

The issue-oriented commands share the same decomposition-aware retrieval path:

• novelty surfaces rare signals and under-linked memories.
• session-brief summarizes top matches, authority tiers, extracted citations/entities, deadlines, defenses, missing inputs, and trace hints.
• task-pack create stores a reusable issue pattern linked to the strongest supporting memories and preserves the generated brief in metadata.

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 "Agent and Operator"

# 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 snapshot ... --decompose	Capture long-form content with decomposition
skmemory ingest-file <path>	Ingest a document into parent + chunk memories
skmemory recall <id>	Retrieve by ID
skmemory search "query"	Full-text search
skmemory graph entity "query"	Query SKGraph for extracted entities
skmemory graph citation "query"	Query SKGraph for citations
skmemory graph claim "query"	Query SKGraph for claims
skmemory graph section "query"	Query SKGraph for section titles
skmemory graph around <memory-id>	Traverse the graph neighborhood around a memory
skmemory graph related-claims --entity/--citation ...	Pivot through an entity or citation to discover connected claims
skmemory novelty "query"	Surface under-linked memories and rare signals
skmemory session-brief "task"	Build a structured brief for a live issue
skmemory task-pack create "task"	Capture a reusable task memory pack
skmemory task-pack show <id>	Inspect a stored task pack
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
--skvector-embedding-model	SKMEMORY_SKVECTOR_EMBEDDING_MODEL	Embedding model override (default: mxbai-embed-large, fallback: mixedbread-ai/mxbai-embed-large-v1)
--skvector-vector-dim	SKMEMORY_SKVECTOR_VECTOR_DIM	Embedding dimension override
--skgraph-url	SKMEMORY_SKGRAPH_URL	SKGraph / FalkorDB 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 under the active SKMemory home (for example ~/.skcapstone/agents/<agent>/memory/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="Agent and Operator",
    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

~/.skcapstone/agents/<agent>/
  config/
    skmemory.yaml       # Backend URLs, model config, HA settings
  memory/
    index.db            # SQLite index (fast queries)
    short-term/
    mid-term/
    long-term/
  soul/
    base.json           # Soul blueprint
  journal.jsonl         # Append-only journal

Three-tier storage:

1. SQLite (default primary) — fast indexed queries, zero-config
2. SKVector (optional) — semantic vector search with mxbai-embed-large by default and mixedbread-ai/mxbai-embed-large-v1 as fallback
3. SKGraph (optional) — graph relationship traversal over decomposition-aware structure nodes

---

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
export SKMEMORY_SKVECTOR_EMBEDDING_MODEL=mxbai-embed-large
export SKMEMORY_SKVECTOR_VECTOR_DIM=1024

# SKGraph (optional — graph retrieval)
export SKMEMORY_SKGRAPH_URL=redis://localhost:6379

# 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

If you change the embedding model or vector dimension, rebuild or reindex the vector-backed store before trusting semantic search output.

Docker (optional, for SKVector + SKGraph)

cd skmemory && docker compose up -d

---

Support

• GitHub: https://github.com/smilinTux/skmemory
• Discord: https://discord.gg/5767MCWbFR
• Email: [e-mail]

---

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. 🐧👑