harness-memory 0.1.1__py3-none-any.whl

harness_memory/__init__.py

@@ -0,0 +1,27 @@
+"""orcakit-harness-memory: pluggable memory system for LLM agents."""
+
+from __future__ import annotations
+
+from harness_memory.core import Memory
+from harness_memory.types import (
+    ConversationRecord,
+    ConversationSummary,
+    MemoryNode,
+    Message,
+    SearchResult,
+)
+
+try:
+    from harness_memory._version import __version__
+except ImportError:
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "ConversationRecord",
+    "ConversationSummary",
+    "Memory",
+    "MemoryNode",
+    "Message",
+    "SearchResult",
+    "__version__",
+]

harness_memory/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.1'
+__version_tuple__ = version_tuple = (0, 1, 1)
+
+__commit_id__ = commit_id = None

harness_memory/backends/__init__.py

@@ -0,0 +1,40 @@
+"""Memory backend protocol and registry."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+from harness_memory.types import (
+    ConversationRecord,
+    ConversationSummary,
+    MemoryNode,
+    SearchResult,
+)
+
+
+@runtime_checkable
+class MemoryBackend(Protocol):
+    """Abstract interface for memory storage backends.
+
+    Implementations: SqliteMemoryBackend, PostgresMemoryBackend, QdrantMemoryBackend.
+    """
+
+    def save_node(self, node: MemoryNode) -> None: ...
+    def get_children(self, parent_id: str | None) -> list[MemoryNode]: ...
+    def update_node(self, node_id: str, content: str, topic: str | None = None) -> None: ...
+    def search_memories(self, query: str, limit: int = 5) -> list[MemoryNode]: ...
+    def get_tree(self) -> list[MemoryNode]: ...
+    def save_conversation(self, record: ConversationRecord) -> None: ...
+    def search_messages(self, query: str, limit: int = 10) -> list[SearchResult]: ...
+    def list_conversations(
+        self,
+        *,
+        user: str | None = None,
+        after: Any | None = None,
+        before: Any | None = None,
+        limit: int = 20,
+    ) -> list[ConversationSummary]: ...
+    def get_conversation(self, conversation_id: str) -> ConversationRecord | None: ...
+
+
+__all__ = ["MemoryBackend"]

harness_memory/backends/postgres.py

@@ -0,0 +1,347 @@
+"""PostgreSQL-based memory backend with tsvector full-text search."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import UTC, datetime
+from typing import Any
+
+import psycopg
+from psycopg.rows import dict_row
+
+from harness_memory.types import (
+    ConversationRecord,
+    ConversationSummary,
+    MemoryNode,
+    Message,
+    SearchResult,
+)
+
+
+class PostgresMemoryBackend:
+    """Memory backend using PostgreSQL + tsvector/GIN full-text search.
+
+    Multi-agent isolation via PostgreSQL schemas (one schema per namespace).
+    Default DSN: ``postgresql://localhost/harness_memory``.
+    """
+
+    def __init__(
+        self,
+        namespace: str,
+        dsn: str = "postgresql://localhost/harness_memory",
+        **kwargs: Any,
+    ) -> None:
+        self._ns = re.sub(r"[^a-z0-9_]", "_", namespace.lower())
+        self._dsn = dsn
+        self._conn = psycopg.connect(dsn, row_factory=dict_row, **kwargs)
+        self._init_schema()
+
+    def close(self) -> None:
+        """Close the database connection."""
+        self._conn.close()
+
+    # ------------------------------------------------------------------
+    # Schema
+    # ------------------------------------------------------------------
+
+    def _init_schema(self) -> None:
+        ns = self._ns
+        with self._conn.cursor() as cur:
+            cur.execute(f"CREATE SCHEMA IF NOT EXISTS {ns}")
+
+            cur.execute(f"""
+                CREATE TABLE IF NOT EXISTS {ns}.memory_nodes (
+                    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+                    parent_id UUID REFERENCES {ns}.memory_nodes(id) ON DELETE CASCADE,
+                    level TEXT NOT NULL CHECK (level IN ('root', 'branch', 'leaf')),
+                    content TEXT NOT NULL,
+                    topic TEXT,
+                    conversation_id UUID,
+                    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+                    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+                    content_tsv TSVECTOR GENERATED ALWAYS AS (
+                        to_tsvector('simple', content) || to_tsvector('simple', COALESCE(topic, ''))
+                    ) STORED
+                )
+            """)
+            cur.execute(
+                f"CREATE INDEX IF NOT EXISTS memory_nodes_parent ON {ns}.memory_nodes(parent_id)"
+            )
+            cur.execute(
+                f"CREATE INDEX IF NOT EXISTS memory_nodes_level ON {ns}.memory_nodes(level)"
+            )
+            cur.execute(
+                f"CREATE INDEX IF NOT EXISTS memory_nodes_fts ON {ns}.memory_nodes USING GIN(content_tsv)"
+            )
+
+            cur.execute(f"""
+                CREATE TABLE IF NOT EXISTS {ns}.conversations (
+                    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+                    thread_id TEXT NOT NULL,
+                    "user" TEXT,
+                    started_at TIMESTAMPTZ NOT NULL,
+                    ended_at TIMESTAMPTZ NOT NULL,
+                    summary TEXT,
+                    metadata JSONB,
+                    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+                )
+            """)
+            cur.execute(
+                f"CREATE INDEX IF NOT EXISTS conversations_thread ON {ns}.conversations(thread_id)"
+            )
+            cur.execute(
+                f'CREATE INDEX IF NOT EXISTS conversations_user ON {ns}.conversations("user")'
+            )
+            cur.execute(
+                f"CREATE INDEX IF NOT EXISTS conversations_time ON {ns}.conversations(started_at)"
+            )
+
+            cur.execute(f"""
+                CREATE TABLE IF NOT EXISTS {ns}.messages (
+                    id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+                    conversation_id UUID NOT NULL REFERENCES {ns}.conversations(id) ON DELETE CASCADE,
+                    role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'tool')),
+                    content TEXT NOT NULL,
+                    timestamp TIMESTAMPTZ NOT NULL,
+                    tool_name TEXT,
+                    seq INTEGER NOT NULL,
+                    content_tsv TSVECTOR GENERATED ALWAYS AS (to_tsvector('simple', content)) STORED
+                )
+            """)
+            cur.execute(
+                f"CREATE INDEX IF NOT EXISTS messages_conv ON {ns}.messages(conversation_id)"
+            )
+            cur.execute(
+                f"CREATE INDEX IF NOT EXISTS messages_fts ON {ns}.messages USING GIN(content_tsv)"
+            )
+
+        self._conn.commit()
+        # Set search_path so subsequent queries don't need schema prefix
+        self._conn.execute(f"SET search_path TO {ns}, public")
+
+    # ------------------------------------------------------------------
+    # Memory tree
+    # ------------------------------------------------------------------
+
+    def save_node(self, node: MemoryNode) -> None:
+        with self._conn.cursor() as cur:
+            cur.execute(
+                """INSERT INTO memory_nodes
+                    (id, parent_id, level, content, topic, conversation_id, created_at, updated_at)
+                    VALUES (%s, %s, %s, %s, %s, %s, %s, %s)
+                    ON CONFLICT (id) DO UPDATE SET
+                        parent_id = EXCLUDED.parent_id,
+                        level = EXCLUDED.level,
+                        content = EXCLUDED.content,
+                        topic = EXCLUDED.topic,
+                        conversation_id = EXCLUDED.conversation_id,
+                        updated_at = EXCLUDED.updated_at
+                """,
+                (
+                    node.id,
+                    node.parent_id,
+                    node.level,
+                    node.content,
+                    node.topic,
+                    node.conversation_id,
+                    node.created_at,
+                    node.updated_at,
+                ),
+            )
+        self._conn.commit()
+
+    def get_children(self, parent_id: str | None) -> list[MemoryNode]:
+        with self._conn.cursor() as cur:
+            if parent_id is None:
+                cur.execute("SELECT * FROM memory_nodes WHERE parent_id IS NULL")
+            else:
+                cur.execute("SELECT * FROM memory_nodes WHERE parent_id = %s", (parent_id,))
+            rows = cur.fetchall()
+        return [self._row_to_node(r) for r in rows]
+
+    def update_node(self, node_id: str, content: str, topic: str | None = None) -> None:
+        now = datetime.now(UTC)
+        with self._conn.cursor() as cur:
+            cur.execute(
+                "UPDATE memory_nodes SET content = %s, topic = %s, updated_at = %s WHERE id = %s",
+                (content, topic, now, node_id),
+            )
+        self._conn.commit()
+
+    def search_memories(self, query: str, limit: int = 5) -> list[MemoryNode]:
+        with self._conn.cursor() as cur:
+            cur.execute(
+                """SELECT * FROM memory_nodes
+                    WHERE content_tsv @@ plainto_tsquery('simple', %s)
+                    ORDER BY ts_rank(content_tsv, plainto_tsquery('simple', %s)) DESC
+                    LIMIT %s""",
+                (query, query, limit),
+            )
+            rows = cur.fetchall()
+        return [self._row_to_node(r) for r in rows]
+
+    def get_tree(self) -> list[MemoryNode]:
+        with self._conn.cursor() as cur:
+            cur.execute("SELECT * FROM memory_nodes")
+            rows = cur.fetchall()
+        return [self._row_to_node(r) for r in rows]
+
+    # ------------------------------------------------------------------
+    # Conversations
+    # ------------------------------------------------------------------
+
+    def save_conversation(self, record: ConversationRecord) -> None:
+        metadata_json = json.dumps(record.metadata, ensure_ascii=False) if record.metadata else None
+        with self._conn.cursor() as cur:
+            cur.execute(
+                """INSERT INTO conversations
+                    (id, thread_id, "user", started_at, ended_at, summary, metadata)
+                    VALUES (%s, %s, %s, %s, %s, %s, %s)
+                    ON CONFLICT (id) DO UPDATE SET
+                        thread_id = EXCLUDED.thread_id,
+                        "user" = EXCLUDED."user",
+                        started_at = EXCLUDED.started_at,
+                        ended_at = EXCLUDED.ended_at,
+                        summary = EXCLUDED.summary,
+                        metadata = EXCLUDED.metadata
+                """,
+                (
+                    record.id,
+                    record.thread_id,
+                    record.user,
+                    record.started_at,
+                    record.ended_at,
+                    record.summary,
+                    metadata_json,
+                ),
+            )
+            # Delete old messages on upsert, then re-insert
+            cur.execute("DELETE FROM messages WHERE conversation_id = %s", (record.id,))
+            for seq, msg in enumerate(record.messages):
+                cur.execute(
+                    """INSERT INTO messages
+                        (conversation_id, role, content, timestamp, tool_name, seq)
+                        VALUES (%s, %s, %s, %s, %s, %s)""",
+                    (record.id, msg.role, msg.content, msg.timestamp, msg.tool_name, seq),
+                )
+        self._conn.commit()
+
+    def search_messages(self, query: str, limit: int = 10) -> list[SearchResult]:
+        with self._conn.cursor() as cur:
+            cur.execute(
+                """SELECT m.conversation_id, m.content, m.role, m.timestamp,
+                          ts_rank(m.content_tsv, plainto_tsquery('simple', %s)) AS score
+                    FROM messages m
+                    WHERE m.content_tsv @@ plainto_tsquery('simple', %s)
+                    ORDER BY score DESC
+                    LIMIT %s""",
+                (query, query, limit),
+            )
+            rows = cur.fetchall()
+        return [
+            SearchResult(
+                conversation_id=str(r["conversation_id"]),
+                message_content=r["content"],
+                role=r["role"],
+                timestamp=r["timestamp"],
+                score=float(r["score"]),
+            )
+            for r in rows
+        ]
+
+    def list_conversations(
+        self,
+        *,
+        user: str | None = None,
+        after: Any | None = None,
+        before: Any | None = None,
+        limit: int = 20,
+    ) -> list[ConversationSummary]:
+        conditions: list[str] = []
+        params: list[Any] = []
+        if user is not None:
+            conditions.append('"user" = %s')
+            params.append(user)
+        if after is not None:
+            conditions.append("started_at >= %s")
+            params.append(after if isinstance(after, datetime) else str(after))
+        if before is not None:
+            conditions.append("started_at <= %s")
+            params.append(before if isinstance(before, datetime) else str(before))
+
+        where = f"WHERE {' AND '.join(conditions)}" if conditions else ""
+        params.append(limit)
+
+        with self._conn.cursor() as cur:
+            cur.execute(
+                f'SELECT id, thread_id, "user", started_at, summary'
+                f" FROM conversations {where} ORDER BY started_at DESC LIMIT %s",
+                params,
+            )
+            rows = cur.fetchall()
+        return [
+            ConversationSummary(
+                id=str(r["id"]),
+                thread_id=r["thread_id"],
+                user=r["user"],
+                started_at=r["started_at"],
+                summary=r["summary"],
+            )
+            for r in rows
+        ]
+
+    def get_conversation(self, conversation_id: str) -> ConversationRecord | None:
+        with self._conn.cursor() as cur:
+            cur.execute("SELECT * FROM conversations WHERE id = %s", (conversation_id,))
+            row = cur.fetchone()
+            if row is None:
+                return None
+
+            cur.execute(
+                "SELECT * FROM messages WHERE conversation_id = %s ORDER BY seq",
+                (conversation_id,),
+            )
+            msg_rows = cur.fetchall()
+
+        messages = [
+            Message(
+                role=m["role"],
+                content=m["content"],
+                timestamp=m["timestamp"],
+                tool_name=m["tool_name"],
+            )
+            for m in msg_rows
+        ]
+
+        metadata = row["metadata"] if row["metadata"] else {}
+        if isinstance(metadata, str):
+            metadata = json.loads(metadata)
+
+        return ConversationRecord(
+            id=str(row["id"]),
+            thread_id=row["thread_id"],
+            user=row["user"],
+            started_at=row["started_at"],
+            ended_at=row["ended_at"],
+            messages=messages,
+            summary=row["summary"],
+            metadata=metadata,
+        )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _row_to_node(row: dict[str, Any]) -> MemoryNode:
+        return MemoryNode(
+            id=str(row["id"]),
+            parent_id=str(row["parent_id"]) if row["parent_id"] else None,
+            level=row["level"],
+            content=row["content"],
+            topic=row["topic"],
+            conversation_id=str(row["conversation_id"]) if row["conversation_id"] else None,
+            created_at=row["created_at"],
+            updated_at=row["updated_at"],
+        )

