harness-memory 0.9.11

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

📌 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

🧰 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 ... manages the OpenClaw integration; the standalone harness-memory-hermes install|doctor package manages Hermes.

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
pip install harness-memory-hermes
harness-memory-hermes install --hermes-source /path/to/hermes-agent
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

Global options come before the subcommand and select which store to act on:

harness-memory [--backend sqlite|postgres] [--db PATH] [--dsn DSN] \
               [--namespace NAME] [--json] [--config FILE] <command> ...

--json makes any command emit machine-readable output. Every group supports --help. Env-var equivalents: HARNESS_MEMORY_BACKEND / _DB / _DSN / _NAMESPACE / _CONFIG.

Search & recall

Inspect the memory layers

Storage maintenance

Cleanup and space reclaim are separate concerns: gc / consolidate / thread prune delete rows, db gives the freed space back to the OS. None of them run automatically — schedule them yourself.

Migration & backup

SQLite Memory checkpoints now reuse large skills_metadata and workspace file contents by default. In documentation, workspace_file_contents means the loaded AGENTS.md, MEMORY.md, USER.md, and other configured files, separate from dynamically recalled snippets. The underlying DeepAgents state key remains memory_contents; workspace_file_contents is a documentation label, not an API or schema change. Existing inline checkpoints stay readable and are migrated only by an explicit db checkpoints invocation. Set HARNESS_MEMORY_CHECKPOINT_DEDUP=0 to disable new reference writes while keeping compatible reads. Older binaries cannot read the new format; use the offline --expand migration before reverting the reader. See checkpoint storage and migration for maintenance and rollback steps.

Host integration & tooling

🛠️ Development

Prerequisites: Python 3.11+, uv

make install          # uv sync --group dev
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 against main

See CONTRIBUTING.md for branching, PR, and release details (release/* → main auto-publishes to PyPI).

🔗 Related projects

📄 License

This project is licensed under the MIT License.