octop-memory 0.9.9__tar.gz

octop_memory-0.9.9/.gitignore

@@ -0,0 +1,104 @@
+# OS
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+*.whl
+pip-wheel-metadata/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Node
+# hatchling only honours the ROOT .gitignore when collecting sdist files, so a
+# nested plugins/openclaw/octopmemory/.gitignore is not enough: a local
+# `npm install` (373MB / ~17k files) ends up inside the published sdist.
+node_modules/
+
+# Test / coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.nox/
+.hypothesis/
+
+# IDE / editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+
+# uv
+.uv/
+
+# hatch-vcs auto-generated version file
+src/octop_memory/_version.py
+
+# Personal assistant settings; shared project rules live in AGENTS.md.
+/.codebuddy/
+/.cursor/
+/.claude/
+# Local database diagnostics, never public fixtures.
+/scripts/_smoke_dashboard.py
+*.hmpkg
+*.sqlite.bak
+*.sqlite.before-slim.*.bak
+*.db-journal
+*.sqlite3
+*.sqlite3-wal
+*.sqlite3-shm
+
+# 本地规划文档（开发期 planning，不外发）
+/docs/plans/*.md
+
+# 本地集成自检脚本（dogfood，不属于对外示例）
+/examples/dogfood_*.py
+
+# Local-only checkpoint benchmark
+/scripts/benchmark_checkpoint_storage.py
+
+# Local databases
+*.sqlite
+*.sqlite-journal
+*.sqlite-wal
+*.sqlite-shm
+*.db
+*.db-wal
+*.db-shm
+
+# Logs
+*.log
+logs/

octop_memory-0.9.9/AGENTS.md

@@ -0,0 +1,96 @@
+# AGENTS.md
+
+本文件是所有 coding agent 共用的工作协议。用户入口见 [README_CN.md](README_CN.md)，
+贡献入口见 [CONTRIBUTING.md](CONTRIBUTING.md)，项目认知保留在 `docs/agent/`，宿主接入见
+[docs/integrations.md](docs/integrations.md)。沿用 Harness 的澄清、实现、验证、文档对齐闭环。
+
+## 项目速览
+
+`octop-memory` 是可独立使用的 Agent 记忆组件，为 Octop 及其他宿主提供记忆能力。
+本仓负责证据捕获、事实提炼、召回、存储与迁移；Agent 执行、模型调用调度和用户界面由宿主组织。
+核心是 stdlib + SQLite，PostgreSQL、向量索引和 LLM 通过可选后端/接口接入。
+
+- 公共入口：`Memory`（`core.py`）与 `MemoryService`（`service.py`）；共享编排在 `application/`。
+- 业务流水线在 `pipeline/`，持久化在 `storage/`；CLI / JSON-RPC 在 `adapters/`。
+- `plugins/<host>/` 是外部 Agent 适配目录；当前实现包括 OpenClaw、Hermes，新增宿主复用共享业务逻辑。
+- 按任务找代码和验证入口，见 [PROJECT_MAP](docs/agent/PROJECT_MAP.md) 与 [TEST_MATRIX](docs/agent/TEST_MATRIX.md)。
+
+## 工作方式
+
+- 开始前检查 `git status --short` 和相关 diff，保留用户已有改动。
+- 非平凡改动先说明目标、涉及文件、预期行为、最小验证和风险；大任务分阶段，保持范围聚焦。
+- 代码、测试、配置和文档同步更新；不顺手重构无关模块，不为每次任务新增文档。
+- 中文解释设计，保留代码实体、字段、CLI、环境变量与错误信息原文。
+- 示例使用通用占位符和临时数据库，不提交私人路径、运行记录、凭据、导出记忆或真实数据库。
+
+## Harness 文档闭环
+
+**记录范围**：`docs/agent/` 用于理解代码和接续开发，记录业务逻辑、架构、public API、数据契约、
+召回/写入行为，以及相关 bug、新需求、设计取舍和未解决风险。
+banner、排版、措辞、链接、Python 版本、依赖/锁文件、构建/CI 和个人工具配置等常规维护，
+只更新对应文件及必要的 README/CONTRIBUTING/CHANGELOG，不写入 Harness，也不为此新建 HANDOFF 或 ADR。
+若这类维护同时改变了运行行为或数据契约，仅记录其代码影响，不记录维护操作流水账。
+以下回写要求仅适用于上述代码相关范围；判断依据是实际影响，不是改动文件数量或是否修改了代码文件。
+
+1. **入场核对**：快速扫描相关代码、diff 与近期相关提交，对照 [HANDOFF](docs/agent/HANDOFF.md)
+   和 [PROJECT_MAP](docs/agent/PROJECT_MAP.md)。核对召回 source/顺序、public API、配置、prompt 与验证命令；
+   不依赖日期或提交数推断新鲜度。发现漂移，修正相关描述；范围外缺口记入 [KNOWN_RISKS](docs/agent/KNOWN_RISKS.md)。
+2. **文本澄清**：在现有 Issue / PR 或 HANDOFF 中写明 bug 的实际/预期行为、最小复现，
+   或需求的使用场景、范围/不做什么、可验证验收条件；列出假设和待澄清问题。
+   会改变范围、兼容性或数据安全的未决问题需先澄清；已明确授权的工作继续执行，不重复索要确认。
+3. **实现与验证**：按最小可验证闭环实现，运行相关测试及完整门禁。涉及召回/写入或双 backend 时执行下述硬规则。
+4. **认知回写**：代码相关的非平凡任务更新 HANDOFF 的当前状态、关键文件、验证结果、风险与下一步；
+   模块/调用链/运行策略配置变更更新 PROJECT_MAP；重要代码取舍更新 [DECISIONS](docs/agent/DECISIONS.md)；
+   行为验证方式变更更新 [TEST_MATRIX](docs/agent/TEST_MATRIX.md)；代码相关缺口更新 KNOWN_RISKS；
+   术语变更更新 [GLOSSARY](docs/agent/GLOSSARY.md)，对外行为变更核对 [README_AUDIT](docs/agent/README_AUDIT.md)。
+
+每份文档只承载自己的事实，不重复复制。HANDOFF 保留当前任务/未决项，历史通过 Issue / PR / Git 查阅；
+DECISIONS 保留稳定 ADR 编号及替代关系，不追加日期流水账。只改 HANDOFF 而遗漏受影响的地图或测试矩阵不算完成。
+
+## 架构约束
+
+- `Memory` 为公共存储 API；`MemoryService` / `Bridge` 复用 `application.MemoryRuntime`。
+- pipeline、storage、domain 不依赖 adapters；storage 不依赖 pipeline；service 不依赖 bridge。
+- 新宿主通过 application 接入；现有源码 dashboard 的直接 SQLite 访问不是新模块的模板。
+- `AtomCard` 是事实真源，tree leaf 只引用 atom；Chroma/Qdrant 是可选 index，不是关系 backend。
+- 不擅自改变 public API、数据格式、配置默认值或增加生产依赖。
+
+## 双 backend gate
+
+SQLite/PostgreSQL 均为正式支持的 memory backend。涉及 public 读写、持久化编排、backend contract、
+schema、SQL、transaction、FTS 或 lifecycle 时：
+
+1. 同步维护两种 backend，用同一组行为断言验证，优先扩展 `tests/test_backend_parity.py`。
+2. 使用真实专用 PostgreSQL 和 `TEST_POSTGRES_DSN`，确认相关 PG cases 未 skip。
+3. 有意的单 backend 能力必须明确拒绝另一 backend，并在 KNOWN_RISKS 中说明原因。
+4. backend-specific SQL 留在 `storage/backends/`；不把既有能力缺口当作新代码可以静默分叉的理由。
+
+## 召回与写入敏感路径
+
+| 范围 | 需要说明的影响 |
+|---|---|
+| `core.py`、`storage/backends/` | 公共写入、事务、schema、索引、namespace |
+| `pipeline/extractor/`、`pipeline/promotion/`、`pipeline/episode/` | 哪些内容成为 Candidate、AtomCard 或 Episode |
+| `pipeline/recall/`、`pipeline/page/` | source、排序、raw policy、去重、budget、页面内容 |
+| `application/runtime.py`、`application/path_projection.py`、`application/host_files.py` | 工具搜索、路径可读内容和 host 文件 |
+| `adapters/bridge/handlers.py`、宿主插件 hook | capture/extract、memory_search/memory_get 的宿主行为 |
+
+修改这些行为时，用 `⚠️ 召回/写入路径变更` 明确说明具体影响、受影响 source/layer 和验证命令。
+仅编辑说明或构建清单时说明行为未变，不将文档整理描述为 runtime 变更。
+
+## 验证与交付
+
+```bash
+make install-hooks    # 每个 clone 一次，提交前不得绕过失败门禁
+make all              # format + lint + strict mypy + pytest
+```
+
+代码改动先运行最小相关测试，再执行完整门禁；纯文档维护只需相关文档检查，提交前仍执行完整门禁。
+失败时找到首个根因、做范围内最小修复并重跑；
+环境或既有问题阻止验证时，明确报告失败/skip 和复现命令，不声称通过。
+交付前确认实现符合验收、相关文档与代码一致；属于 Harness 记录范围的任务将实际验证和未解决项写入 HANDOFF；
+无法通过的门禁必须说明根因及后续命令，不能把未验证状态写成完成验收。
+完成回复简述改动、验证和剩余限制即可，不要求固定多节交接模板。
+
+未经用户明确授权，不执行 push、重写 Git 历史、大目录删除、生产部署或密钥修改。
+详细验证与双 backend 命令见 [TEST_MATRIX](docs/agent/TEST_MATRIX.md)，发布检查见 [CONTRIBUTING.md](CONTRIBUTING.md)。

octop_memory-0.9.9/CHANGELOG.md

@@ -0,0 +1,24 @@
+# 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]
+
+### Added
+
+- Distribution `octop-memory`, Python package `octop_memory`, CLI entry points
+  `octop-memory` / `octopmemory-bridge`, and host plugin ID `octopmemory`.
+- Dual memory backends (SQLite + FTS5 default, PostgreSQL optional), optional Chroma/Qdrant
+  indexes, OpenClaw and Hermes host adapters, portable `.hmpkg` export/import.
+- Idle maintenance, SQLite checkpoint compaction, and host-coordinated online slim helpers.
+
+### Notes
+
+- Requires Python 3.12+.
+- Default paths and environment variables use the `OCTOP_MEMORY_*` / `OCTOPMEMORY_*` prefixes;
+  PostgreSQL shared schema is `octop_memory`.
+
+[Unreleased]: https://github.com/TencentCloud/octop-memory/compare/v0.9.9...HEAD

octop_memory-0.9.9/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# 开发指南
+
+从 [README](README_CN.md) 了解用途，从本文了解实现和贡献流程。AI 工作规则只维护在
+[AGENTS.md](AGENTS.md)；外部 Agent 的接入方式、已有适配的安装配置和宿主契约统一见[集成指南](docs/integrations.md)。
+
+## 开始开发
+
+要求 Python 3.12+、支持 FTS5 的 SQLite 和 uv。
+
+```bash
+git clone https://github.com/TencentCloud/octop-memory.git
+cd octop-memory
+make install
+make install-hooks
+make all
+```
+
+从 `main` 创建 `feature/*` 或 `fix/*`，用合成数据复现问题，再添加实现和相关行为测试。
+`make all` 包括 format、lint、strict mypy、pytest；format 会改写文件。pre-commit 执行相同门禁。
+
+源码辅助目录各有用途：`examples/basic_usage.py` 是唯一的基础示例，使用临时数据库演示公共 API、
+组织树和 prompt recall；`evals/recall/` 是合成数据回归工具，指标局限见测试矩阵。
+`scripts/` 保留插件构建、部署和宿主验收入口；部署/E2E 脚本需专用环境，不属于普通单测。
+个人工具设置留在被忽略的 `.claude/`、`.codebuddy/`、`.cursor/` 中，不复制项目规则或发布流程。
+
+## Harness 维护流程
+
+代码相关 bug / 新需求先写明问题、范围和验收，再实现、验证、同步项目认知。已有 Issue / PR 可作为澄清正文，
+在 [HANDOFF](docs/agent/HANDOFF.md) 留链接和当前状态即可；尚未开 Issue 的任务直接使用其中的简短模板。
+规则集中在 [AGENTS.md](AGENTS.md)，人工开发者也沿用同一闭环。
+banner、排版、链接、Python/依赖版本、构建/CI 等常规维护只更新对应文件与必要的用户说明，不写 Harness 记录。
+若同时改变运行行为或数据契约，只记录代码影响。
+
+| 文档 | 单一职责 |
+|---|---|
+| [HANDOFF](docs/agent/HANDOFF.md) | 当前任务的澄清、进度、验证、遗留问题和下一步 |
+| [PROJECT_MAP](docs/agent/PROJECT_MAP.md) | 模块入口、调用链、数据流与边界 |
+| [DECISIONS](docs/agent/DECISIONS.md) | 架构选择、理由、代价和替代关系 |
+| [TEST_MATRIX](docs/agent/TEST_MATRIX.md) | 按改动范围选择验证命令和环境 |
+| [KNOWN_RISKS](docs/agent/KNOWN_RISKS.md) | 当前缺口、限制与应对 |
+| [GLOSSARY](docs/agent/GLOSSARY.md) | 核心术语 |
+| [README_AUDIT](docs/agent/README_AUDIT.md) | 对外声明与实现的核对项 |
+
+仅更新受影响的文档，不为每个任务新建文件；已完成任务的细节由 Issue / PR / Git 保存。
+开发从 [项目地图](docs/agent/PROJECT_MAP.md) 开始，验证命令见 [测试矩阵](docs/agent/TEST_MATRIX.md)，
+已知限制见 [风险清单](docs/agent/KNOWN_RISKS.md)。
+
+## Checkpoint 维护
+
+SQLite `CompactSqliteSaver` 默认复用较大的 `skills_metadata` 和 `memory_contents`，在同库
+`hm_checkpoint_blobs` 保存不可变内容，`harness-checkpoint-v1` checkpoint 保存引用。
+内容和 checkpoint 原子提交，读取时恢复原值；旧 inline 仍可读，历史不会自动批量迁移。
+独立 reader 使用 `CheckpointSerializer.with_connection(conn)` 获取自身 decoder/cache 和一致事务视图。
+
+```bash
+# 默认只读预览。
+octop-memory db slim /path/to/memory.sqlite
+# 停止所有数据库使用者后：自动备份、去重、VACUUM，不删历史。
+octop-memory db slim /path/to/memory.sqlite --apply --offline
+# 降级 reader 前，显式展开旧格式；备份路径必须不存在。
+octop-memory --db /path/to/memory.sqlite db checkpoints \
+  --apply --offline --backup /path/to/new-backup.sqlite --expand
+```
+
+`--offline` 是操作者声明，不会停止进程。备份包含已提交 WAL，并需要额外磁盘空间。
+`OCTOP_MEMORY_CHECKPOINT_DEDUP=0` 仅停止新引用写入，不展开存量；旧 reader 无法直接读取新格式。
+迁移分批提交，重跑跳过已转换行；retention 需显式 completed thread、外部引用和依赖闭包。
+在线 `slim_live_checkpoints` 由宿主负责暂停新 invocation、协调 reader 和恢复；长 reader 可能延期 WAL 回收。
+这些格式维护仅支持 SQLite，明确拒绝 PostgreSQL；PG 使用原 saver，checkpoint_ns 不等于 memory namespace。
+
+## PR 与发布
+
+PR 描述说明问题、改动、验证和剩余限制；用户可见变更更新 `CHANGELOG.md` 的 Unreleased。
+代码相关的非平凡改动更新现有 HANDOFF，并按影响同步地图、决策、测试、风险、术语和 README 核对项；不追加日期流水账。
+
+`main` 是集成分支。发布从 `release/x.y.z`（或 `hotfix/*`）通过 PR 合入 main，
+project version、CHANGELOG 与标签一致。现有 workflow 在合并后创建 `v*` tag 并触发 PyPI/GitHub Release；
+没有发布授权时只验证构建，不推 tag 或上传。
+公开发布统一走上述 PR 与 Actions 流程，不在本地用 `make publish` / `twine upload` 代替；
+发布前检查版本未占用、Unreleased 归档正确和门禁结果，发布后核对 tag 与产物，再按仓库策略清理发布分支。
+
+```bash
+uv build --out-dir dist/package-review
+uv build --wheel --out-dir dist/package-review/direct
+```
+
+首条从 sdist 重建 wheel；比较两种 wheel 解压后的文件名与内容。Python sdist 使用 allowlist，
+独立插件另行构建，测试/CI 留在完整 checkout。插件短 README 是分发入口，详细说明只有集成指南一份。
+
+不要提交 `.env`、数据库/WAL、备份、日志、`.hmpkg`、依赖安装目录或私人运维记录。
+个人 editor 配置、重复发布 skill 和访问个人真实库的诊断脚本不属于公共源码；
+ignore 不删除已跟踪内容，工作树脱敏也不清理 Git 历史或已有附件。漏洞报告见 [SECURITY.md](SECURITY.md)。

octop_memory-0.9.9/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.

octop_memory-0.9.9/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: octop-memory
+Version: 0.9.9
+Summary: Pluggable memory system with hierarchical recall, FTS search, and multiple backend support.
+Project-URL: Homepage, https://github.com/TencentCloud/octop-memory
+Project-URL: Repository, https://github.com/TencentCloud/octop-memory
+Project-URL: Issues, https://github.com/TencentCloud/octop-memory/issues
+Project-URL: Changelog, https://github.com/TencentCloud/octop-memory/blob/main/CHANGELOG.md
+Author: orcakit
+License: 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.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Provides-Extra: chroma
+Requires-Dist: chromadb>=0.4; extra == 'chroma'
+Provides-Extra: cli
+Requires-Dist: click>=8.0; extra == 'cli'
+Provides-Extra: dashboard
+Requires-Dist: click>=8.0; extra == 'dashboard'
+Requires-Dist: fastapi>=0.110; extra == 'dashboard'
+Requires-Dist: uvicorn[standard]>=0.29; extra == 'dashboard'
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=2.2; extra == 'embeddings'
+Provides-Extra: langgraph
+Requires-Dist: langgraph-checkpoint-sqlite>=2.0; extra == 'langgraph'
+Requires-Dist: langgraph-checkpoint>=2.0; extra == 'langgraph'
+Provides-Extra: langgraph-postgres
+Requires-Dist: langgraph-checkpoint-postgres>=2.0; extra == 'langgraph-postgres'
+Requires-Dist: langgraph-checkpoint>=2.0; extra == 'langgraph-postgres'
+Requires-Dist: psycopg[binary]>=3.1; extra == 'langgraph-postgres'
+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
+
+<p align="center">
+  <img src="assets/images/banner.jpeg" alt="Octop Memory" width="600" />
+</p>
+
+# Octop Memroy
+
+**Persistent, portable memory for LLM agents.** Store facts, capture conversations, and retrieve relevant context through a shared Python runtime or host adapters.
+
+[中文](README_CN.md) · [Developer guide](CONTRIBUTING.md) · [Integrations](docs/integrations.md) · [MIT License](LICENSE)
+
+## Project scope
+
+Octop Memory provides cross-session memory for personal assistants, ongoing project work, and existing agents.
+It is the memory component in the Octop ecosystem and can also run independently as a Python library,
+CLI, or JSON-RPC bridge, without installing Octop. This repository owns memory capture, extraction, retrieval, storage,
+and migration; the host application manages agent execution, tool scheduling, and user interfaces.
+
+## What it provides
+
+- **Long-term memory:** extract candidates from raw events, then promote, merge, or review them into facts (`AtomCard`). Entity pages consolidate facts, episodes describe events, and the tree provides a hierarchical view.
+- **Recall:** full-text search, optional vector search, ranking, deduplication, and a token budget for prompt context.
+- **Two storage backends:** SQLite + FTS5 by default, PostgreSQL for server deployments. Chroma and Qdrant are optional vector indexes alongside either backend.
+- **External agent adapters:** `MemoryService` for Python hosts and a JSON-RPC bridge for cross-language/subprocess hosts. Host adapters live in `plugins/`, currently including OpenClaw and Hermes.
+- **Portability:** export/import and `.hmpkg` packages for moving memory between supported hosts.
+- **Optional LangGraph checkpoints:** conversation recovery state alongside long-term memory.
+
+The core requires **Python 3.12+**, aligned with Octop’s Python 3.12 baseline, and uses only the standard library, including `sqlite3` with FTS5. Manual storage and lexical recall need no model. Automated extraction, promotion checks, and page regeneration can use an injected `LLMClient`; installing the package alone does not configure a model.
+
+## Quick start
+
+```bash
+pip install octop-memory
+```
+
+```python
+from octop_memory import Memory, MemoryService
+
+memory = Memory(
+    namespace="demo",
+    backend_config={"db_path": "./demo.sqlite"},
+)
+memory.store("User prefers Python for backend services", topic="preferences")
+
+# Basic fact search returns MemoryNode leaf projections.
+for node in memory.recall("Python"):
+    print(node.content)
+
+# Prompt recall adds source selection, ranking, deduplication, and budgeting.
+result = MemoryService(memory).recall("Python")
+print(result.rendered)
+```
+
+This creates a local database. Use terms present in the stored text for a minimal FTS example. `Memory.search()` searches archived conversation messages; it is a separate API from fact recall.
+
+### Optional dependencies
+
+| Install | Purpose |
+|---|---|
+| `pip install "octop-memory[cli]"` | CLI and OpenClaw setup commands |
+| `pip install "octop-memory[postgres]"` | PostgreSQL memory backend |
+| `pip install "octop-memory[chroma,embeddings]"` | Chroma index and local embeddings |
+| `pip install "octop-memory[qdrant,embeddings]"` | Qdrant index and local embeddings |
+| `pip install "octop-memory[langgraph]"` | SQLite LangGraph checkpointer |
+| `pip install "octop-memory[langgraph-postgres]"` | PostgreSQL LangGraph checkpointer |
+
+Vector search requires constructing and injecting `vector_index` and `embedding_provider` into `Memory`; an extra installs dependencies only. The database backend remains `sqlite` or `postgres`.
+
+```python
+memory = Memory(
+    namespace="demo",
+    backend="postgres",
+    backend_config={"dsn": "postgresql://user:pass@localhost/octop_memory"},
+)
+```
+
+Use deployment configuration for real credentials. SQLite isolates memory with table prefixes; PostgreSQL uses namespace-first keys in the shared `octop_memory` schema.
+
+## Code architecture
+
+```text
+src/octop_memory/
+├── core.py / types.py     # Public Memory API and data structures
+├── service.py            # MemoryService: Python host entry point
+├── application/          # MemoryRuntime, config, host files, path projection
+├── pipeline/             # Extraction, promotion, recall, pages, episodes, lifecycle
+├── storage/              # SQLite / PostgreSQL, checkpoints, vector indexes
+├── ports/                # External capability interfaces, including LLM clients
+├── domain/               # Shared alias and time rules
+├── adapters/             # JSON-RPC bridge, CLI, source-only dashboard
+└── operations/           # Import/export, migration, portable packages
+plugins/                  # External agent adapters, organized by host
+examples/                 # Public API example
+tests/ / evals/           # Behavior tests / synthetic recall evaluation
+docs/agent/               # Harness project map, decisions, and handoff
+```
+
+Adapters call inward through application and pipeline/core/storage layers. `MemoryService` and `Bridge`
+share `MemoryRuntime`; pipeline/storage do not depend on adapters, and backend-specific SQL stays in storage.
+The source dashboard's direct SQLite access is an existing exception.
+
+### Host call flow
+
+```text
+Python host → MemoryService ─────────┐
+Hermes → in-process Bridge ──────────┤
+OpenClaw → JSON-RPC bridge ───────────┴→ MemoryRuntime → pipelines → Memory
+CLI → application / operations ────────────────────────────────────┘
+                                                     ├→ SQLite / PostgreSQL
+                                                     └→ optional vector index
+```
+
+Hermes currently calls `Bridge` in-process; OpenClaw uses a bridge subprocess. `MemoryService.recall()` also calls the recall pipeline directly. Facts live in `AtomCard`; tree leaves reference atoms and project their content. The tree is an organization view, not an additional copy or independent recall source.
+
+### Long-term memory flow
+
+```text
+RawEvent ──extraction──→ Candidate ──promotion──→ AtomCard ──dirty / regeneration──→ EntityPage
+    └──episode extraction──→ Episode                └──atom_id reference──→ tree leaf
+```
+
+Candidates do not all require human approval. Promotion checks value, evidence, entity resolution,
+duplicates, and conflicts; it can promote, merge, or drop candidates automatically, leaving review/conflict
+cases for user action. Pages are marked dirty and regenerated when triggered by runtime/CLI/host,
+rather than immediately after every write. Episode extraction is a parallel path from raw events.
+Manual `Memory.store()` needs no model and directly creates RawEvent/Candidate/AtomCard plus a leaf reference.
+
+Prompt recall routes `atom` and `raw` by default, adds `page_headline` when an entity is resolved, and adds `vector` when configured. With the default raw fallback policy, durable hits suppress raw; passing the current session/thread excludes its raw events from prompt injection.
+
+Start with [CONTRIBUTING.md](CONTRIBUTING.md); the [project map](docs/agent/PROJECT_MAP.md) covers architecture and data flow. AI contributors use [AGENTS.md](AGENTS.md), with task clarification and handoff in [HANDOFF.md](docs/agent/HANDOFF.md).
+
+## CLI
+
+Install `[cli]`. Global options precede subcommands; use an explicit database and namespace when following examples.
+
+```bash
+octop-memory --db ./demo.sqlite --namespace demo memory store --content "User prefers Python"
+octop-memory --db ./demo.sqlite --namespace demo recall "Python"
+octop-memory --db ./demo.sqlite --namespace demo memory tree
+octop-memory --help
+```
+
+| Commands | Purpose |
+|---|---|
+| `raw`, `candidate`, `atom`, `entity`, `page` | Inspect and manage memory layers |
+| `episode`, `digest`, `journal` | Event summaries and decision records |
+| `memory`, `recall`, `thread` | Tree operations, prompt recall, thread state |
+| `export`, `import`, `migrate`, `portable` | Backup and migration |
+| `db`, `gc`, `consolidate` | Storage maintenance and lifecycle operations |
+| `config`, `openclaw`, `backfill` | Configuration, integration, historical extraction |
+
+Run `<command> --help` for arguments. `db slim FILE` previews SQLite checkpoint deduplication; `--apply --offline` creates a backup and performs it without deleting history. Read [checkpoint compatibility and maintenance](CONTRIBUTING.md#checkpoint-维护) before migration or reader downgrade.
+
+The dashboard is available from a source checkout with `[dashboard]` dependencies; its modules are currently excluded from the wheel. Installing `octop-memory[dashboard]` from PyPI alone does not provide the dashboard command.
+
+## External agent adapters
+
+`plugins/<host>/` maps external agent hooks, tools, and configuration to the shared Python runtime.
+OpenClaw and Hermes adapters are available today. Other agents can integrate through the Python API or JSON-RPC,
+with an adapter implementing their host contract.
+
+| Integration | Use case | Entry point |
+|---|---|---|
+| In-process Python | Custom agents / Python applications | `MemoryService.capture_turn()` / `recall()` / `search()` / `get()` / `extract()` |
+| JSON-RPC bridge | Cross-language or separate processes | stdio `octopmemory-bridge` |
+| Host plugin | Agent-specific lifecycle and tool interfaces | `plugins/<host>/`; OpenClaw and Hermes currently implemented |
+
+See the [integration guide](docs/integrations.md) for installation, configuration, profiles, troubleshooting, and adapter boundaries.
+
+Move memory with `octop-memory portable list-sources / pack / adopt / doctor`. Exported `.hmpkg` files contain memory data; keep them out of source control.
+
+## Development
+
+```bash
+make install          # uv sync --group dev
+make install-hooks    # required once per clone
+make all              # format + lint + strict mypy + tests
+uv build              # Python wheel + source distribution
+```
+
+Run PostgreSQL behavior tests against a real test server with `TEST_POSTGRES_DSN`; skipped PG cases do not prove compatibility. OpenClaw has its own `npm ci`, `npm test`, and `npm run build` under `plugins/openclaw/octopmemory/`.
+
+The repository retains tests, CI, examples, and plugins; the Python sdist contains the sources needed to rebuild the wheel. Development and release procedures live in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE). Report vulnerabilities through the channels in [SECURITY.md](SECURITY.md).