Metadata-Version: 2.4
Name: loom-memory
Version: 0.1.0
Summary: Loom — Cognitive Operating System for AI Agents with Structured Persistent Memory
License: Apache-2.0
Project-URL: Homepage, https://github.com/TeamEcho-AI/Loom
Project-URL: Documentation, https://docs.loom.teamecho.ai
Project-URL: Repository, https://github.com/TeamEcho-AI/Loom
Project-URL: Issues, https://github.com/TeamEcho-AI/Loom/issues
Keywords: ai,agents,memory,llm,Schema Call Protocal,context
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.0.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn[standard]>=0.20.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

<div align="center">

<img src="docs/logo/banner.png" alt="Loom — Structured, persistent memory for LLM-powered agents" width="100%">

<br>

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI version](https://img.shields.io/pypi/v/loom-memory.svg)](https://pypi.org/project/loom-memory/)

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

[Documentation](https://docs.loom.teamecho.ai) •
[OpenClaw](#openclaw) •
[Quick Start](#quick-start) •
[Demo](#demo)

</div>

---
# Loom: The Missing "Last Mile" of Agentic Memory
![Loom overall intro](assets/loom_intro.png)
## 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:

![Loom pipeline overview](assets/loom_pipeline.png)

- **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

![Loom schema overview](assets/loom_schema.png)

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

![Loom locomo performance](assets/locomo_performance.jpeg)

## Architecture

See [Architecture Documentation](docs/concepts/architecture.mdx) for the system architecture diagram.

---

## OpenClaw

Use Loom as structured long-term memory inside [OpenClaw](https://docs.openclaw.ai). The first-party [loom-openclaw-plugin](https://github.com/TeamEcho-AI/Loom/tree/main/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](https://docs.openclaw.ai/install) for CLI, gateway, and daemon setup.
2. **Install and configure Loom** from this repo (or `pip install loom-memory` elsewhere, then `loom init`):

```bash
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`:

```bash
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:

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

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

```bash
openclaw gateway
openclaw gateway restart
```

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

```bash
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`](skills/loom-setup/SKILL.md).

**More detail:** [OpenClaw integration (docs)](https://docs.loom.teamecho.ai/extending/openclaw) · [`loom-openclaw-plugin/README.md`](loom-openclaw-plugin/README.md)

---

## Quick Start

### Install

```bash
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:

```bash
# 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

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

### Python API

```python
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

```bash
# 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

```bash
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](https://teamecho-ai.github.io/Loom/)** — 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](#openclaw) above.

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

---

## Resources

- **[Documentation](https://docs.loom.teamecho.ai)** — full guides, API reference, and configuration
- **[Quick Start Guide](https://docs.loom.teamecho.ai/quickstart)** — get running in minutes
- **[Python API](https://docs.loom.teamecho.ai/usage/python-api)** — detailed Python usage
- **[REST API](https://docs.loom.teamecho.ai/interfaces/api-server)** — all endpoints and examples
- **[CLI Reference](https://docs.loom.teamecho.ai/interfaces/cli)** — command-line interface
- **[Schema Templates](https://docs.loom.teamecho.ai/usage/schema-templates)** — create and manage templates
- **[OpenClaw integration](https://docs.loom.teamecho.ai/extending/openclaw)** — Loom as a Context Engine in OpenClaw
- **[Plugins](https://docs.loom.teamecho.ai/extending/plugins)** — extend Loom with custom behavior
- **[GitHub Issues](https://github.com/TeamEcho-AI/Loom/issues)** — bug reports and feature requests

---

## Contributing

Contributions are welcome! Please see our documentation for guidelines.

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.
