harness-memory 0.1.1__tar.gz

harness_memory-0.1.1/.codebuddy/skills/pypi-publish/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: publish
+description: 当需要发布 Python 包到 PyPI 时使用 — 创建 release 分支、升版本号、更新 CHANGELOG、发布到 PyPI、打 tag、并创建合并请求到 main
+---
+
+# Publish
+
+自动化 Python 包的完整发布流程。
+
+**开始时宣告：** "正在使用 publish 技能发布版本 {VERSION}。"
+
+## 配置项
+
+以下配置有默认值，可在项目的 `.codebuddy/skills/publish/SKILL.md` 中覆盖。
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `PUBLISH_CMD` | 自动检测（见步骤 5） | 发布到 PyPI 的命令 |
+| `CHANGELOG_FILE` | `CHANGELOG.md` | 相对于仓库根目录的路径，文件不存在则跳过 |
+| `VERSION_FILE` | `pyproject.toml` | 包含版本号的文件 |
+| `VERSION_PATTERN` | `^\s*version\s*=\s*"[^"]+"` | 匹配版本行的正则表达式 |
+| `TAG_PREFIX` | ``（空） | Git tag 前缀，设为 `v` 则生成 `v0.1.14` 风格标签 |
+| `REMOTE` | `origin` | Git 远程仓库名 |
+| `TARGET_BRANCH` | `main` | 合并请求的目标分支 |
+| `RELEASE_BRANCH_PREFIX` | `release/` | release 分支名前缀 |
+
+## 调用方式
+
+```
+/publish 0.1.14
+```
+
+目标版本号是唯一必填参数，其余均从配置或自动检测获取。
+
+## 发布流程
+
+### 步骤 1 — 读取配置并确认版本
+
+1. 获取仓库根目录：`git rev-parse --show-toplevel`
+2. 从 `VERSION_FILE` 读取当前版本：
+   ```bash
+   grep -E '^\s*version\s*=\s*"[^"]+"' pyproject.toml
+   ```
+3. 检查未提交的更改：
+   ```bash
+   git status --short
+   ```
+   如果存在未提交的更改，它们将被包含在步骤 4 的发布提交中。这是有意为之 — 所有待处理的工作随版本一起发布。
+4. 查找最近的 git tag：
+   ```bash
+   git tag --sort=-creatordate | head -1
+   ```
+   如果没有 tag，视为首次发布（在步骤 3 中使用从仓库初始到 HEAD 的所有提交）。
+5. 展示确认信息：
+
+```
+当前版本 (pyproject.toml): X.Y.Z
+目标版本:                   A.B.C
+上次发布 tag:               X.Y.Z (YYYY-MM-DD)
+Release 分支:               release/A.B.C
+目标分支 (MR):              main
+
+确认发布 X.Y.Z → A.B.C？[y/N]
+```
+
+如果用户未输入 `y` 确认，立即中止。
+
+### 步骤 2 — 创建 release 分支
+
+从当前 HEAD 创建并切换到新的 release 分支：
+
+```bash
+git checkout -b {RELEASE_BRANCH_PREFIX}{version}
+```
+
+如果分支已存在，中止：
+```
+✗ 分支 {RELEASE_BRANCH_PREFIX}{version} 已存在。
+请手动删除：git branch -D {RELEASE_BRANCH_PREFIX}{version}
+然后重新运行 /publish。
+```
+
+### 步骤 3 — 分析变更并生成 CHANGELOG 草稿
+
+1. 获取上次 tag 以来的提交：
+   ```bash
+   git log {last_tag}..HEAD --oneline
+   # 首次发布时：
+   git log --oneline
+   ```
+
+2. 如果没有找到提交：
+   ```
+   ⚠ 自上次发布 tag ({last_tag}) 以来没有新提交。
+   是否继续？[y/N]
+   ```
+   用户未确认则中止。
+
+3. 按提交前缀分类，生成 Keep a Changelog 格式的条目。
+
+   **CHANGELOG 内容必须用中文书写。** 将每个提交总结为简洁的中文要点 — 不要逐字翻译提交信息。适当合并相关提交。
+
+   分类规则：
+   - 以 `feat:` 或 `feat(` 开头 → **新增**
+   - 以 `fix:` 或 `fix(` 开头 → **修复**
+   - 以 `refactor:` 或 `perf:` 开头 → **变更**
+   - 包含 `!:` 或提交正文含 `BREAKING CHANGE:` → **变更**，加 `**Breaking:**` 前缀
+   - 以 `docs:` 开头 → **变更**
+   - 以 `chore:`、`test:`、`ci:` 开头 → 忽略（基础设施噪音）
+   - 其他所有提交 → **变更**
+   - 移除的功能 → **移除**
+   - 安全修复 → **安全**
+
+   输出格式：
+   ```markdown
+   ## [A.B.C] - YYYY-MM-DD
+
+   ### 新增
+   - 中文描述新增功能
+
+   ### 修复
+   - 中文描述修复内容
+
+   ### 变更
+   - 中文描述行为变更
+
+   ### 移除
+   - 中文描述移除内容
+
+   ### 安全
+   - 中文描述安全修复
+   ```
+   省略空的分类。日期使用 ISO 8601 格式（当天日期）。日期行与第一个分类之间、各分类之间保留空行。
+
+4. 向用户展示草稿并请求确认：
+   ```
+   CHANGELOG 草稿：
+
+   {draft}
+
+   添加到 CHANGELOG.md？[y/N/edit]
+   ```
+   - `y` → 继续
+   - `n` → 中止
+   - `edit` 或其他反馈 → 询问用户："需要什么修改？" — 等待回复后重新生成，再次展示确认。循环直到 `y` 或 `n`。
+
+5. 如果 `CHANGELOG_FILE` 不存在，跳过此步骤（无需警告）。
+
+### 步骤 4 — 更新文件、提交并推送 release 分支
+
+按顺序执行：
+
+**4a. 更新 CHANGELOG：**
+
+在 `CHANGELOG_FILE` 中找到 `## [Unreleased]` 标题，在其后插入新版本条目（保持 `[Unreleased]` 为空）：
+
+```markdown
+## [Unreleased]
+
+## [A.B.C] - YYYY-MM-DD
+### 新增
+- ...
+```
+
+如果 `## [Unreleased]` 标题不存在，在 `# Changelog` 标题行之后插入新条目（若无标题则插入到文件顶部）。
+
+**4b. 升级 VERSION_FILE 中的版本号：**
+
+替换 `VERSION_PATTERN` 匹配到的版本行。对于 `pyproject.toml`：
+```bash
+# 查找当前行：
+grep -n '^\s*version\s*=\s*"[^"]+"' pyproject.toml
+# 用 Edit 工具将该行的 "X.Y.Z" 替换为 "A.B.C"
+```
+
+**4c. 提交：**
+
+检查工作树状态：
+```bash
+git status --short
+```
+
+- 如果有更改（已暂存或未暂存）：暂存所有文件并提交：
+  ```bash
+  git add -A
+  git commit -m "chore: release {version}"
+  ```
+- 如果工作树已干净：无需提交，跳过。
+
+**4d. 推送 release 分支：**
+```bash
+git push -u {REMOTE} {RELEASE_BRANCH_PREFIX}{version}
+```
+
+推送失败则中止。
+
+### 步骤 5 — 发布到 PyPI
+
+**自动检测 PUBLISH_CMD**（仅在配置未覆盖时）：
+
+```bash
+# 检查 Makefile 是否有 publish 目标
+grep -q '^\s*publish\s*:' Makefile 2>/dev/null && echo "make publish" || echo "python -m build && python -m twine upload dist/*"
+```
+
+- 如果 `make publish` 目标存在 → `PUBLISH_CMD=make publish`
+- 否则 → `PUBLISH_CMD=python -m build && python -m twine upload dist/*`
+- 如果 `python -m build` 或 `python -m twine` 未安装，中止："缺少构建工具。请安装：`pip install build twine`"
+
+执行：
+```bash
+{PUBLISH_CMD}
+```
+
+实时输出。如果退出码非零：
+
+```
+✗ 发布失败（退出码 N）。已停止 — 不会创建 tag。
+请检查上方输出，解决问题后重新运行 /publish。
+```
+
+**不继续执行步骤 6。**
+
+### 步骤 6 — 打 tag 并推送
+
+```bash
+git tag {TAG_PREFIX}{version}
+git push {REMOTE} {TAG_PREFIX}{version}
+```
+
+如果 `git tag` 因 tag 已存在而失败：
+```
+✗ Tag {TAG_PREFIX}{version} 已存在。
+请手动删除：git tag -d {TAG_PREFIX}{version}
+然后重新运行 /publish 从此步骤重试。
+```
+中止。
+
+### 步骤 7 — 创建合并请求
+
+使用工丰 MCP 工具从 release 分支创建到 `TARGET_BRANCH` 的合并请求：
+
+1. 从 git remote 检测项目路径：
+   ```bash
+   git remote get-url {REMOTE} | sed -E 's|.*[:/](.+/.+)\.git$|\1|'
+   ```
+
+2. 使用 `mcp__gongfeng__create_merge_request` 创建 MR：
+   - `project_id`：项目完整路径（如 `orcakit/finnie`）
+   - `title`：`chore: release {version}`
+   - `source_branch`：`{RELEASE_BRANCH_PREFIX}{version}`
+   - `target_branch`：`{TARGET_BRANCH}`
+   - `description`：步骤 3 生成的 CHANGELOG 条目
+
+3. 成功时展示：
+   ```
+   ✓ 已发布 {package_name} {version} 到 PyPI
+   ✓ 已创建并推送 tag {TAG_PREFIX}{version} 到 {REMOTE}
+   ✓ 已创建合并请求：{RELEASE_BRANCH_PREFIX}{version} → {TARGET_BRANCH}
+     链接：{mr_url}
+   ```
+
+4. MR 创建失败时展示警告（非致命 — 发布已成功）：
+   ```
+   ⚠ 发布成功，但合并请求创建失败。
+   请手动创建：{RELEASE_BRANCH_PREFIX}{version} → {TARGET_BRANCH}
+   ```
+
+### 步骤 8 — 切回原分支
+
+返回创建 release 分支之前所在的分支：
+
+```bash
+git checkout {original_branch}
+```
+
+确保流程结束后用户不会停留在 release 分支上。
+
+## 错误处理参考
+
+| 场景 | 行为 |
+|------|------|
+| `VERSION_FILE` 未找到 | 中止："找不到 VERSION_FILE：{path}" |
+| 文件中未匹配到版本号 | 中止："在 {VERSION_FILE} 中找不到匹配 {VERSION_PATTERN} 的版本行" |
+| 没有 git tag（首次发布） | 使用从仓库初始到 HEAD 的所有提交；提示"首次发布 — 使用完整 git 历史" |
+| 上次 tag 以来无提交 | 警告并询问是否继续 |
+| Release 分支已存在 | 中止并给出删除指令 |
+| 步骤 4 推送失败 | 中止：文件已在本地更新但未推送 |
+| 步骤 5 发布失败 | 中止：不创建 tag、不创建 MR |
+| 步骤 6 tag 已存在 | 中止并给出删除指令 |
+| 步骤 7 MR 创建失败 | 仅警告（发布已成功） |
+
+## 红线规则
+
+**绝不：**
+- 在发布成功前创建 tag
+- 在发布成功前创建合并请求
+- 跳过步骤 1 的用户确认
+- 跳过步骤 3 的 CHANGELOG 确认
+- 在任何步骤失败后继续执行（步骤 7 MR 失败除外）
+- 流程结束后让用户留在 release 分支
+
+**始终：**
+- 任何失败立即中止（步骤 7 除外）
+- 中止前展示完整错误输出
+- 插入新版本条目后保持 `[Unreleased]` 为空
+- 流程结束时切回原分支

