harness-memory 0.1.1

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

orcakit-harness-memory

Pluggable memory system for LLM agents — hierarchical memory tree with full-text search and multiple backend support.

Features

• Memory Tree — Hierarchical summaries (root → branch → leaf) for long-term recall
• Full-Text Search — FTS5/BM25 powered search across conversations and memories
• Conversation Records — Standardized chat history storage and retrieval
• Pluggable Backends — SQLite (default, zero-dep), PostgreSQL, Qdrant
• Zero Dependencies — Core package uses only Python stdlib + sqlite3
• Namespace Isolation — Multiple agents share one database safely

Installation

pip install orcakit-harness-memory

Optional backends:

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

Quickstart

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}")

# Add a conversation record
from harness_memory import ConversationRecord, Message
from datetime import datetime, timezone

record = ConversationRecord(
    id="conv-001",
    thread_id="thread-1",
    user="alice",
    started_at=datetime.now(timezone.utc),
    ended_at=datetime.now(timezone.utc),
    messages=[
        Message(role="user", content="How do I use memory?", timestamp=datetime.now(timezone.utc)),
        Message(role="assistant", content="Just call memory.store()!", timestamp=datetime.now(timezone.utc)),
    ],
    summary=None,
    metadata={},
)
memory.add_conversation(record)

# Search conversations
hits = memory.search("memory")
for hit in hits:
    print(f"[{hit.role}] {hit.message_content}")

Backend Configuration

# SQLite (default) — zero dependencies
memory = Memory(namespace="agent", backend="sqlite")
memory = Memory(namespace="agent", backend_config={"db_path": "/data/memory.db"})

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

# Qdrant — requires [qdrant] extra
memory = Memory(namespace="agent", backend="qdrant", backend_config={
    "url": "http://localhost:6333"
})

# Custom backend — pass any MemoryBackend instance
memory = Memory(namespace="agent", backend=my_custom_backend)

API Reference

Memory

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

Data Types

• MemoryNode — A node in the memory tree (root/branch/leaf)
• ConversationRecord — Complete conversation with messages
• Message — Single message (user/assistant/tool)
• SearchResult — FTS search hit with score
• ConversationSummary — Lightweight conversation listing

Development

make dev          # Install dev dependencies
make lint         # Ruff check + format check
make typecheck    # mypy strict
make test         # pytest
make all          # lint + typecheck + test

License

MIT