@smilintux/skmemory 0.5.0 → 0.9.2

package/SKILL.md

@@ -1,11 +1,18 @@
+---
+name: skmemory
+emoji: 🧠
+description: Universal AI memory system with emotional context, multi-layer persistence, and token-optimized loading. 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.5.0  
-**Author:** smilinTux Team + Queen Ara  
-**Category:** Memory & Persistence  
-**License:** AGPL-3.0
+**Name:** skmemory
+**Version:** 0.6.0
+**Author:** smilinTux Team + Queen Ara
+**Category:** Memory & Persistence
+**License:** GPL-3.0-or-later
 
 ---
 
@@ -13,18 +20,36 @@
 
 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 Qdrant & FalkorDB  
+**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
 
-### Python (recommended)
+### pipx (recommended — isolated install)
 
 ```bash
-pip install skmemory
+# 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
+
+```bash
+pip install skmemory                   # Core
+pip install 'skmemory[telegram]'       # + Telethon for API import
+pip install 'skmemory[all]'            # All optional extras
 ```
 
 ### From Source
@@ -32,20 +57,54 @@ pip install skmemory
 ```bash
 git clone https://github.com/smilinTux/skmemory.git
 cd skmemory
-pip install -e .
+pip install -e '.[all]'
 ```
 
-### OpenClaw Integration
+### Verify
 
 ```bash
-# Python plugin (automatic on pip install)
-pip install skmemory
+skmemory --version     # Should print 0.6.0
+skmemory health        # Check system status
+```
+
+### OpenClaw Integration
 
-# JavaScript plugin
-cd openclaw-plugin && npm install
-openclaw skill add skmemory --path ~/.openclaw/plugins/skmemory
+Add the skmemory plugin to your `~/.openclaw/openclaw.json`:
+
+```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
@@ -136,7 +195,9 @@ path = plugin.export()
 | `skmemory list` | List memories (--layer, --tags) |
 | `skmemory ritual` | Full rehydration ceremony |
 | `skmemory context` | Token-efficient context JSON |
-| `skmemory import-telegram <path>` | Import Telegram export |
+| `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 |
@@ -151,6 +212,24 @@ path = plugin.export()
 | `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 |
@@ -158,13 +237,15 @@ path = plugin.export()
 | `--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 |
-| `--qdrant-url` | `SKMEMORY_QDRANT_URL` | Qdrant server URL |
+| `--skvector-url` | `SKMEMORY_SKVECTOR_URL` | SKVector server URL |
 
 ---
 
-## Chat Import (Telegram, etc.)
+## Chat Import (Telegram)
+
+### Method 1: Telegram Desktop Export
 
-### 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
@@ -183,6 +264,77 @@ skmemory import-telegram ~/Downloads/telegram-export/
 - `--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:**
+   ```bash
+   pipx install 'skmemory[telegram]'
+   # Or add to existing install:
+   pipx inject skmemory telethon
+   ```
+
+2. **Get API credentials from [my.telegram.org](https://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:**
+   ```bash
+   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`):
+   ```bash
+   echo 'export TELEGRAM_API_ID=12345678' >> ~/.bashrc
+   echo 'export TELEGRAM_API_HASH=your_api_hash_here' >> ~/.bashrc
+   ```
+
+4. **First run — authenticate:**
+   ```bash
+   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
+
+```bash
+# 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
 
 ```python
@@ -200,6 +352,19 @@ stats = import_telegram(
 print(f"Imported {stats['messages_imported']} messages across {stats['days_processed']} days")
 ```
 
+```python
+# 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
@@ -219,8 +384,8 @@ print(f"Imported {stats['messages_imported']} messages across {stats['days_proce
 
 **Three-tier storage:**
 1. **SQLite** (default primary) — fast indexed queries, zero-config
-2. **Qdrant** (optional) — semantic vector search
-3. **FalkorDB** (optional) — graph relationship traversal
+2. **SKVector** (optional) — semantic vector search
+3. **SKGraph** (optional) — graph relationship traversal
 
 ---
 
@@ -239,14 +404,21 @@ print(f"Imported {stats['messages_imported']} messages across {stats['days_proce
 ### Environment Variables
 
 ```bash