harness_memory-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --all-extras
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+      - run: uv sync --all-extras
+      - run: uv run mypy --strict src
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --all-extras
+      - run: uv run pytest --cov=harness_memory --cov-report=xml -q
+      - uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.12'
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

harness_memory-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v4
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true

harness_memory-0.1.1/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+.env
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+*.sqlite
+src/harness_memory/_version.py

harness_memory-0.1.1/.python-version

@@ -0,0 +1 @@
+3.11

harness_memory-0.1.1/AGENTS.md

@@ -0,0 +1,58 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build & Development Commands
+
+```bash
+make dev          # Install all deps (including optional backends) via uv
+make lint         # ruff check + format check
+make format       # Auto-fix lint + format
+make typecheck    # mypy --strict src
+make test         # pytest -q
+make all          # lint + typecheck + test (full CI check)
+```
+
+Run a single test file or test:
+```bash
+uv run pytest tests/test_core.py -q
+uv run pytest tests/test_sqlite.py::TestSearchMemories -q
+uv run pytest tests/test_sqlite.py::TestSearchMemories::test_fts_finds_matching_nodes -v
+```
+
+## Architecture
+
+This is a pluggable memory system for LLM agents (`orcakit-harness-memory`). Zero runtime dependencies for the core — only stdlib + sqlite3.
+
+### Key Layers
+
+1. **`Memory` (core.py)** — The public API. Wraps a backend and provides `store()`, `recall()`, `add_conversation()`, `search()`, etc. Contains a factory function (`_resolve_memory_backend`) that lazily imports backend implementations by string name.
+
+2. **`MemoryBackend` (backends/__init__.py)** — A `Protocol` (runtime-checkable) defining the storage contract. All backends must implement this interface.
+
+3. **Backends** — Concrete implementations:
+   - `SqliteMemoryBackend` (backends/sqlite.py) — Default. Uses FTS5 for full-text search. Namespace isolation via table-name prefix.
+   - `PostgresMemoryBackend` (backends/postgres.py) — Uses tsvector/GIN for FTS. Namespace isolation via PostgreSQL schemas. Requires `psycopg[binary]>=3.1`.
+   - Qdrant backend referenced but not yet implemented in source.
+
+4. **Types (types.py)** — Pure dataclasses: `MemoryNode`, `Message`, `ConversationRecord`, `SearchResult`, `ConversationSummary`. No logic, no imports beyond stdlib.
+
+### Design Patterns
+
+- **Namespace isolation**: SQLite uses table-name prefixes (`{ns}_memory_nodes`, `{ns}_messages`, etc.); PostgreSQL uses schemas. Namespace is sanitized to `[a-z0-9_]`.
+- **Lazy backend imports**: Optional backends (postgres, qdrant) are imported inside the factory function, so missing extras raise clear `ImportError` messages rather than import-time failures.
+- **FTS sync**: SQLite uses triggers to keep FTS5 virtual tables in sync with source tables; PostgreSQL uses generated `TSVECTOR` columns.
+
+### Test Conventions
+
+- Tests use `tmp_path` fixture to create isolated SQLite databases — no shared state between tests.
+- PostgreSQL tests (`test_postgres.py`) require a running PostgreSQL instance and are typically skipped in local dev.
+- Test classes group related functionality (e.g., `TestStore`, `TestRecall`, `TestConversations`).
+
+## Tooling
+
+- **Package manager**: `uv` (lockfile: `uv.lock`)
+- **Build**: hatchling + hatch-vcs (version from git tags)
+- **Linting**: ruff (line-length 120, target py311)
+- **Type checking**: mypy strict mode
+- **Python**: 3.11+ (tested on 3.11, 3.12, 3.13)

