loom-memory 0.1.0

Loom — Cognitive Operating System for AI Agents with Structured Persistent Memory

Build agents that truly remember — without flooding the context window.

Documentation • OpenClaw • Quick Start • Demo

---

Loom: The Missing "Last Mile" of Agentic Memory

What is Loom?

Loom is the missing "last mile" of agentic memory. It builds memories from interactions in tandem with the model and dynamically orchestrates candidate memories into the Minimum Sufficient Context for LLM agents—not merely another storage or retrieval layer. While naive retrieval treats memory as a search problem, Loom treats it as an associative recommendation problem. Driven by real-world product abstractions from building lifelong AI companions, Loom helps agents remember, evolve, and reason without flooding the context window.

Through its cognitive architecture, Loom achieves this via a robust pipeline:

• Goal-Aware Context: Builds the exact context needed based on the agent's current task and token budget— no more, no less.
• Associative Recall: Links related memories naturally, but applies strict depth limits to prevent context bloat.
• Read & Write Loop: Pulls information from multiple sources and actively saves high-value insights back to memory.
• Flexible Schemas: Support for custom schemas, AI-generated schemas, and production-tested templates out-of-the-box.
• Decoupled & Inspectable: Plugs into any existing storage (Vector DBs, RAG) while keeping the memory process human-readable and debuggable.

Schema Call Protocol

To empower CM agents with genuine cognitive continuity, we built the Schema Call Protocol (SCP)—an infrastructural memory interaction protocol. We discard the archaic paradigms of conventional RAG (which retrieves noisy, unstructured dialogue chunks) and static file systems (which lack active reasoning semantics). Instead, we introduce the Loom Schema: a dynamic, self-describing cognitive ontology.

Acting as an executable "file system for memories," SCP fundamentally redefines memory from a passive storage unit to an interactive logical construct. This architectural shift delivers profound advantages:

• Controllable & operable: Agents interact with memory through predictable, protocol-bound state transitions.
• Human-aligned transparency: Memory trees are natively human-readable, definable, and adjustable—reducing the “black box” problem.
• Deterministic traversal: Agents stop blindly searching raw text and instead compile context along a structured, self-descriptive memory tree.
• Interpretability & error correction: Logical pathways become traceable so humans and agents can debug reasoning steps.

From Flat Data to Multi-Resolution Intelligence

Unlike traditional flat schemas that treat memory as a static spreadsheet, Loom’s Schema is Hierarchical & Collapsible. This creates a "Variable Focal Length" for the agent's memory:

• High-Level Abstraction (Low Resolution): When the agent zooms out, it perceives the Core Essence. It doesn't see "Alice likes hiking on Sundays"; it sees Identity -> High-Energy Adventurer. This allows for lightning-fast, high-dimensional reasoning.
• Granular Specificity (High Resolution): When the interaction demands precision, the schema unfolds recursively. The agent dives from a general persona down to the microscopic nuances of a specific habit.

The Loom Forge: Hybrid Schema Strategy

Loom doesn't force a "one-size-fits-all" structure. We provide a flexible orchestration layer that balances human control with machine intuition through three distinct strategies:

1. Pre-designed Schemas For developers who demand absolute precision, Loom supports Pre-designed Schemas. You can define the "Skeleton of Truth" manually, ensuring that the agent’s core world-model aligns perfectly with your business logic or narrative constraints.
2. AI-Generated Schemas Loom allows the agent to Auto-Generate Schemas on the fly. As the interaction evolves and new patterns emerge, the system autonomously identifies latent structures in the experience, creating new recursive abstractions without human intervention.
3. NS-Inspired Reference Schemas Loom comes "batteries-included" with Reference Schemas distilled from extensive experience in AI Companionship and Social AI (NatureSelect.ai).
   • Ready-to-use: Skip the cold-start problem with battle-tested templates for personality, relationship dynamics, and emotional memory.
   • Validated Abstractions: Use schemas specifically optimized to capture the nuances of human-AI bonding and long-term social rapport.

The Vision

Memory is a means, not the end. Loom’s "last mile" approach isn't just about saving context window tokens—it's about shifting the paradigm from storing raw data to evolving cognition. By distilling noisy interactions into the Minimum Sufficient Context along a structured "skeleton of truth," Loom bridges the gap between simply knowing what a user said and truly understanding who they are. The ultimate endgame of this architecture is hidden state modeling—moving beyond explicit dialogue logs to capture underlying intents, beliefs, and emotional baselines. This is how we move agents past short-term execution toward true cognitive growth, paving the way for long-horizon AI companions with genuine intelligence.

Benchmark & Results

Architecture

See Architecture Documentation for the system architecture diagram.

---

OpenClaw

Use Loom as structured long-term memory inside OpenClaw. The first-party loom-openclaw-plugin registers as a Context Engine: memory is recalled into context and updated from conversation each turn.

Setup

1. Install OpenClaw if you do not have it yet. See the OpenClaw install guide for CLI, gateway, and daemon setup.
2. Install and configure Loom from this repo (or pip install loom-memory elsewhere, then loom init):

cd Loom
pip install -e .
loom init

Set api_key, model, and base_url in configs/loom.yaml or via .env (API_KEY, MODEL, BASE_URL).

3. Start the Loom HTTP API. The plugin talks to this backend, defaulting to http://localhost:8666:

