harness-memory 0.8.4

Pluggable memory system with hierarchical recall, FTS search, and multiple backend support.

A memory-tree based memory system — tiered recall, pluggable storage, and memory that migrates to OpenClaw / Hermes and beyond.

Highlights · Overview · Core Technology · Features · Quick Start · Contents

English · 中文

---

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:

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

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

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

# 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
• Overview
• Core Technology
• Features
• Quick Start
• Reference
  • Architecture
  • CLI reference
  • Development
• Project Info
  • Contributing
  • Related projects
  • 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

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	Agent runtime that consumes the memory
harness-browser	Browser automation for memory-backed agents
harness-gateway	Multi-platform IM channel bridge
Octop	The self-hosted assistant that composes the Harness stack

📄 License

This project is licensed under the MIT License.