harness_memory-0.1.1/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-05-24
+
+### 新增
+- `Memory` 类 — 统一的记忆存储与召回接口。
+- `MemoryBackend` 协议 — 可插拔的后端抽象。
+- `SqliteMemoryBackend` — 默认后端，基于 FTS5 提供全文搜索。
+- 数据类型：`MemoryNode`、`ConversationRecord`、`Message`、`SearchResult`、`ConversationSummary`。
+- 记忆树：层级化的 root → branch → leaf 结构。
+- 命名空间隔离：多个 agent 可安全共享同一数据库。
+- 后端工厂：将 `"sqlite"` / `"postgres"` / `"qdrant"` 字符串解析为对应实现。
+
+[Unreleased]: https://github.com/orcakit/harness-memory/compare/HEAD...HEAD

harness_memory-0.1.1/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.

harness_memory-0.1.1/Makefile

@@ -0,0 +1,27 @@
+.PHONY: dev lint format typecheck test all publish clean
+
+dev:
+	uv sync --all-extras
+
+lint:
+	uv run ruff check .
+	uv run ruff format --check .
+
+format:
+	uv run ruff check --fix .
+	uv run ruff format .
+
+typecheck:
+	uv run mypy --strict src
+
+test:
+	uv run pytest -q
+
+all: lint typecheck test
+
+publish:
+	uv build
+	uv publish
+
+clean:
+	rm -rf dist/ build/ *.egg-info src/harness_memory/_version.py

harness_memory-0.1.1/PKG-INFO

@@ -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)