loom-claw 0.1.0

package/README.md

@@ -0,0 +1,414 @@
+# Loom Memory Plugin for OpenClaw
+
+Structured long-term memory for OpenClaw using loom. Automatically extracts key information from conversations into schema-based memory and injects relevant context back into the model prompt.
+
+## Quick Start
+
+### 1. Install & configure Loom
+
+```bash
+cd Loom
+pip install -e .
+loom init          # generates configs/loom.yaml and template files
+```
+
+Open `configs/loom.yaml` and fill in the `llm` section (or copy `.env.example` to `.env` and edit):
+
+```yaml
+# configs/loom.yaml
+llm:
+  api_key: "your-api-key"
+  model: "google/gemini-2.5-flash"            # any OpenAI-compatible model
+  base_url: "https://openrouter.ai/api/v1"    # OpenRouter / OpenAI / local endpoint
+```
+
+> **Supported providers:** OpenAI (`https://api.openai.com/v1`), OpenRouter (`https://openrouter.ai/api/v1`), or any OpenAI-compatible endpoint.
+
+### 2. Start the Loom backend
+
+```bash
+loom serve                   # foreground (Ctrl+C to stop)
+# or
+loom serve start             # background daemon (recommended)
+```
+
+The server runs at `http://localhost:8666` by default. Use `loom serve status` to verify.
+
+### 3. Install OpenClaw (if not already installed)
+
+If you don't have OpenClaw yet, install it first:
+
+```bash
+# Recommended: one-line installer (auto-detects OS, installs Node if needed)
+curl -fsSL https://openclaw.ai/install.sh | bash
+
+# Or via npm / pnpm / bun if you manage Node yourself
+npm install -g openclaw@latest
+openclaw onboard --install-daemon
+```
+
+Verify the installation:
+
+```bash
+openclaw --version
+openclaw doctor            # check for config issues
+```
+
+> See the [OpenClaw Install Guide](https://docs.openclaw.ai/install) for all install methods (Docker, Nix, from source, etc.).
+
+### 4. Install the plugin
+
+```bash
+openclaw plugins install --link /path/to/Loom/loom-openclaw-plugin
+```
+
+### 5. Start (or restart) OpenClaw
+
+If the Gateway is **not running**, start it:
+
+```bash
+openclaw gateway
+```
+
+If the Gateway is **already running**, restart it to load the new plugin:
+
+```bash
+openclaw gateway restart
+```
+
+### 6. Verify
+
+Confirm the plugin is loaded and the Gateway is healthy:
+
+```bash
+# Check the plugin is registered
+openclaw plugins list --enabled
+
+# Inspect plugin details
+openclaw plugins inspect loom-claw
+
+# Check Gateway health
+openclaw gateway status
+```
+
+Then open a chat and run `/loom status` — you should see Loom connection info and schema overview. The plugin will automatically extract and recall structured memories each turn.
+
+## AI-Assisted Setup
+
+You can let an AI agent handle the entire setup process for you.
+
+**Option A: Via any LLM agent (OpenClaw, Telegram, etc.)**
+
+Send this prompt to your agent:
+
+```
+Read https://github.com/TeamEcho-AI/Loom/blob/main/skills/loom-setup/SKILL.md and follow it to install and configure Loom for OpenClaw. When done, summarize what you can do.
+```
+
+The agent will fetch the setup guide, then walk you through environment checks, LLM configuration, service startup, plugin installation, and verification step by step.
+
+**Option B: Via Claude Code**
+
+```bash
+claude skill install ./skills/loom-setup
+```
+
+Once installed, say “help me run Loom” or “I want to add memory to OpenClaw” and the skill will trigger automatically.
+
+## Features
+
+- **Auto-extract** and **auto-recall** — the Loom CM agent extracts information from conversations into structured schemas and injects relevant data into the system prompt each turn
+- **Schema-based memory** — organizes knowledge into typed domains and fields rather than flat text, enabling precise recall and structured reasoning
+- **Multi-schema management** — create, switch, backup, and restore independent schema files for different contexts or personas
+- **Template system** — bootstrap schemas from built-in, shared, or custom templates; create and manage templates via slash commands
+- **Agent tools** — 5 registered tools let the LLM inspect, recall, build, forget, and update memory on demand
+- **Slash commands** — full `/loom` command suite for manual memory management
+
+
+## Prerequisites
+
+| Requirement | Version | Check |
+| --- | --- | --- |
+| Python | 3.10+ | `python --version` |
+| Node.js | 22.14+ (24 recommended) | `node --version` |
+| Loom | latest | `loom --version` |
+| OpenClaw | latest | `openclaw --version` |
+
+### Loom backend setup
+
+```bash
+cd Loom
+pip install -e .
+loom init
+```
+
+Configure your LLM provider by editing `configs/loom.yaml`:
+
+```yaml
+llm:
+  api_key: "your-api-key"
+  model: "google/gemini-2.5-flash"
+  base_url: "https://openrouter.ai/api/v1"
+```
+
+Alternatively, copy `.env.example` to `.env` and fill in `API_KEY`, `MODEL`, `BASE_URL`. Values in `.env` override `loom.yaml`.
+
+Start the server:
+
+```bash
+loom serve                               # foreground
+loom serve start                         # background daemon
+loom serve start --autostart             # daemon + auto-start on boot
+loom serve status                        # check if running
+```
+
+The backend runs on `http://localhost:8666` by default.
+
+### OpenClaw installation
+
+If OpenClaw is not yet installed:
+
+```bash
+curl -fsSL https://openclaw.ai/install.sh | bash
+```
+
+Or install manually via npm:
+
+```bash
+npm install -g openclaw@latest
+openclaw onboard --install-daemon
+```
+
+See the [OpenClaw Install Guide](https://docs.openclaw.ai/install) for Docker, Nix, and other options.
+
+## Installation
+
+```bash
+openclaw plugins install --link /path/to/Loom/loom-openclaw-plugin
+```
+
+The installer automatically registers the plugin as the active Context Engine. **A Gateway restart is required** to load the plugin:
+
+```bash
+# If the Gateway is already running as a service
+openclaw gateway restart
+
+# Or start it fresh
+openclaw gateway
+```
+
+To configure the context engine slot manually, add to your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "contextEngine": "loom-claw"
+    }
+  }
+}
+```
+
+### Verify installation
+
+```bash
+# Plugin should appear in the loaded list
+openclaw plugins list --enabled
+
+# Detailed plugin info (config schema, status, capabilities)
+openclaw plugins inspect loom-claw
+
+# Gateway health check
+openclaw gateway status
+```
+
+Once the Gateway is running, open a chat and send `/loom status` to confirm end-to-end connectivity with the Loom backend.
+
+> See [OpenClaw Plugin docs](https://docs.openclaw.ai/tools/plugin) for full plugin management commands, and [Gateway CLI](https://docs.openclaw.ai/cli/gateway) for service lifecycle.
+
+## Configuration
+
+Configure in `openclaw.json` under `plugins.entries.loom-claw.config`:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `loomBaseUrl` | `http://localhost:8666` | Loom backend URL |
+| `sessionId` | `default` | Loom session ID |
+| `schemaId` | `default` | Shared schema file ID for cross-session memory |
+| `schemaTemplate` | — | Initial template: `general`, `roleplay`, or any custom template |
+| `buildEveryNTurns` | `1` | Run memory extraction every N conversation turns (same concept as Loom `build_every_n_turns`) |
+
+Example `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "loom-claw": {
+        "enabled": true,
+        "config": {
+          "loomBaseUrl": "http://localhost:8666",
+          "sessionId": "default",
+          "schemaId": "default",
+          "schemaTemplate": "general",
+          "buildEveryNTurns": 1
+        }
+      }
+    }
+  }
+}
+```
+
+## Slash Commands
+
+The plugin registers the `/loom` command with the following subcommands:
+
+**View & Recall**
+
+| Command | Description |
+| --- | --- |
+| `/loom` or `/loom status` | Show connection status and schema overview |
+| `/loom inspect` | View schema structure with field values |
+| `/loom recall` | Recall all stored memory data |
+
+**Memory Management**
+
+| Command | Description |
+| --- | --- |
+| `/loom forget <domain>` | Delete a specific schema domain |
+| `/loom forget --all` | Clear all memory |
+| `/loom reset` | Backup current schema and start fresh |
+
+**Schema Files**
+
+| Command | Description |
+| --- | --- |
+| `/loom schemas` | List all schema files and backups |
+| `/loom new [name]` | Create a new blank schema and switch to it |
+| `/loom switch <schema_id>` | Switch to an existing schema |
+| `/loom restore <backup_id>` | Restore a schema from backup |
+
+**Template Management**
+
+| Command | Description |
+| --- | --- |
+| `/loom templates` | List all available templates (grouped by source) |
+| `/loom templates show <name>` | Preview template domains and fields |
+| `/loom templates use <name>` | Create a schema from template and switch to it |
+| `/loom templates create` | Show format help for creating custom templates |
+| `/loom templates create <definition>` | Create a custom template (compact text or `--json`) |
+| `/loom templates delete <name>` | Delete a custom template |
+| `/loom templates help` | Show template command help |
+
+**Configuration**
+
+| Command | Description |
+| --- | --- |
+| `/loom config` | View current runtime configuration |
+| `/loom config buildEveryNTurns <N>` | Update extraction frequency at runtime |
+| `/loom help` | Show help |
+
+## Agent Tools
+
+Five tools are registered for the OpenClaw agent to use during conversations:
+
+| Tool | Description |
+| --- | --- |
+| `loom_inspect` | Inspect schema structure and field values |
+| `loom_recall` | Recall all schema memory data |
+| `loom_build` | Manually trigger information extraction and storage |
+| `loom_forget` | Delete a specific domain or clear all memory |
+| `loom_update` | Trigger schema update from session chat history |
+
+## Creating Custom Templates
+
+You can create custom templates directly from the chat using the compact text format:
+
+```
+/loom templates create game_character RPG character memory
+  character: name | character name, class | class, level | level, skills | skills
+  story: main_quest | main quest, side_quests | side quests, achievements | achievements
+  social: friends | friends, guild | guild, reputation | reputation
+```
+
+Format rules:
+- First line: `template_name description` (name allows letters, numbers, underscores, hyphens)
+- Following lines: `domain_name: field1 | description, field2 | description`
+- Fields separated by `,`, field name and description separated by `|`
+
+Alternatively, use JSON format:
+
+```
+/loom templates create --json {"_meta":{"name":"my_template","description":"..."},"domain1":{"data":{...},"_mutable":true}}
+```
+
+## Context Engine Lifecycle
+
+| OpenClaw Hook | Plugin Behavior | Loom API |
+| --- | --- | --- |
+| `bootstrap` | Verify backend, create session, load template | `POST /api/sessions`, `GET /api/schemas/recall-all` |
+| `assemble` | Fetch schema data and inject into system prompt | `GET /api/schemas/recall-all` |
+| `afterTurn` | Format new messages, call build to extract info | `POST /api/build` |
+| `compact` | Delegate to runtime | — |
+
+## Data Flow
+
+```
+User message → OpenClaw agent
+                 ↓
+           [assemble] → GET /api/schemas/recall-all
+                 ↓        → schema data injected into system prompt
+           Model generates response
+                 ↓
+           [afterTurn] → POST /api/build
+                           → CM Agent extracts information
+                           → Updates schema
+                           → Available on next assemble
+```
+
+## Data Storage
+
+Loom stores data under the OpenClaw [Agent Workspace](https://docs.openclaw.ai/concepts/agent-workspace):
+
+```
+~/.openclaw/workspace/loom/
+├── schemas/              # Schema files (shared across sessions)
+│   ├── default.json
+│   └── backups/          # Auto-created on reset
+│       └── default_20260314_180736.json
+└── sessions/             # Loom session files
+    └── default.json
+```
+
+Configure the paths in `configs/loom.yaml`:
+
+```yaml
+persistence:
+  session_dir: "~/.openclaw/workspace/loom/sessions"
+  schemas_dir: "~/.openclaw/workspace/loom/schemas"
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Type check
+npm run typecheck
+
+# Run tests
+npm test
+```
+
+To develop with a local link:
+
+```bash
+openclaw plugins install --link /path/to/Loom/loom-openclaw-plugin
+```
+
+Changes to the TypeScript source are picked up on the next gateway restart.
+
+## License
+
+MIT