harness-memory 0.7.0

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

Harness Memory

Lightweight, agent-neutral memory system — hierarchical memory tree with pluggable backends and seamless migration.

English · 中文

---

Highlights

• Lightweight Architecture — A minimal memory layer that complements (not replaces) your agent's native memory, achieving a 1+1 > 2 effect
• Agent-Neutral — Works alongside any LLM agent without direct model interaction; never interferes with existing agent workflows
• Pluggable & Migratable — Swap backends freely (SQLite, PostgreSQL, Qdrant); migrate memory data seamlessly across different agents
• Hierarchical Memory Tree — Root → branch → leaf structure for organized long-term recall
• Dual-Database Design — Stores both raw conversation records and distilled memory tree for complete knowledge retention
• Zero Dependencies — Core package uses only Python stdlib + sqlite3; no heavy ML frameworks required
• Full-Text Search — FTS5/BM25 powered search across conversations and memories
• CLI Tooling — Complete command-line interface for ingesting, querying, and managing memories

---

Overview

Harness Memory is a lightweight, agent-neutral memory system that provides persistent, structured memory for AI agents. It does not interact with LLMs directly — instead, it operates as an independent storage and recall layer that any agent can plug into, enhancing the agent's native memory without disrupting its existing workflows.

Design Philosophy

• Complement, not replace — Your agent already has its own memory mechanisms. Harness Memory acts as a supplementary layer, enriching context without taking over.
• No model coupling — The system never calls LLMs itself. It prepares and organizes data; the agent decides when and how to use it.
• Portable knowledge — Memory data lives in an independent backend that can be migrated across different agents, frameworks, or deployments without loss.

How It Differs from Other Memory Systems

Aspect	Other Systems	Harness Memory
Backend portability	Tied to specific agent/framework	Independent storage backend — migrate freely between agents. Supports local SQLite, remote PostgreSQL, or vector databases (Qdrant). Users can implement custom backends.
Memory recall	Tool-call only, model must request	Pre-injection into system prompt before reaching the model (feeds relevant context proactively) + tool-call as supplement
Memory storage	Single representation	Dual-database: raw conversation records (archival source of truth) + distilled memory tree (structured knowledge). Periodically cleans raw conversations into archival data, then distills them — like a "dreaming" process — into hierarchical memory nodes.
Agent coupling	Deep integration required	Agent-neutral; pluggable via CLI, Python API, or system prompt injection. Zero interference with existing agent memory.

Three-Phase Workflow

1. Ingest — Archive conversation history (Claude Code, OpenAI, generic JSONL) as raw records
2. Distill — Periodically "dream": clean and summarize raw conversations, then organize into the memory tree
3. Recall — Inject relevant memories into system prompts before model invocation; also available as agent tools

---

Core Technology

Component	Technology	Purpose
Storage	SQLite + FTS5	Zero-dep local persistence with BM25 search
Memory Model	Hierarchical tree	Root → branch → leaf organization
Search	FTS5/BM25	Full-text search across conversations and memory nodes
Backends	Pluggable interface	SQLite (default), PostgreSQL, Qdrant
CLI	Click	Command-line management and automation
Integration	LangGraph checkpoint	Compatible with LangGraph agent state

---

Features

• Memory Tree — Hierarchical summaries (root → branch → leaf) for long-term recall
• System Prompt Injection — Pre-injects relevant memories before model invocation for proactive recall
• Full-Text Search — FTS5/BM25 powered search across conversations and memories
• Dual Storage — Raw conversation archives + distilled memory tree, two databases working together
• Dream-like Distillation — Periodically processes raw conversations into structured memory nodes
• Conversation Records — Standardized chat history storage and retrieval
• CLI Tooling — Command-line interface for ingesting, querying, and managing memories
• Agent Skill — Cross-platform skill for automated archival, summarization, and memory tree construction
• Pluggable Backends — SQLite (default, zero-dep), PostgreSQL, Qdrant, or custom
• Zero Dependencies — Core package uses only Python stdlib + sqlite3
• Namespace Isolation — Multiple agents share one database safely
• LangGraph Integration — Optional checkpoint backend for LangGraph agents

---

Quick Start

Installation

pip install harness-memory

With CLI support:

pip install "harness-memory[cli]"

Optional backends:

pip install "harness-memory[postgres]"   # PostgreSQL backend
pip install "harness-memory[qdrant]"     # Qdrant vector backend

Python API

from harness_memory import Memory

# Create with default SQLite backend
memory = Memory(namespace="my-agent")

