Metadata-Version: 2.4
Name: harness-memory
Version: 0.8.4
Summary: Pluggable memory system with hierarchical recall, FTS search, and multiple backend support.
Project-URL: Homepage, https://github.com/orcakit/harness-memory
Project-URL: Repository, https://github.com/orcakit/harness-memory
Project-URL: Issues, https://github.com/orcakit/harness-memory/issues
Project-URL: Changelog, https://github.com/orcakit/harness-memory/blob/main/CHANGELOG.md
Author: orcakit
License: MIT
License-File: LICENSE
Keywords: agent,fts,llm,memory,recall,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Provides-Extra: chroma
Requires-Dist: chromadb>=0.4; extra == 'chroma'
Provides-Extra: cli
Requires-Dist: click>=8.0; extra == 'cli'
Provides-Extra: dashboard
Requires-Dist: click>=8.0; extra == 'dashboard'
Requires-Dist: fastapi>=0.110; extra == 'dashboard'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: click>=8.0; extra == 'dev'
Requires-Dist: langgraph-checkpoint-sqlite>=2.0; extra == 'dev'
Requires-Dist: langgraph-checkpoint>=2.0; extra == 'dev'
Requires-Dist: langgraph>=0.2; extra == 'dev'
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2; extra == 'embeddings'
Provides-Extra: langgraph
Requires-Dist: langgraph-checkpoint-sqlite>=2.0; extra == 'langgraph'
Requires-Dist: langgraph-checkpoint>=2.0; extra == 'langgraph'
Provides-Extra: langgraph-postgres
Requires-Dist: langgraph-checkpoint-postgres>=2.0; extra == 'langgraph-postgres'
Requires-Dist: langgraph-checkpoint>=2.0; extra == 'langgraph-postgres'
Requires-Dist: psycopg[binary]>=3.1; extra == 'langgraph-postgres'
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
Provides-Extra: qdrant
Requires-Dist: qdrant-client>=1.7; extra == 'qdrant'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/images/banner.jpeg" alt="Harness Memory Banner" width="600" />
</p>

<p align="center">
  <strong>A memory-tree based memory system — tiered recall, pluggable storage, and memory that migrates to OpenClaw / Hermes and beyond.</strong>
</p>

<p align="center">
  <a href="https://www.python.org/downloads/"><img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-blue?logo=python&logoColor=white" /></a>
  <a href="https://github.com/orcakit/harness-memory/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green" /></a>
  <a href="https://pypi.org/project/harness-memory/"><img src="https://img.shields.io/pypi/v/harness-memory.svg" alt="PyPI version" /></a>
  <a href="https://github.com/astral-sh/ruff"><img alt="Code Style: Ruff" src="https://img.shields.io/badge/code%20style-ruff-000000?logo=ruff&logoColor=white" /></a>
  <a href="https://github.com/orcakit/harness-memory"><img alt="GitHub stars" src="https://img.shields.io/github/stars/orcakit/harness-memory?style=social" /></a>
</p>

<p align="center">
  <a href="#-highlights">Highlights</a> ·
  <a href="#-overview">Overview</a> ·
  <a href="#-core-technology">Core Technology</a> ·
  <a href="#-features">Features</a> ·
  <a href="#-quick-start">Quick Start</a> ·
  <a href="#-contents">Contents</a>
</p>

<p align="center">
  <b>English</b> · <a href="README_CN.md">中文</a>
</p>

---

**Harness Memory** is a pluggable long-term memory system for LLM agents, built around the **memory tree** model — a hierarchy of `root → branch → leaf` nodes. It does not talk to an LLM itself; it is a storage-and-recall layer any agent can drop in. What makes it special is **portability**: the storage backend is abstracted behind a `MemoryBackend` Protocol, and first-class host adapters let the same memory travel to other agents such as **OpenClaw** and **Hermes**.

> Harness Memory's design goal: memory is a portable asset, not a lock-in. Capture it once, recall it anywhere — including in a different agent framework.

## ✨ Highlights

| | Feature | Description |
|---|---------|-------------|
| 🌳 | **Memory tree** | Hierarchical `root → branch → leaf` nodes for organized recall |
| 🧩 | **Portable by design** | `MemoryBackend` Protocol makes storage swappable |
| 🔄 | **Agent-agnostic** | Drop into any agent; OpenClaw & Hermes adapters ship in-box |
| 🚚 | **Cross-agent migration** | Pack to `.hmpkg`, adopt into OpenClaw / Hermes / another agent |
| 🔍 | **Recall pipeline** | M4 pipeline: parse → route → gather → rerank → diversify → suppress → budget → render |
| 💾 | **Pluggable storage** | SQLite + FTS5 by default; PostgreSQL / Chroma / Qdrant optional |
| 🪶 | **Zero core deps** | stdlib + `sqlite3`; extras add the rest |
| 🧠 | **Tiered distillation** | L0 raw → L1 candidate → L2 atom → L3 entity |

## 📌 Overview

A fact is recorded canonically as an `AtomCard` (L2) grouped under an `Entity` (L3). The memory tree is a lightweight index over those atoms: `root` and `branch` nodes hold directory-style labels, and each `leaf` points at an atom — its content is projected from the atom at read time, so there is never a second copy of the fact to drift out of sync. Recall walks the tree and surfaces the linked leaves most relevant to a query.

Because storage sits behind a Protocol, the same `Memory` object can run on a local SQLite file, a Postgres database, or a vector index — and because host adapters exist for OpenClaw and Hermes, the memory you build in one agent can be adopted by another.

## 🧠 Core Technology