loom serve start
loom serve status

Use loom serve instead if you want foreground mode.

4. Install the plugin using the path to loom-openclaw-plugin inside your clone:

openclaw plugins install --link /path/to/Loom/loom-openclaw-plugin

5. Start or restart the OpenClaw gateway so it loads the plugin:

openclaw gateway
openclaw gateway restart

6. Verify the connection with /loom status in chat. Optional CLI checks:

openclaw plugins list --enabled
openclaw gateway status

First Chat

Once the gateway is up, these are the first commands worth trying in any OpenClaw chat:

1. Check the connection with /loom or /loom status. This should show the Loom backend URL, current schema id, and available domains. If it fails, fix loom serve or loomBaseUrl first.
2. Choose how memory starts: Use /loom templates then /loom templates show general and /loom templates use general if you want a built-in schema tree from the start. Use /loom new or /loom new my_session if you want a blank schema file and prefer the CM to create fields as you chat.
3. Just talk normally. The plugin recalls memory each turn and runs build on a schedule controlled by buildEveryNTurns; you do not need slash commands for every message.
4. Inspect what got stored with /loom inspect and /loom schemas. Use /loom help for the full command set, including forget, reset, templates create, and config.

Where To Tweak

Runtime tuning lives in ~/.openclaw/openclaw.json under plugins.entries.loom-claw.config, including loomBaseUrl, schemaTemplate, and buildEveryNTurns.

For a guided setup inside an AI coding agent, use skills/loom-setup/SKILL.md.

More detail: OpenClaw integration (docs) · loom-openclaw-plugin/README.md

---

Quick Start

Install

pip install loom-memory
loom init

From source: git clone https://github.com/TeamEcho-AI/Loom.git && cd Loom && pip install -e .

Then configure your LLM provider:

# Edit configs/loom.yaml — set api_key, model, base_url
# Or use environment variables:
export API_KEY="your-api-key"
export MODEL="gpt-5.4"
export BASE_URL="https://api.openai.com/v1"

Any OpenAI-compatible API works (OpenAI, OpenRouter, vLLM, etc.).

Start the Server

loom serve
# API: http://localhost:8666
# Web UI: http://localhost:8666

Python API

import asyncio
from loom import Loom, LoomConfig
from loom.prompts import default_cm_prompt, DEFAULT_CHATBOT_PROMPT

config = LoomConfig.from_file()

loom = (
    Loom(config)
    .from_template("general")
    .cm_prompt(default_cm_prompt)
    .chatbot_prompt(DEFAULT_CHATBOT_PROMPT)
)

# Build memory from any text
asyncio.run(loom.build("""
    [user]: I'm Bob, I love hiking and sushi.
    [assistant]: Great taste, Bob!
""", session_id="bob"))

# Chat with memory
result = asyncio.run(loom.chat("What food do I like?", session_id="bob"))
print(result["reply"])  # "You mentioned that you love sushi!"

REST API

# Build memory
curl -X POST http://localhost:8666/api/build \
  -H "Content-Type: application/json" \
  -d '{"text": "I am Alice, I love hiking.", "session_id": "alice"}'

# Chat with memory
curl -X POST http://localhost:8666/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "What are my hobbies?", "session_id": "alice"}'

CLI

loom build --input conversation.md --session user1
loom chat --message "What do I like?" --session user1
loom chat --session user1   # interactive mode

---

Demo

Try the interactive demo — no installation required.

Pick a scenario, chat with the assistant, and see how Loom precisely recalls specific facts from the structured memory schema.

Scenario	What you can test
Personal Assistant — Meeting Alice	Food allergies, family members, hobbies, career
Developer Coach — Bob's Tech Stack	Programming languages, career history, tech preferences
Travel Planner — Maria's Japan Trip	Dietary restrictions, budget, travel companions, language level

---

How It Works

Loom uses a two-phase workflow:

1. build — The CM agent reads input text and updates the schema (no chatbot response)
2. chat — The CM agent recalls relevant schema data → Chatbot generates a grounded response

When build_every_n_turns is configured, Loom automatically extracts memories from ongoing conversations — the schema evolves naturally without explicit build() calls.

---

Use Cases

• Per-user memory — personalize chatbots and agents with structured user profiles
• Long-running agents — maintain context across hundreds of conversation turns
• Multi-session knowledge sharing — schemas are shared across sessions by default
• AI companions & roleplay — built-in templates for deep character memory
• Autonomous task agents — learn from feedback and adapt behavior over time

---

Integrations

Plugin system

Extend Loom with custom plugins for RAG retrieval, logging, safety filters, and more—without modifying core code. For OpenClaw, see OpenClaw above.

loom = Loom(config).from_template("general").use(MyPlugin())

---

Resources

• Documentation — full guides, API reference, and configuration
• Quick Start Guide — get running in minutes
• Python API — detailed Python usage
• REST API — all endpoints and examples
• CLI Reference — command-line interface
• Schema Templates — create and manage templates
• OpenClaw integration — Loom as a Context Engine in OpenClaw
• Plugins — extend Loom with custom behavior
• GitHub Issues — bug reports and feature requests

---

Contributing

Contributions are welcome! Please see our documentation for guidelines.

License

Apache License 2.0 — see LICENSE for details.