# Store a memory
memory.store("User prefers Python over Java", topic="preferences")

# Recall relevant memories
results = memory.recall("programming language")
for node in results:
    print(f"[{node.topic}] {node.content}")

CLI

# Ingest conversation files
harness-memory --namespace my-agent ingest --source ~/.claude/projects/myapp/conversations/

# Search memories
harness-memory --namespace my-agent memory recall "user preferences"

# Store a new memory
harness-memory --namespace my-agent memory store --content "User prefers TDD" --topic "workflow"

# View the memory tree
harness-memory --namespace my-agent memory tree

---

CLI Reference

The CLI provides five command groups for managing conversations and memories:

harness-memory [GLOBAL OPTIONS] COMMAND [ARGS]

Global options:

• --config PATH — Config file path (default: ~/.harness-memory/config.json)
• --backend, -b TYPE — Backend type: sqlite, postgres, qdrant
• --db PATH — SQLite database path
• --dsn DSN — PostgreSQL connection string
• --namespace, -n NS — Memory namespace for isolation (default: default)
• --json — Output machine-readable JSON

Commands

Command	Description
config show	Show resolved configuration
config set KEY VALUE	Set a config value
ingest --source PATH	Archive conversation files
conversations list	List stored conversations
conversations export ID	Export a conversation as JSON
summary pending	List conversations needing summaries
summary set ID --content TEXT	Set a conversation summary
memory store --content TEXT	Store a memory node
memory recall QUERY	Full-text search
memory tree	Display the memory tree

---

Agent Skill

The skills/memory-agent/ directory contains a cross-platform agent skill for automated memory management. It works with Claude Code, Copilot CLI, Gemini CLI, or any agent that can invoke Bash commands.

Workflow

# 1. Ingest recent conversations
harness-memory --namespace my-agent --json ingest --source ~/.claude/projects/

# 2. Check what needs summarizing
harness-memory --namespace my-agent --json summary pending

# 3. Export for summarization
harness-memory --namespace my-agent conversations export conv-abc123

# 4. Write summary back
harness-memory --namespace my-agent summary set conv-abc123 --content "Implemented OAuth login flow"

# 5. Store extracted knowledge
harness-memory --namespace my-agent --json memory store --content "Auth uses JWT with 24h expiry" --topic "architecture"

# 6. Recall later
harness-memory --namespace my-agent --json memory recall "authentication"

Scheduling

Task	Interval	Purpose
Ingest	Every 4 hours	Archive new conversations
Summarize	Daily	Generate missing summaries
Memory Tree	Weekly	Organize knowledge hierarchy

---

Python API Reference

Memory

from harness_memory import Memory

memory = Memory(namespace="my-agent", backend_config={"db_path": "~/my-memory.db"})

Method	Description
store(content, topic=None)	Store a memory as a leaf node
recall(query, limit=5)	Recall relevant memories via FTS
add_conversation(record)	Persist a conversation record
search(query, limit=10)	Full-text search across messages
list_conversations(**filters)	List conversations with filters
get_conversation(id)	Get full conversation by ID
get_tree()	Get the complete memory tree

Backend Configuration

# SQLite (default) — zero dependencies
memory = Memory(namespace="agent", backend="sqlite")

# PostgreSQL — requires [postgres] extra
memory = Memory(namespace="agent", backend="postgres", backend_config={
    "dsn": "postgresql://user:pass@localhost/memdb"
})

# Custom backend
memory = Memory(namespace="agent", backend=my_custom_backend)

---

Supported Conversation Formats

Format	Extension	Detection
Claude Code	.jsonl	type field: human_message / assistant_message
Generic JSONL	.jsonl	role + content fields per line
OpenAI JSON	.json	messages array with role/content objects

---

Development

Prerequisites: Python 3.11+, uv

git clone https://github.com/orcakit/harness-memory.git
cd harness-memory
make install
make all              # lint + typecheck + test (CI ship bar)

Command	Description
make lint	Ruff check + format check
make format	Auto-fix and format
make typecheck	mypy strict
make test	pytest with coverage
make build	Build wheel + sdist

---

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and run make all before opening a PR.

Security issues: see SECURITY.md.

---

Related Projects

Project	Description
orca (Octop)	Self-hosted multi-user AI control plane
harness-agent	Production-grade AI agent platform built on LangChain Deep Agents
harness-browser	AI-friendly browser automation via CDP
harness-gateway	Multi-platform IM channel bridge for AI agents

---

License

MIT