harness_memory/backends/sqlite.py

@@ -0,0 +1,339 @@
+"""SQLite-based memory backend with FTS5 full-text search."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from harness_memory.types import (
+    ConversationRecord,
+    ConversationSummary,
+    MemoryNode,
+    Message,
+    SearchResult,
+)
+
+
+class SqliteMemoryBackend:
+    """Memory backend using SQLite + FTS5.
+
+    Multi-agent isolation via table-name prefix (namespace).
+    Default database path: ``~/.harness-memory/session.sqlite``.
+    """
+
+    def __init__(
+        self,
+        namespace: str,
+        db_path: str | Path = "~/.harness-memory/session.sqlite",
+    ) -> None:
+        self._ns = namespace.replace("-", "_").replace(".", "_")
+        self._db_path = Path(db_path).expanduser()
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(str(self._db_path), check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("PRAGMA foreign_keys=ON")
+        self._init_schema()
+
+    def close(self) -> None:
+        self._conn.close()
+
+    # ------------------------------------------------------------------
+    # Schema
+    # ------------------------------------------------------------------
+
+    def _init_schema(self) -> None:
+        ns = self._ns
+        self._conn.executescript(f"""
+            CREATE TABLE IF NOT EXISTS {ns}_memory_nodes (
+                id TEXT PRIMARY KEY,
+                parent_id TEXT,
+                level TEXT NOT NULL CHECK (level IN ('root', 'branch', 'leaf')),
+                content TEXT NOT NULL,
+                topic TEXT,
+                conversation_id TEXT,
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS {ns}_memory_nodes_parent
+                ON {ns}_memory_nodes(parent_id);
+            CREATE INDEX IF NOT EXISTS {ns}_memory_nodes_level
+                ON {ns}_memory_nodes(level);
+
+            CREATE TABLE IF NOT EXISTS {ns}_conversations (
+                id TEXT PRIMARY KEY,
+                thread_id TEXT NOT NULL,
+                user TEXT,
+                started_at TEXT NOT NULL,
+                ended_at TEXT NOT NULL,
+                summary TEXT,
+                metadata TEXT,
+                created_at TEXT NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS {ns}_conversations_thread
+                ON {ns}_conversations(thread_id);
+            CREATE INDEX IF NOT EXISTS {ns}_conversations_user
+                ON {ns}_conversations(user);
+            CREATE INDEX IF NOT EXISTS {ns}_conversations_time
+                ON {ns}_conversations(started_at);
+
+            CREATE TABLE IF NOT EXISTS {ns}_messages (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                conversation_id TEXT NOT NULL,
+                role TEXT NOT NULL CHECK (role IN ('user', 'assistant', 'tool')),
+                content TEXT NOT NULL,
+                timestamp TEXT NOT NULL,
+                tool_name TEXT,
+                seq INTEGER NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS {ns}_messages_conv
+                ON {ns}_messages(conversation_id);
+        """)
+
+        # FTS5 tables (CREATE VIRTUAL TABLE IF NOT EXISTS is supported)
+        self._conn.executescript(f"""
+            CREATE VIRTUAL TABLE IF NOT EXISTS {ns}_messages_fts USING fts5(
+                content,
+                content='{ns}_messages',
+                content_rowid='id',
+                tokenize='unicode61'
+            );
+
+            CREATE VIRTUAL TABLE IF NOT EXISTS {ns}_memory_fts USING fts5(
+                content,
+                topic,
+                content='{ns}_memory_nodes',
+                content_rowid='rowid',
+                tokenize='unicode61'
+            );
+        """)
+
+        # Triggers for FTS sync
+        self._conn.executescript(f"""
+            CREATE TRIGGER IF NOT EXISTS {ns}_messages_ai
+            AFTER INSERT ON {ns}_messages BEGIN
+                INSERT INTO {ns}_messages_fts(rowid, content)
+                VALUES (new.id, new.content);
+            END;
+
+            CREATE TRIGGER IF NOT EXISTS {ns}_memory_ai
+            AFTER INSERT ON {ns}_memory_nodes BEGIN
+                INSERT INTO {ns}_memory_fts(rowid, content, topic)
+                VALUES (new.rowid, new.content, COALESCE(new.topic, ''));
+            END;
+
+            CREATE TRIGGER IF NOT EXISTS {ns}_memory_au
+            AFTER UPDATE ON {ns}_memory_nodes BEGIN
+                INSERT INTO {ns}_memory_fts({ns}_memory_fts, rowid, content, topic)
+                VALUES ('delete', old.rowid, old.content, COALESCE(old.topic, ''));
+                INSERT INTO {ns}_memory_fts(rowid, content, topic)
+                VALUES (new.rowid, new.content, COALESCE(new.topic, ''));
+            END;
+        """)
+        self._conn.commit()
+
+    # ------------------------------------------------------------------
+    # Memory tree
+    # ------------------------------------------------------------------
+
+    def save_node(self, node: MemoryNode) -> None:
+        ns = self._ns
+        self._conn.execute(
+            f"""INSERT OR REPLACE INTO {ns}_memory_nodes
+                (id, parent_id, level, content, topic, conversation_id, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                node.id,
+                node.parent_id,
+                node.level,
+                node.content,
+                node.topic,
+                node.conversation_id,
+                node.created_at.isoformat(),
+                node.updated_at.isoformat(),
+            ),
+        )
+        self._conn.commit()
+
+    def get_children(self, parent_id: str | None) -> list[MemoryNode]:
+        ns = self._ns
+        if parent_id is None:
+            rows = self._conn.execute(f"SELECT * FROM {ns}_memory_nodes WHERE parent_id IS NULL").fetchall()
+        else:
+            rows = self._conn.execute(f"SELECT * FROM {ns}_memory_nodes WHERE parent_id = ?", (parent_id,)).fetchall()
+        return [self._row_to_node(r) for r in rows]
+
+    def update_node(self, node_id: str, content: str, topic: str | None = None) -> None:
+        ns = self._ns
+        now = datetime.now(UTC).isoformat()
+        self._conn.execute(
+            f"UPDATE {ns}_memory_nodes SET content = ?, topic = ?, updated_at = ? WHERE id = ?",
+            (content, topic, now, node_id),
+        )
+        self._conn.commit()
+
+    def search_memories(self, query: str, limit: int = 5) -> list[MemoryNode]:
+        ns = self._ns
+        # Wrap in double-quotes so FTS5 treats the whole string as a phrase
+        # rather than interpreting operators like '-' as NOT.
+        safe_query = '"{}"'.format(query.replace('"', '""'))
+        rows = self._conn.execute(
+            f"""SELECT n.* FROM {ns}_memory_fts f
+                JOIN {ns}_memory_nodes n ON f.rowid = n.rowid
+                WHERE f.{ns}_memory_fts MATCH ?
+                ORDER BY rank
+                LIMIT ?""",
+            (safe_query, limit),
+        ).fetchall()
+        return [self._row_to_node(r) for r in rows]
+
+    def get_tree(self) -> list[MemoryNode]:
+        ns = self._ns
+        rows = self._conn.execute(f"SELECT * FROM {ns}_memory_nodes").fetchall()
+        return [self._row_to_node(r) for r in rows]
+
+    # ------------------------------------------------------------------
+    # Conversations
+    # ------------------------------------------------------------------
+
+    def save_conversation(self, record: ConversationRecord) -> None:
+        ns = self._ns
+        now = datetime.now(UTC).isoformat()
+        self._conn.execute(
+            f"""INSERT OR REPLACE INTO {ns}_conversations
+                (id, thread_id, user, started_at, ended_at, summary, metadata, created_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                record.id,
+                record.thread_id,
+                record.user,
+                record.started_at.isoformat(),
+                record.ended_at.isoformat(),
+                record.summary,
+                json.dumps(record.metadata, ensure_ascii=False),
+                now,
+            ),
+        )
+        for seq, msg in enumerate(record.messages):
+            self._conn.execute(
+                f"""INSERT INTO {ns}_messages
+                    (conversation_id, role, content, timestamp, tool_name, seq)
+                    VALUES (?, ?, ?, ?, ?, ?)""",
+                (record.id, msg.role, msg.content, msg.timestamp.isoformat(), msg.tool_name, seq),
+            )
+        self._conn.commit()
+
+    def search_messages(self, query: str, limit: int = 10) -> list[SearchResult]:
+        ns = self._ns
+        rows = self._conn.execute(
+            f"""SELECT m.conversation_id, m.content, m.role, m.timestamp,
+                       rank AS score
+                FROM {ns}_messages_fts f
+                JOIN {ns}_messages m ON f.rowid = m.id
+                WHERE f.{ns}_messages_fts MATCH ?
+                ORDER BY rank
+                LIMIT ?""",
+            (query, limit),
+        ).fetchall()
+        return [
+            SearchResult(
+                conversation_id=r["conversation_id"],
+                message_content=r["content"],
+                role=r["role"],
+                timestamp=datetime.fromisoformat(r["timestamp"]),
+                score=float(r["score"]),
+            )
+            for r in rows
+        ]
+
+    def list_conversations(
+        self,
+        *,
+        user: str | None = None,
+        after: Any | None = None,
+        before: Any | None = None,
+        limit: int = 20,
+    ) -> list[ConversationSummary]:
+        ns = self._ns
+        conditions: list[str] = []
+        params: list[Any] = []
+        if user is not None:
+            conditions.append("user = ?")
+            params.append(user)
+        if after is not None:
+            conditions.append("started_at >= ?")
+            params.append(after.isoformat() if isinstance(after, datetime) else str(after))
+        if before is not None:
+            conditions.append("started_at <= ?")
+            params.append(before.isoformat() if isinstance(before, datetime) else str(before))
+
+        where = f"WHERE {' AND '.join(conditions)}" if conditions else ""
+        params.append(limit)
+
+        rows = self._conn.execute(
+            f"SELECT id, thread_id, user, started_at, summary"
+            f" FROM {ns}_conversations {where} ORDER BY started_at DESC LIMIT ?",
+            params,
+        ).fetchall()
+        return [
+            ConversationSummary(
+                id=r["id"],
+                thread_id=r["thread_id"],
+                user=r["user"],
+                started_at=datetime.fromisoformat(r["started_at"]),
+                summary=r["summary"],
+            )
+            for r in rows
+        ]
+
+    def get_conversation(self, conversation_id: str) -> ConversationRecord | None:
+        ns = self._ns
+        row = self._conn.execute(f"SELECT * FROM {ns}_conversations WHERE id = ?", (conversation_id,)).fetchone()
+        if row is None:
+            return None
+
+        msg_rows = self._conn.execute(
+            f"SELECT * FROM {ns}_messages WHERE conversation_id = ? ORDER BY seq",
+            (conversation_id,),
+        ).fetchall()
+
+        messages = [
+            Message(
+                role=m["role"],
+                content=m["content"],
+                timestamp=datetime.fromisoformat(m["timestamp"]),
+                tool_name=m["tool_name"],
+            )
+            for m in msg_rows
+        ]
+
+        return ConversationRecord(
+            id=row["id"],
+            thread_id=row["thread_id"],
+            user=row["user"],
+            started_at=datetime.fromisoformat(row["started_at"]),
+            ended_at=datetime.fromisoformat(row["ended_at"]),
+            messages=messages,
+            summary=row["summary"],
+            metadata=json.loads(row["metadata"]) if row["metadata"] else {},
+        )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _row_to_node(row: sqlite3.Row) -> MemoryNode:
+        return MemoryNode(
+            id=row["id"],
+            parent_id=row["parent_id"],
+            level=row["level"],
+            content=row["content"],
+            topic=row["topic"],
+            conversation_id=row["conversation_id"],
+            created_at=datetime.fromisoformat(row["created_at"]),
+            updated_at=datetime.fromisoformat(row["updated_at"]),
+        )

harness_memory/core.py

@@ -0,0 +1,154 @@
+"""Memory — the unified interface for the memory system."""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+from harness_memory.backends import MemoryBackend
+from harness_memory.types import (
+    ConversationRecord,
+    ConversationSummary,
+    MemoryNode,
+    SearchResult,
+)
+
+
+class Memory:
+    """High-level memory interface.
+
+    Wraps a ``MemoryBackend`` and provides the developer-facing API for
+    storing/recalling memories and managing conversation records.
+
+    Args:
+        namespace: Isolation namespace (typically agent name).
+        backend: Either a backend type string (``"sqlite"``/``"postgres"``/
+            ``"qdrant"``) that will be resolved via factory, or a pre-built
+            ``MemoryBackend`` instance for direct injection.
+        backend_config: Backend-specific configuration dict. Only used when
+            ``backend`` is a string. Ignored when ``backend`` is an instance.
+    """
+
+    def __init__(
+        self,
+        namespace: str,
+        backend: str | MemoryBackend = "sqlite",
+        backend_config: dict[str, Any] | None = None,
+    ) -> None:
+        self._namespace = namespace
+        if isinstance(backend, str):
+            self._backend = _resolve_memory_backend(backend, namespace, backend_config or {})
+        else:
+            self._backend = backend
+
+    @property
+    def backend(self) -> MemoryBackend:
+        """The underlying storage backend."""
+        return self._backend
+
+    @property
+    def namespace(self) -> str:
+        """The isolation namespace."""
+        return self._namespace
+
+    # ------------------------------------------------------------------
+    # Memory management
+    # ------------------------------------------------------------------
+
+    def store(self, content: str, *, topic: str | None = None) -> MemoryNode:
+        """Store a memory as a leaf node in the tree."""
+        node = MemoryNode(
+            id=uuid.uuid4().hex,
+            parent_id=None,
+            level="leaf",
+            content=content,
+            topic=topic,
+            conversation_id=None,
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+        )
+        self._backend.save_node(node)
+        return node
+
+    def recall(self, query: str, *, limit: int = 5) -> list[MemoryNode]:
+        """Recall memories relevant to the query via FTS."""
+        return self._backend.search_memories(query, limit=limit)
+
+    # ------------------------------------------------------------------
+    # Conversation records
+    # ------------------------------------------------------------------
+
+    def add_conversation(self, record: ConversationRecord) -> None:
+        """Persist a standardized conversation record."""
+        self._backend.save_conversation(record)
+
+    def search(self, query: str, *, limit: int = 10) -> list[SearchResult]:
+        """Full-text search across chat message content."""
+        return self._backend.search_messages(query, limit=limit)
+
+    def list_conversations(
+        self,
+        *,
+        user: str | None = None,
+        after: datetime | None = None,
+        before: datetime | None = None,
+        limit: int = 20,
+    ) -> list[ConversationSummary]:
+        """List conversations with optional filters."""
+        return self._backend.list_conversations(user=user, after=after, before=before, limit=limit)
+
+    def get_conversation(self, conversation_id: str) -> ConversationRecord | None:
+        """Get a full conversation by ID."""
+        return self._backend.get_conversation(conversation_id)
+
+    # ------------------------------------------------------------------
+    # Memory tree
+    # ------------------------------------------------------------------
+
+    def get_tree(self) -> list[MemoryNode]:
+        """Get the full memory tree."""
+        return self._backend.get_tree()
+
+
+# ---------------------------------------------------------------------------
+# Backend factory
+# ---------------------------------------------------------------------------
+
+
+def _resolve_memory_backend(
+    backend_type: str,
+    namespace: str,
+    config: dict[str, Any],
+) -> MemoryBackend:
+    """Resolve a backend type string to a MemoryBackend instance."""
+    if backend_type == "sqlite":
+        from harness_memory.backends.sqlite import SqliteMemoryBackend
+
+        return SqliteMemoryBackend(
+            namespace=namespace,
+            db_path=config.get("db_path", "~/.harness-memory/session.sqlite"),
+        )
+    elif backend_type == "postgres":
+        try:
+            from harness_memory.backends.postgres import PostgresMemoryBackend  # type: ignore[import-untyped]
+        except ImportError as exc:
+            raise ImportError(
+                "PostgresMemoryBackend requires 'orcakit-harness-memory[postgres]'. "
+                "Install with: pip install 'orcakit-harness-memory[postgres]'"
+            ) from exc
+        return PostgresMemoryBackend(namespace=namespace, **config)  # type: ignore[no-any-return]
+    elif backend_type == "qdrant":
+        try:
+            from harness_memory.backends.qdrant import QdrantMemoryBackend  # type: ignore[import-untyped]
+        except ImportError as exc:
+            raise ImportError(
+                "QdrantMemoryBackend requires 'orcakit-harness-memory[qdrant]'. "
+                "Install with: pip install 'orcakit-harness-memory[qdrant]'"
+            ) from exc
+        return QdrantMemoryBackend(namespace=namespace, **config)  # type: ignore[no-any-return]
+    else:
+        raise ValueError(f"Unknown memory backend type: {backend_type!r}. Supported: 'sqlite', 'postgres', 'qdrant'")
+
+
+__all__ = ["Memory"]

harness_memory/types.py

@@ -0,0 +1,76 @@
+"""Data types for the memory system."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Literal
+
+
+@dataclass
+class MemoryNode:
+    """A node in the memory tree (root, branch, or leaf)."""
+
+    id: str
+    parent_id: str | None
+    level: Literal["root", "branch", "leaf"]
+    content: str
+    topic: str | None
+    conversation_id: str | None
+    created_at: datetime
+    updated_at: datetime
+
+
+@dataclass
+class Message:
+    """A single message in a conversation."""
+
+    role: Literal["user", "assistant", "tool"]
+    content: str
+    timestamp: datetime
+    tool_name: str | None = None
+
+
+@dataclass
+class ConversationRecord:
+    """A complete conversation record."""
+
+    id: str
+    thread_id: str
+    user: str | None
+    started_at: datetime
+    ended_at: datetime
+    messages: list[Message]
+    summary: str | None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class SearchResult:
+    """A search hit from FTS query."""
+
+    conversation_id: str
+    message_content: str
+    role: str
+    timestamp: datetime
+    score: float
+
+
+@dataclass
+class ConversationSummary:
+    """Lightweight conversation listing entry."""
+
+    id: str
+    thread_id: str
+    user: str | None
+    started_at: datetime
+    summary: str | None
+
+
+__all__ = [
+    "ConversationRecord",
+    "ConversationSummary",
+    "MemoryNode",
+    "Message",
+    "SearchResult",
+]

harness_memory-0.1.1.dist-info/METADATA

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: harness-memory
+Version: 0.1.1
+Summary: Pluggable memory system with hierarchical recall, FTS search, and multiple backend support.
+Project-URL: Homepage, https://github.com/orcakit/harness-memory
+Project-URL: Repository, https://github.com/orcakit/harness-memory
+Project-URL: Issues, https://github.com/orcakit/harness-memory/issues
+Author: orcakit
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,fts,llm,memory,recall,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.7; extra == 'qdrant'
+Description-Content-Type: text/markdown
+
+# orcakit-harness-memory
+
+[![CI](https://github.com/orcakit/harness-memory/actions/workflows/ci.yml/badge.svg)](https://github.com/orcakit/harness-memory/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/orcakit-harness-memory.svg)](https://pypi.org/project/orcakit-harness-memory/)
+[![Python versions](https://img.shields.io/pypi/pyversions/orcakit-harness-memory.svg)](https://pypi.org/project/orcakit-harness-memory/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+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
+
+```bash
+pip install orcakit-harness-memory
+```
+
+Optional backends:
+
+```bash
+pip install "orcakit-harness-memory[postgres]"   # PostgreSQL backend
+pip install "orcakit-harness-memory[qdrant]"     # Qdrant vector backend
+```
+
+## Quickstart
+
+```python
+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
+
+```python
+# 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
+
+```bash
+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](LICENSE)

harness_memory-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+harness_memory/__init__.py,sha256=mzFN-KzLxRrWN0AClOnN7p6_4l2j7eINTD0x_zelU50,545
+harness_memory/_version.py,sha256=mEr1FdwwZVMovyM6vpPg2W8zwa1u1f4KdymTrLcqf9U,520
+harness_memory/core.py,sha256=M5JmwiE8OFaw4L-5Hi_on2FiwzwvZWeqkNNqfii4EVc,5691
+harness_memory/types.py,sha256=0NNWR9pAB11h848lsX17tdpquR0BEx5BkB_KLpVIaBY,1458
+harness_memory/backends/__init__.py,sha256=fPFQfNyXNDjZIEmytuhF5EscS5WmDTyUmzSqiaJIHIQ,1307
+harness_memory/backends/postgres.py,sha256=869pBprfgr0AWtdV7eMIADL9EScGj9MoCfPkHFgQEkw,13445
+harness_memory/backends/sqlite.py,sha256=SuJeNyYPomBYNWIGm1Y_cPlvD1HjHI3ySVQmAoR0YqI,12665
+harness_memory-0.1.1.dist-info/METADATA,sha256=ncXEV7OB0Nk9SS9z4wOcwmarIj0NkHPl9AT-FZHqXYk,5533
+harness_memory-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+harness_memory-0.1.1.dist-info/licenses/LICENSE,sha256=KZQwXHx21B5YVep7xogAySPBO_wSTi3er7AUfUK5zuQ,1064
+harness_memory-0.1.1.dist-info/RECORD,,

harness_memory-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

harness_memory-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 orcakit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.