| Layer | Technology |
|-------|-----------|
| **Language** | Python 3.11+ |
| **Core deps** | None — stdlib + `sqlite3` |
| **Model** | `MemoryNode` tree + `AtomCard` |
| **Recall** | M4 pipeline (`recall/`) |
| **Storage** | `MemoryBackend` Protocol — SQLite/FTS5, Postgres, vector (Chroma/Qdrant) |
| **Host adapters** | `lightclaw/` bridge for OpenClaw & Hermes |
| **LangGraph** | Optional checkpointer (SQLite / Postgres) |
| **Build / quality** | hatchling · ruff · mypy · pytest |

## 🤔 Features

### Memory tree
- `root → branch → leaf` hierarchy; leaves reference atoms, content is projected on read.
- Tiered distillation: **L0** raw event → **L1** candidate → **L2** `AtomCard` → **L3** entity page (plus an L2.5 episode/diary layer).

### Recall
- `recall_for_prompt_v2(memory, query)` returns `result.rendered` + `result.snippets`.
- M4 pipeline routes the query, gathers candidates, reranks, diversifies, suppresses noise, and budgets tokens before rendering.

### Pluggable backends
- Default: SQLite + FTS5 (full-text search).
- Optional: PostgreSQL (`[postgres]`), ChromaDB (`[chroma]`), Qdrant (`[qdrant]`), local embeddings (`[embeddings]`), and a LangGraph checkpointer (`[langgraph]`).

### Portability — OpenClaw & Hermes
- **`MemoryBackend` Protocol** keeps storage swappable, so the engine is agent-agnostic.
- **`lightclaw/`** is a shared bridge (JSON-RPC + path projection) reused by both OpenClaw and Hermes.
- **`plugins/openclaw/`** ships a TypeScript shell (`harnessmemory`); **`plugins/hermes/`** ships a Python plugin — both build on the same bridge.
- **CLI**: `harness-memory openclaw ...` and `harness-memory hermes ...` manage the integration.

### Cross-agent migration
`migration/portable/` packs memory into a `.hmpkg` and adopts it into a target host:

```bash
harness-memory portable pack  --namespace my-agent --out my-agent.hmpkg
harness-memory portable adopt --source my-agent.hmpkg --host openclaw
```

`adopt()` rewrites the `host` / namespace and resolves the target store for OpenClaw, Hermes, another agent, or a plain `harnessmemory` backend.

## 🚀 Quick Start

### Prerequisites
- **Python 3.11+**

### 1. Install

```bash
pip install harness-memory                       # core (SQLite + FTS5)
pip install "harness-memory[postgres]"           # PostgreSQL backend
pip install "harness-memory[chroma,embeddings]"  # vector index + embeddings
pip install "harness-memory[langgraph]"          # LangGraph checkpointer
pip install "harness-memory[cli]"                # CLI (incl. openclaw / hermes)
```

### 2. Store & recall

```python
from harness_memory import Memory
from harness_memory.recall import recall_for_prompt_v2

m = Memory(namespace="my-agent")
m.store("User prefers Python over Java", topic="preferences")

result = recall_for_prompt_v2(m, "language preference")
print(result.rendered)
```

### 3. Use with another agent

```bash
# OpenClaw
harness-memory openclaw status
harness-memory portable adopt --source my-agent.hmpkg --host openclaw

# Hermes
harness-memory hermes status
harness-memory portable adopt --source my-agent.hmpkg --host hermes
```

## 📑 Contents

- [Highlights](#-highlights)
- [Overview](#-overview)
- [Core Technology](#-core-technology)
- [Features](#-features)
- [Quick Start](#-quick-start)
- **Reference**
  - [Architecture](#-architecture)
  - [CLI reference](#-cli-reference)
  - [Development](#-development)
- **Project Info**
  - [Contributing](#-contributing)
  - [Related projects](#-related-projects)
  - [License](#-license)

## 🏗️ Architecture

```
Memory                      facade + backend factory
 ├─ core.py                 store / get / update / delete / recall / get_tree
 ├─ backends/               MemoryBackend Protocol · sqlite · postgres · fts
 ├─ recall/                 M4 pipeline (parse/route/gather/rerank/...)
 ├─ extractor/ + promotion/ L0→L1→L2 distillation
 ├─ page/ + episode/        entity pages + diary layer
 ├─ vector/                 optional Chroma / Qdrant
 ├─ lightclaw/              OpenClaw / Hermes host bridge
 └─ migration/portable/     pack → .hmpkg → adopt
```

## 📖 CLI reference

| Command | Description |
|---------|-------------|
| `harness-memory openclaw ...` | Manage the OpenClaw integration |
| `harness-memory hermes ...` | Manage the Hermes integration |
| `harness-memory portable pack` | Export memory to a `.hmpkg` |
| `harness-memory portable adopt` | Import a `.hmpkg` into a target host |
| `harness-memory portable doctor` | Validate a portable package |
| `harness-memory store` / `recall` | Direct store / recall helpers |

## 🛠️ Development

**Prerequisites:** Python 3.11+, [uv](https://docs.astral.sh/uv/)

```bash
make install          # pip install -e ".[dev,cli]"
make all              # lint + typecheck + test
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Run `make all` before submitting
4. Open a Pull Request

## 🔗 Related projects

| Project | Description |
|---------|-------------|
| [harness-agent](https://github.com/orcakit/harness-agent) | Agent runtime that consumes the memory |
| [harness-browser](https://github.com/orcakit/harness-browser) | Browser automation for memory-backed agents |
| [harness-gateway](https://github.com/orcakit/harness-gateway) | Multi-platform IM channel bridge |
| [Octop](https://github.com/orcakit/orca) | The self-hosted assistant that composes the Harness stack |

## 📄 License

This project is licensed under the [MIT License](LICENSE).
