harness-memory 0.9.1

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 (pipeline/recall/)
Storage	MemoryBackend Protocol — SQLite/FTS5, Postgres, vector (Chroma/Qdrant)
Host adapters	adapters/bridge/ host 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(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.
• adapters/bridge/ is a shared JSON-RPC bridge reused by OpenClaw; in-process hosts call the same application/runtime.py through MemoryService.
• 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

operations/migration/portable/ packs memory into a .hmpkg and adopts it into a target host:

harness-memory portable list-sources                            # discover migratable stores
harness-memory portable pack  --from agent:my-agent --out my-agent.hmpkg
harness-memory portable adopt my-agent.hmpkg --as openclaw
harness-memory portable doctor --host openclaw --compare-with my-agent.hmpkg

adopt resolves the target store and namespace for OpenClaw, Hermes, another agent, or a plain harnessmemory backend — for OpenClaw it defaults to the namespace the installed plugin actually reads (from openclaw.json); override with --as openclaw:<namespace>. Imports are idempotent, back up the target db first, and can rewrite the host field (--host-rewrite target).

🚀 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.pipeline.recall import recall_for_prompt

m = Memory(namespace="my-agent")  # defaults to ~/.harness-memory/session.sqlite
m.store("User prefers Python over Java", topic="preferences")

# Recall is FTS-based (no stemming) — query with words that appear in the memory.
result = recall_for_prompt(m, "Python preference")
print(result.rendered)

3. Use with another agent

# OpenClaw — wire the plugin slot, then bring your memory along
harness-memory openclaw setup
harness-memory portable adopt my-agent.hmpkg --as openclaw

# Hermes
harness-memory hermes install
harness-memory portable adopt my-agent.hmpkg --as hermes

📑 Contents

• Highlights
• Overview
• Core Technology
• Features
• Quick Start
• Reference
  • Architecture
  • CLI reference
  • Development
• Project Info
  • Contributing
  • Related projects
  • License

🏗️ Architecture

harness_memory/
 ├─ core.py                 Memory facade + backend factory
 ├─ service.py              in-process adapter over application runtime
 ├─ application/            MemoryRuntime, config, host files, path projection
 ├─ pipeline/               extractor · promotion · page · episode · recall · lifecycle
 ├─ storage/                MemoryBackend Protocol · sqlite · postgres · vector
 ├─ ports/                  LLMClient protocol and clients
 ├─ adapters/               bridge · CLI · dashboard
 └─ operations/migration/   export/import/rename/portable pack → .hmpkg → adopt

📖 CLI reference

Command	Description
harness-memory openclaw setup / doctor / uninstall / print-config	Manage the OpenClaw integration
harness-memory hermes install / doctor	Manage the Hermes integration
harness-memory portable list-sources	Discover migratable memory stores on this machine
harness-memory portable pack --from <host:name>	Export memory to a .hmpkg
harness-memory portable adopt <pkg> --as <host[:ns]>	Import a .hmpkg into a target host
harness-memory portable doctor --host <host[:ns]>	Health-check the target store, optionally comparing counts with a .hmpkg
harness-memory recall "<query>"	Run the recall pipeline from the terminal
harness-memory atom / entity / raw / candidate ...	Inspect and maintain the individual memory layers
harness-memory dashboard	Launch the local web dashboard ([dashboard] extra)

Every group supports --help; global options --backend, --db, and --namespace select the store.

🛠️ 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.