+# 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
-export SKMEMORY_QDRANT_URL=http://localhost:6333
-export SKMEMORY_QDRANT_KEY=your-api-key
+
+# 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 Qdrant + FalkorDB)
+### Docker (optional, for SKVector + SKGraph)
 
 ```bash
 cd skmemory && docker compose up -d

package/docker-compose.yml

@@ -4,32 +4,32 @@
 # SKMemory works perfectly with just SQLite (zero infrastructure).
 #
 # Start everything:  docker compose up -d
-# Just Qdrant:       docker compose up -d qdrant
-# Just FalkorDB:     docker compose up -d falkordb
+# Just SKVector:     docker compose up -d skvector
+# Just SKGraph:      docker compose up -d skgraph
 # Check status:      docker compose ps
 # Stop:              docker compose down
 #
 # Resource usage (idle):
-#   Qdrant:    ~200MB RAM, ~100MB disk
-#   FalkorDB:  ~100MB RAM, ~150MB disk
+#   SKVector:  ~200MB RAM, ~100MB disk
+#   SKGraph:   ~100MB RAM, ~150MB disk
 #   Combined:  ~300MB RAM total
 #
 # Connect from skmemory:
-#   skmemory --qdrant-url http://localhost:6333 health
+#   skmemory --skvector-url http://localhost:6333 health
 #
 # Or set environment variables:
-#   export SKMEMORY_QDRANT_URL=http://localhost:6333
-#   export SKMEMORY_FALKORDB_URL=redis://localhost:6379
+#   export SKMEMORY_SKVECTOR_URL=http://localhost:6333
+#   export SKMEMORY_SKGRAPH_URL=redis://localhost:6379
 
 services:
-  qdrant:
+  skvector:
     image: qdrant/qdrant:latest
-    container_name: skmemory-qdrant
+    container_name: skmemory-skvector
     ports:
       - "6333:6333"   # REST API
       - "6334:6334"   # gRPC
     volumes:
-      - qdrant_data:/qdrant/storage
+      - skvector_data:/qdrant/storage
     environment:
       - QDRANT__SERVICE__GRPC_PORT=6334
     restart: unless-stopped
@@ -38,13 +38,13 @@ services:
         limits:
           memory: 512M
 
-  falkordb:
+  skgraph:
     image: falkordb/falkordb:latest
-    container_name: skmemory-falkordb
+    container_name: skmemory-skgraph
     ports:
       - "6379:6379"   # Redis-compatible protocol
     volumes:
-      - falkordb_data:/data
+      - skgraph_data:/data
     restart: unless-stopped
     deploy:
       resources:
@@ -52,7 +52,7 @@ services:
           memory: 256M
 
 volumes:
-  qdrant_data:
+  skvector_data:
     driver: local
-  falkordb_data:
+  skgraph_data:
     driver: local

package/examples/stignore-agent.example

@@ -0,0 +1,59 @@
+# SKMemory Agent-Level Syncthing Ignore Patterns
+# Place at: ~/.skcapstone/agents/{agent_name}/.stignore
+# https://docs.syncthing.net/users/ignoring.html
+
+# Virtual environment (machine-specific, large)
+/venv/
+/venv
+
+# Local SQLite database (rebuildable from JSON files)
+/index.db
+
+# Logs directory (machine-specific, high churn)
+/logs
+
+# Root-level archive directory
+/archive
+
+# Memory archive (deduped/aged-out memories — machine-local, not syncable)
+# Each host runs its own cleanup; syncing archives causes data loss
+memory/archive
+
+# Temporary files
+*.tmp
+*.temp
+*.swp
+*.swo
+*~
+
+# System files
+.DS_Store
+Thumbs.db
+
+# IDE files
+.idea/
+.vscode/
+*.iml
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+
+# Node modules
+node_modules/
+
+# Syncthing internal
+.stfolder
+.stversions/
+
+# Lock files
+*.lock
+
+# Backup files
+*.bak
+*.backup
+
+# SQLite WAL/SHM (machine-specific, cause conflicts)
+*.db-wal
+*.db-shm

package/examples/stignore-root.example

@@ -0,0 +1,62 @@
+// SKCapstone Root-Level Syncthing Ignore Patterns
+// Place at: ~/.skcapstone/.stignore
+// https://docs.syncthing.net/users/ignoring.html
+
+// Private key material must never leave this node
+*.key
+*.pem
+**/private.*
+
+// Python venv (platform-specific)
+venv
+
+// Python cache
+__pycache__
+*.pyc
+*.pyo
+
+// OS metadata
+.DS_Store
+Thumbs.db
+desktop.ini
+
+// Runtime files
+daemon.pid
+
+// Operational files written independently per-host (cause sync conflicts)
+memory/promotion-log.json
+/heartbeats
+metrics/daily
+logs/daemon.log
+
+// Memory archive (deduped/aged-out memories — machine-local, not syncable)
+// Each host runs its own cleanup; syncing archives causes data loss
+**/memory/archive
+
+// Machine-local indexes — rebuildable from JSON memory files
+// SQLite DBs cause constant sync conflicts when written on multiple hosts
+**/index.db
+**/index.db-wal
+**/index.db-shm
+**/index.json
+
+// Per-host runtime state (not portable between machines)
+**/.last_checkpoint
+**/dreaming-state.json
+
+// Reflection logs (per-host cron output)
+**/reflection.log
+
+// Syncthing conflict artifacts (clean up, never sync)
+**/*.sync-conflict*
+
+// Local-only dirs (not synced)
+sessions
+conversations
+backups
+prompt_versions
+deployments
+connectors
+pubsub
+file-transfer
+souls

package/index.js

@@ -12,12 +12,13 @@ const VERSION = "0.5.0";
 const PYTHON_PACKAGE = "skmemory";
 
 function checkInstalled() {
-  try {
-    execSync(`python3 -c "import skmemory"`, { stdio: "pipe" });
-    return true;
-  } catch {
-    return false;
+  for (const py of ["python3", "python"]) {
+    try {
+      execSync(`${py} -c "import skmemory"`, { stdio: "pipe" });
+      return true;
+    } catch {}
   }
+  return false;
 }
 
 function run(args) {

package/openclaw-plugin/openclaw.plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "skmemory",
+  "name": "SKMemory",
+  "description": "Universal AI memory system — snapshots, search, rehydration rituals, import, and health checks via the skmemory CLI.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/openclaw-plugin/package.json

@@ -27,7 +27,8 @@
       "events": [
         "session:start",
         "session:compaction",
-        "session:resume"
+        "session:resume",
+        "session:end"
       ],
       "dashboard": {
         "widgets": [