colink-memory 1.0.3.post1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- colink_memory-1.0.3.post1/.gitignore +111 -0
- colink_memory-1.0.3.post1/AGENTS.md +96 -0
- colink_memory-1.0.3.post1/CHANGELOG.md +243 -0
- colink_memory-1.0.3.post1/CONTRIBUTING.md +116 -0
- colink_memory-1.0.3.post1/LICENSE +21 -0
- colink_memory-1.0.3.post1/PKG-INFO +272 -0
- colink_memory-1.0.3.post1/README.md +227 -0
- colink_memory-1.0.3.post1/README_CN.md +224 -0
- colink_memory-1.0.3.post1/SECURITY.md +28 -0
- colink_memory-1.0.3.post1/assets/images/banner.jpeg +0 -0
- colink_memory-1.0.3.post1/docs/agent/DECISIONS.md +239 -0
- colink_memory-1.0.3.post1/docs/agent/GLOSSARY.md +24 -0
- colink_memory-1.0.3.post1/docs/agent/HANDOFF.md +98 -0
- colink_memory-1.0.3.post1/docs/agent/KNOWN_RISKS.md +33 -0
- colink_memory-1.0.3.post1/docs/agent/PROJECT_MAP.md +116 -0
- colink_memory-1.0.3.post1/docs/agent/README_AUDIT.md +23 -0
- colink_memory-1.0.3.post1/docs/agent/TEST_MATRIX.md +68 -0
- colink_memory-1.0.3.post1/docs/integrations.md +264 -0
- colink_memory-1.0.3.post1/pyproject.toml +166 -0
- colink_memory-1.0.3.post1/src/octop_memory/__init__.py +56 -0
- colink_memory-1.0.3.post1/src/octop_memory/_config_io.py +98 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/__init__.py +1 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/bridge/__init__.py +37 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/bridge/handlers.py +127 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/bridge/server.py +343 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/__init__.py +130 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/atom_cmd.py +143 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/candidate_cmd.py +795 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/checkpoint_cmd.py +81 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/config.py +155 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/consolidate_cmd.py +123 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/dashboard.py +125 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/db_cmd.py +268 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/entity_cmd.py +121 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/episode_cmd.py +239 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/gc_cmd.py +97 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/journal_cmd.py +114 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/memory_cmd.py +290 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/migration_cmd.py +330 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/openclaw_cmd.py +624 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/page_cmd.py +267 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/portable_cmd.py +279 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/raw_cmd.py +229 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/recall_cmd.py +127 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/slim_cmd.py +84 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/cli/thread_cmd.py +152 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/dashboard/__init__.py +8 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/dashboard/server.py +712 -0
- colink_memory-1.0.3.post1/src/octop_memory/adapters/dashboard/static/index.html +892 -0
- colink_memory-1.0.3.post1/src/octop_memory/application/__init__.py +1 -0
- colink_memory-1.0.3.post1/src/octop_memory/application/checkpoint_maintenance.py +28 -0
- colink_memory-1.0.3.post1/src/octop_memory/application/config.py +76 -0
- colink_memory-1.0.3.post1/src/octop_memory/application/dashboard_data.py +1218 -0
- colink_memory-1.0.3.post1/src/octop_memory/application/host_files.py +512 -0
- colink_memory-1.0.3.post1/src/octop_memory/application/path_projection.py +349 -0
- colink_memory-1.0.3.post1/src/octop_memory/application/runtime.py +1165 -0
- colink_memory-1.0.3.post1/src/octop_memory/core.py +1887 -0
- colink_memory-1.0.3.post1/src/octop_memory/domain/__init__.py +1 -0
- colink_memory-1.0.3.post1/src/octop_memory/domain/alias.py +43 -0
- colink_memory-1.0.3.post1/src/octop_memory/domain/datetime.py +23 -0
- colink_memory-1.0.3.post1/src/octop_memory/domain/retention.py +50 -0
- colink_memory-1.0.3.post1/src/octop_memory/operations/__init__.py +1 -0
- colink_memory-1.0.3.post1/src/octop_memory/operations/migration/__init__.py +45 -0
- colink_memory-1.0.3.post1/src/octop_memory/operations/migration/backfill.py +282 -0
- colink_memory-1.0.3.post1/src/octop_memory/operations/migration/export.py +305 -0
- colink_memory-1.0.3.post1/src/octop_memory/operations/migration/import_.py +384 -0
- colink_memory-1.0.3.post1/src/octop_memory/operations/migration/portable/__init__.py +84 -0
- colink_memory-1.0.3.post1/src/octop_memory/operations/migration/portable/adopter.py +469 -0
- colink_memory-1.0.3.post1/src/octop_memory/operations/migration/portable/doctor.py +377 -0
- colink_memory-1.0.3.post1/src/octop_memory/operations/migration/portable/models.py +253 -0
- colink_memory-1.0.3.post1/src/octop_memory/operations/migration/portable/packer.py +264 -0
- colink_memory-1.0.3.post1/src/octop_memory/operations/migration/portable/sources.py +246 -0
- colink_memory-1.0.3.post1/src/octop_memory/operations/migration/preview.py +95 -0
- colink_memory-1.0.3.post1/src/octop_memory/operations/migration/rename.py +420 -0
- colink_memory-1.0.3.post1/src/octop_memory/operations/retention.py +507 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/__init__.py +1 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/episode/__init__.py +375 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/episode/digest.py +496 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/episode/prompts.py +157 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/extractor/__init__.py +365 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/extractor/parser.py +394 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/extractor/prompts.py +471 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/lifecycle/__init__.py +83 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/lifecycle/checkpoint_gc.py +629 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/lifecycle/consolidate.py +368 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/lifecycle/gc.py +368 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/lifecycle/maintenance.py +339 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/lifecycle/vacuum.py +679 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/page/__init__.py +54 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/page/headline.py +58 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/page/prompts.py +110 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/page/regenerator.py +422 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/page/trigger.py +73 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/page/user_notes.py +105 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/promotion/__init__.py +638 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/promotion/checks.py +715 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/promotion/fallback.py +294 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/promotion/llm_hook.py +265 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/recall/__init__.py +584 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/recall/budget.py +164 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/recall/cache.py +100 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/recall/diversify.py +67 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/recall/multi_source.py +489 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/recall/parser.py +273 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/recall/rerank.py +298 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/recall/router.py +118 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/recall/suppress.py +142 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/recall/thread_state.py +148 -0
- colink_memory-1.0.3.post1/src/octop_memory/pipeline/recall/timeout.py +123 -0
- colink_memory-1.0.3.post1/src/octop_memory/ports/__init__.py +1 -0
- colink_memory-1.0.3.post1/src/octop_memory/ports/llm/__init__.py +49 -0
- colink_memory-1.0.3.post1/src/octop_memory/ports/llm/_protocol.py +114 -0
- colink_memory-1.0.3.post1/src/octop_memory/ports/llm/mock.py +115 -0
- colink_memory-1.0.3.post1/src/octop_memory/ports/llm/openai_compat.py +217 -0
- colink_memory-1.0.3.post1/src/octop_memory/service.py +334 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/__init__.py +1 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/backends/__init__.py +623 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/backends/forget.py +279 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/backends/fts_text.py +91 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/backends/postgres.py +2477 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/backends/postgres_pool.py +140 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/backends/sqlite.py +2491 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/backends/sqlite_checkpoint.py +219 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/backends/sqlite_checkpoint_job.py +114 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/backends/sqlite_checkpoint_live.py +88 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/backends/sqlite_checkpoint_maintenance.py +267 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/driver_errors.py +64 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/vector/__init__.py +104 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/vector/chroma.py +165 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/vector/embeddings.py +262 -0
- colink_memory-1.0.3.post1/src/octop_memory/storage/vector/qdrant.py +196 -0
- colink_memory-1.0.3.post1/src/octop_memory/types.py +575 -0
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
# OS
|
|
2
|
+
.DS_Store
|
|
3
|
+
.DS_Store?
|
|
4
|
+
._*
|
|
5
|
+
.Spotlight-V100
|
|
6
|
+
.Trashes
|
|
7
|
+
Thumbs.db
|
|
8
|
+
ehthumbs.db
|
|
9
|
+
Desktop.ini
|
|
10
|
+
|
|
11
|
+
# Environment / secrets
|
|
12
|
+
.env
|
|
13
|
+
.env.*
|
|
14
|
+
!.env.example
|
|
15
|
+
|
|
16
|
+
# Python
|
|
17
|
+
__pycache__/
|
|
18
|
+
*.py[cod]
|
|
19
|
+
*$py.class
|
|
20
|
+
*.so
|
|
21
|
+
.Python
|
|
22
|
+
build/
|
|
23
|
+
dist/
|
|
24
|
+
*.egg-info/
|
|
25
|
+
*.egg
|
|
26
|
+
.eggs/
|
|
27
|
+
wheels/
|
|
28
|
+
*.whl
|
|
29
|
+
pip-wheel-metadata/
|
|
30
|
+
|
|
31
|
+
# Virtual environments
|
|
32
|
+
.venv/
|
|
33
|
+
venv/
|
|
34
|
+
env/
|
|
35
|
+
ENV/
|
|
36
|
+
|
|
37
|
+
# Node
|
|
38
|
+
# hatchling only honours the ROOT .gitignore when collecting sdist files, so a
|
|
39
|
+
# nested plugins/openclaw/octopmemory/.gitignore is not enough: a local
|
|
40
|
+
# `npm install` (373MB / ~17k files) ends up inside the published sdist.
|
|
41
|
+
node_modules/
|
|
42
|
+
|
|
43
|
+
# Test / coverage
|
|
44
|
+
.pytest_cache/
|
|
45
|
+
.mypy_cache/
|
|
46
|
+
.ruff_cache/
|
|
47
|
+
.coverage
|
|
48
|
+
.coverage.*
|
|
49
|
+
htmlcov/
|
|
50
|
+
coverage.xml
|
|
51
|
+
.tox/
|
|
52
|
+
.nox/
|
|
53
|
+
.hypothesis/
|
|
54
|
+
|
|
55
|
+
# IDE / editors
|
|
56
|
+
.vscode/
|
|
57
|
+
.idea/
|
|
58
|
+
*.swp
|
|
59
|
+
*.swo
|
|
60
|
+
*~
|
|
61
|
+
.project
|
|
62
|
+
.pydevproject
|
|
63
|
+
|
|
64
|
+
# uv
|
|
65
|
+
.uv/
|
|
66
|
+
|
|
67
|
+
# hatch-vcs auto-generated version file
|
|
68
|
+
src/octop_memory/_version.py
|
|
69
|
+
|
|
70
|
+
# Personal assistant settings; shared project rules live in AGENTS.md.
|
|
71
|
+
# Track the shared publish skill (Octop-style); ignore everything else under these dirs.
|
|
72
|
+
/.codebuddy/*
|
|
73
|
+
!/.codebuddy/skills/
|
|
74
|
+
!/.codebuddy/skills/publish/
|
|
75
|
+
!/.codebuddy/skills/publish/**
|
|
76
|
+
/.cursor/*
|
|
77
|
+
!/.cursor/skills/
|
|
78
|
+
!/.cursor/skills/publish/
|
|
79
|
+
!/.cursor/skills/publish/**
|
|
80
|
+
/.claude/
|
|
81
|
+
# Local database diagnostics, never public fixtures.
|
|
82
|
+
/scripts/_smoke_dashboard.py
|
|
83
|
+
*.hmpkg
|
|
84
|
+
*.sqlite.bak
|
|
85
|
+
*.sqlite.before-slim.*.bak
|
|
86
|
+
*.db-journal
|
|
87
|
+
*.sqlite3
|
|
88
|
+
*.sqlite3-wal
|
|
89
|
+
*.sqlite3-shm
|
|
90
|
+
|
|
91
|
+
# 本地规划文档(开发期 planning,不外发)
|
|
92
|
+
/docs/plans/*.md
|
|
93
|
+
|
|
94
|
+
# 本地集成自检脚本(dogfood,不属于对外示例)
|
|
95
|
+
/examples/dogfood_*.py
|
|
96
|
+
|
|
97
|
+
# Local-only checkpoint benchmark
|
|
98
|
+
/scripts/benchmark_checkpoint_storage.py
|
|
99
|
+
|
|
100
|
+
# Local databases
|
|
101
|
+
*.sqlite
|
|
102
|
+
*.sqlite-journal
|
|
103
|
+
*.sqlite-wal
|
|
104
|
+
*.sqlite-shm
|
|
105
|
+
*.db
|
|
106
|
+
*.db-wal
|
|
107
|
+
*.db-shm
|
|
108
|
+
|
|
109
|
+
# Logs
|
|
110
|
+
*.log
|
|
111
|
+
logs/
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# AGENTS.md
|
|
2
|
+
|
|
3
|
+
本文件是所有 coding agent 共用的工作协议。用户入口见 [README_CN.md](README_CN.md),
|
|
4
|
+
贡献入口见 [CONTRIBUTING.md](CONTRIBUTING.md),项目认知保留在 `docs/agent/`,宿主接入见
|
|
5
|
+
[docs/integrations.md](docs/integrations.md)。沿用 Harness 的澄清、实现、验证、文档对齐闭环。
|
|
6
|
+
|
|
7
|
+
## 项目速览
|
|
8
|
+
|
|
9
|
+
`octop-memory` 是可独立使用的 Agent 记忆组件,为 Octop / octop-harness 及其他宿主提供记忆能力。
|
|
10
|
+
本仓负责证据捕获、事实提炼、召回、存储与迁移;Agent 执行、模型调用调度和用户界面由宿主组织。
|
|
11
|
+
核心是 stdlib + SQLite,PostgreSQL、向量索引和 LLM 通过可选后端/接口接入。
|
|
12
|
+
|
|
13
|
+
- 公共入口:`Memory`(`core.py`)与 `MemoryService`(`service.py`);共享编排在 `application/`。
|
|
14
|
+
- 业务流水线在 `pipeline/`,持久化在 `storage/`;CLI / JSON-RPC 在 `adapters/`。
|
|
15
|
+
- `plugins/<host>/` 是外部 Agent 适配目录;当前实现包括 OpenClaw、Hermes,新增宿主复用共享业务逻辑。
|
|
16
|
+
- 按任务找代码和验证入口,见 [PROJECT_MAP](docs/agent/PROJECT_MAP.md) 与 [TEST_MATRIX](docs/agent/TEST_MATRIX.md)。
|
|
17
|
+
|
|
18
|
+
## 工作方式
|
|
19
|
+
|
|
20
|
+
- 开始前检查 `git status --short` 和相关 diff,保留用户已有改动。
|
|
21
|
+
- 非平凡改动先说明目标、涉及文件、预期行为、最小验证和风险;大任务分阶段,保持范围聚焦。
|
|
22
|
+
- 代码、测试、配置和文档同步更新;不顺手重构无关模块,不为每次任务新增文档。
|
|
23
|
+
- 中文解释设计,保留代码实体、字段、CLI、环境变量与错误信息原文。
|
|
24
|
+
- 示例使用通用占位符和临时数据库,不提交私人路径、运行记录、凭据、导出记忆或真实数据库。
|
|
25
|
+
|
|
26
|
+
## Harness 文档闭环
|
|
27
|
+
|
|
28
|
+
**记录范围**:`docs/agent/` 用于理解代码和接续开发,记录业务逻辑、架构、public API、数据契约、
|
|
29
|
+
召回/写入行为,以及相关 bug、新需求、设计取舍和未解决风险。
|
|
30
|
+
banner、排版、措辞、链接、Python 版本、依赖/锁文件、构建/CI 和个人工具配置等常规维护,
|
|
31
|
+
只更新对应文件及必要的 README/CONTRIBUTING/CHANGELOG,不写入 Harness,也不为此新建 HANDOFF 或 ADR。
|
|
32
|
+
若这类维护同时改变了运行行为或数据契约,仅记录其代码影响,不记录维护操作流水账。
|
|
33
|
+
以下回写要求仅适用于上述代码相关范围;判断依据是实际影响,不是改动文件数量或是否修改了代码文件。
|
|
34
|
+
|
|
35
|
+
1. **入场核对**:快速扫描相关代码、diff 与近期相关提交,对照 [HANDOFF](docs/agent/HANDOFF.md)
|
|
36
|
+
和 [PROJECT_MAP](docs/agent/PROJECT_MAP.md)。核对召回 source/顺序、public API、配置、prompt 与验证命令;
|
|
37
|
+
不依赖日期或提交数推断新鲜度。发现漂移,修正相关描述;范围外缺口记入 [KNOWN_RISKS](docs/agent/KNOWN_RISKS.md)。
|
|
38
|
+
2. **文本澄清**:在现有 Issue / PR 或 HANDOFF 中写明 bug 的实际/预期行为、最小复现,
|
|
39
|
+
或需求的使用场景、范围/不做什么、可验证验收条件;列出假设和待澄清问题。
|
|
40
|
+
会改变范围、兼容性或数据安全的未决问题需先澄清;已明确授权的工作继续执行,不重复索要确认。
|
|
41
|
+
3. **实现与验证**:按最小可验证闭环实现,运行相关测试及完整门禁。涉及召回/写入或双 backend 时执行下述硬规则。
|
|
42
|
+
4. **认知回写**:代码相关的非平凡任务更新 HANDOFF 的当前状态、关键文件、验证结果、风险与下一步;
|
|
43
|
+
模块/调用链/运行策略配置变更更新 PROJECT_MAP;重要代码取舍更新 [DECISIONS](docs/agent/DECISIONS.md);
|
|
44
|
+
行为验证方式变更更新 [TEST_MATRIX](docs/agent/TEST_MATRIX.md);代码相关缺口更新 KNOWN_RISKS;
|
|
45
|
+
术语变更更新 [GLOSSARY](docs/agent/GLOSSARY.md),对外行为变更核对 [README_AUDIT](docs/agent/README_AUDIT.md)。
|
|
46
|
+
|
|
47
|
+
每份文档只承载自己的事实,不重复复制。HANDOFF 保留当前任务/未决项,历史通过 Issue / PR / Git 查阅;
|
|
48
|
+
DECISIONS 保留稳定 ADR 编号及替代关系,不追加日期流水账。只改 HANDOFF 而遗漏受影响的地图或测试矩阵不算完成。
|
|
49
|
+
|
|
50
|
+
## 架构约束
|
|
51
|
+
|
|
52
|
+
- `Memory` 为公共存储 API;`MemoryService` / `Bridge` 复用 `application.MemoryRuntime`。
|
|
53
|
+
- pipeline、storage、domain 不依赖 adapters;storage 不依赖 pipeline;service 不依赖 bridge。
|
|
54
|
+
- 新宿主通过 application 接入;现有源码 dashboard 的直接 SQLite 访问不是新模块的模板。
|
|
55
|
+
- `AtomCard` 是事实真源,tree leaf 只引用 atom;Chroma/Qdrant 是可选 index,不是关系 backend。
|
|
56
|
+
- 不擅自改变 public API、数据格式、配置默认值或增加生产依赖。
|
|
57
|
+
|
|
58
|
+
## 双 backend gate
|
|
59
|
+
|
|
60
|
+
SQLite/PostgreSQL 均为正式支持的 memory backend。涉及 public 读写、持久化编排、backend contract、
|
|
61
|
+
schema、SQL、transaction、FTS 或 lifecycle 时:
|
|
62
|
+
|
|
63
|
+
1. 同步维护两种 backend,用同一组行为断言验证,优先扩展 `tests/test_backend_parity.py`。
|
|
64
|
+
2. 使用真实专用 PostgreSQL 和 `TEST_POSTGRES_DSN`,确认相关 PG cases 未 skip。
|
|
65
|
+
3. 有意的单 backend 能力必须明确拒绝另一 backend,并在 KNOWN_RISKS 中说明原因。
|
|
66
|
+
4. backend-specific SQL 留在 `storage/backends/`;不把既有能力缺口当作新代码可以静默分叉的理由。
|
|
67
|
+
|
|
68
|
+
## 召回与写入敏感路径
|
|
69
|
+
|
|
70
|
+
| 范围 | 需要说明的影响 |
|
|
71
|
+
|---|---|
|
|
72
|
+
| `core.py`、`storage/backends/` | 公共写入、事务、schema、索引、namespace |
|
|
73
|
+
| `pipeline/extractor/`、`pipeline/promotion/`、`pipeline/episode/` | 哪些内容成为 Candidate、AtomCard 或 Episode |
|
|
74
|
+
| `pipeline/recall/`、`pipeline/page/` | source、排序、raw policy、去重、budget、页面内容 |
|
|
75
|
+
| `application/runtime.py`、`application/path_projection.py`、`application/host_files.py` | 工具搜索、路径可读内容和 host 文件 |
|
|
76
|
+
| `adapters/bridge/handlers.py`、宿主插件 hook | capture/extract、memory_search/memory_get 的宿主行为 |
|
|
77
|
+
|
|
78
|
+
修改这些行为时,用 `⚠️ 召回/写入路径变更` 明确说明具体影响、受影响 source/layer 和验证命令。
|
|
79
|
+
仅编辑说明或构建清单时说明行为未变,不将文档整理描述为 runtime 变更。
|
|
80
|
+
|
|
81
|
+
## 验证与交付
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
make install-hooks # 每个 clone 一次,提交前不得绕过失败门禁
|
|
85
|
+
make all # format + lint + strict mypy + pytest
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
代码改动先运行最小相关测试,再执行完整门禁;纯文档维护只需相关文档检查,提交前仍执行完整门禁。
|
|
89
|
+
失败时找到首个根因、做范围内最小修复并重跑;
|
|
90
|
+
环境或既有问题阻止验证时,明确报告失败/skip 和复现命令,不声称通过。
|
|
91
|
+
交付前确认实现符合验收、相关文档与代码一致;属于 Harness 记录范围的任务将实际验证和未解决项写入 HANDOFF;
|
|
92
|
+
无法通过的门禁必须说明根因及后续命令,不能把未验证状态写成完成验收。
|
|
93
|
+
完成回复简述改动、验证和剩余限制即可,不要求固定多节交接模板。
|
|
94
|
+
|
|
95
|
+
未经用户明确授权,不执行 push、重写 Git 历史、大目录删除、生产部署或密钥修改。
|
|
96
|
+
详细验证与双 backend 命令见 [TEST_MATRIX](docs/agent/TEST_MATRIX.md),分支与发布检查见 [CONTRIBUTING.md](CONTRIBUTING.md)(`develop` 集成 + `/publish` skill)。
|
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
## [1.0.3.post1] - 2026-11-20
|
|
11
|
+
|
|
12
|
+
### 修复
|
|
13
|
+
|
|
14
|
+
- 支持彻底遗忘指定记忆及其派生记录,同时清理来源引用和搜索索引。SQLite 与 PostgreSQL 行为保持一致。
|
|
15
|
+
|
|
16
|
+
## [1.0.3] - 2026-11-04
|
|
17
|
+
|
|
18
|
+
### 修复
|
|
19
|
+
|
|
20
|
+
- 候选提炼按单批事件数(默认 100)与字符预算(默认 20,000)分批调用模型,不再把整个 session 的事件塞进一次请求;此前长会话积压会让 prompt 超出上下文、以「长度截断 / 超时」失败(#25)。
|
|
21
|
+
- 「已提炼」游标写入 `{ns}_meta`(`extracted_ids/v1/<session>`),重启后从 meta 恢复,不再整段重跑(#25)。增量提取路径以 `strict=True` 持久化游标:游标写失败会让整个事务回滚、候选写入一并撤销,事件留在未提炼状态等待重试,而非被默默跳过;仅非严格路径的持久化失败才只告警。
|
|
22
|
+
- 旧手动文档审计记录缺少 `uncertain` 字段时,不再信任其已比较进度:只读状态将活跃事实列为待审,后续按现有批次上限重审一次;新格式的空未决集合保留有效进度,避免重复调用模型(#33)。
|
|
23
|
+
- EntityPage 再生成写回校验页面修订号,拒绝覆盖模型调用期间的用户编辑、事实 dirty 标记或更新的生成结果;迟到的生成失败不会重新污染已成功的新页。SQLite/PostgreSQL schema 2 自动补充修订列,SQLite 并发首次迁移使用短写事务;原有 summary_version 含义及不带条件的旧页接口调用保持兼容。
|
|
24
|
+
- Windows 宿主文件扫描忽略带根或驱动器的 allowlist glob,避免 rooted pattern 抛错;portable source 测试正确隔离 Windows 用户目录。
|
|
25
|
+
- **Hermes 适配器不再丢弃 `llm` / `extraction` 配置**:`_bridge_config()` 现在按桥解析器的同一语义把两个配置块转发进 `MemoryRuntimeConfig`,`$HERMES_HOME/octopmemory.json` 里的模型端点与抽取开关能真正抵达运行时;非对象值按缺省处理,坏配置不会挡住启动,`stats` 输出依旧不回显 `api_key`。此前 Hermes 宿主永远落到 `NoopLLMClient`,模型辅助抽取静默不可用(无 candidate/atom,也不报错)(#9)。
|
|
26
|
+
- 补齐 `MemoryService.review_new_memory(max_atoms=20)` 公共入口,修复宿主保存后和定时维护静默跳过手动文档审核的问题;保存仍不等待模型。新增真实 octop-harness 中间件与 SQLite/PostgreSQL 的跨包测试,并纳入 CI 和发布检查(TencentCloud/Octop#2358)。
|
|
27
|
+
- 手动文档审计中,无结论(`uncertain`)的比较仍推进游标,但不再被报告为 `complete`:未验证的 atom 按断言哈希记录,后续无待比对项的巡检仍返回 `uncertain`;新文档 revision 重新比对后可恢复 `complete`(TencentCloud/octop-memory#33)。
|
|
28
|
+
- 手动文档审计的未决集合改按当前活跃 atom 计算:已停用、已删除或断言已变的记录不再滞留,`remaining` 与状态读取同样只统计活跃 atom,因此停用一个 atom 后无需修改文档即可清除 `uncertain`,SQLite/PostgreSQL 同组回归(TencentCloud/octop-memory#33)。
|
|
29
|
+
|
|
30
|
+
### 变更
|
|
31
|
+
|
|
32
|
+
- **修正 Hermes 安装文档**:`docs/integrations.md` 与 provider README 收敛为一条可用路径——用 `hermes plugins install TencentCloud/octop-memory/plugins/hermes/octopmemory --ref <完整 40 位 SHA>` 从本仓子目录直接安装,无需独立插件仓库;并补充用 `hermes --print-runtime-command` 获取网关实际解释器。同时写明仓库未向 PyPI 发布独立的 `octop-memory-hermes` 插件包(按旧命令执行会 404),`installer.py` 仅为仓库内 E2E 工具(#10)。
|
|
33
|
+
|
|
34
|
+
## [1.0.2] - 2026-10-16
|
|
35
|
+
|
|
36
|
+
### 新增
|
|
37
|
+
|
|
38
|
+
- 手动 USER.md/MEMORY.md 与普通记忆核对:手动文档优先,明确冲突将旧 Atom 软停用、替代事实转候选并保留来源审计;重复仅在匹配的会话上下文抑制召回。`MemoryService` / Bridge 共用对账、状态接口;宿主可注册文档读取器在保存/晋升后检查。语义判断须引用原文,不确定、模型失败、过期文档和未完成批次显式报告。SQLite/PostgreSQL 同组验证,不增加 schema。
|
|
39
|
+
|
|
40
|
+
### 修复
|
|
41
|
+
|
|
42
|
+
- SQLite 每个 backend 复用一条连接,完整 SQL 操作与显式事务串行执行,避免多 agent 与常驻 worker 的连接数相乘;关闭等待正在进行的操作,独立失败写入回滚后再抛出异常(TencentCloud/Octop#2060)。
|
|
43
|
+
- PostgreSQL 按进程与连接配置共享有界池:业务最多 8 条,checkpoint/维护最多 4 条;操作归还连接、显式事务持有同一连接、最后引用关闭才销毁池。checkpoint 初始化串行复用,失败立即释放租约;修复 69 个活跃 agent 超出服务端连接上限的问题(TencentCloud/Octop#2060)。
|
|
44
|
+
- PostgreSQL 容量、排队超限、空闲回收、断连恢复、初始化失败及引用关闭加入真实服务回归;CI 与 release 测试均启动专用 PostgreSQL,显式配置测试 DSN 不可用时失败而非跳过。
|
|
45
|
+
- 系统运行报错仅按结构化来源标记隔离,不再自动采集、提炼或兜底召回。移除记忆意图、排障价值关键词及短消息意图例外,Agent 自行调用 memory_save;手工保存、人工批准按来源保护。存量预览/应用仅停用全部证据均带错误标记的自动记录,旧版报错文本、缺失或混合来源仅列入审核清单并保持原状态,保留原始证据与审计,SQLite/PostgreSQL 行为一致。
|
|
46
|
+
|
|
47
|
+
## [1.0.1] - 2026-10-09
|
|
48
|
+
|
|
49
|
+
### 修复
|
|
50
|
+
|
|
51
|
+
- 线程 ident 复用时关闭被丢弃的 SQLite 连接,短命线程不再累积 fd 并最终进入不可恢复的 disk I/O error(TencentCloud/Octop#1339)。
|
|
52
|
+
- PostgreSQL 空闲连接不再长期占用:连接建立时申请 `idle_session_timeout`(PostgreSQL 14+,旧版本自动降级);本地按同一阈值主动关闭并重拨,不必等下一条语句。checkpointer 连接池 `min_size` 改为 0,空闲超过 `max_idle` 后关闭。常驻 agent 不再永久持有 1–2 个连接(TencentCloud/Octop#1795)。小时 checkpoint 裁剪在打开连接池之前会拒绝已空闲的 Postgres backend。
|
|
53
|
+
- checkpointer 连接池在取出连接时做存活性探测,丢弃服务器已关闭的连接并重建(TencentCloud/Octop#1172)。
|
|
54
|
+
- 提炼补全默认带 `max_tokens` 预算(2048);调用方传入 `None` 视为未设置并回落到该默认值,避免推理模型占满上下文并超过读取超时(TencentCloud/Octop#1360)。
|
|
55
|
+
- 提高删除后与空闲维护的 SQLite 增量 vacuum 页数,避免 300 页的小时预算在大批删除后追不上。compact 统计计入 SQLite 主库、WAL 与 shm,Postgres 则报告数据库大小与回收字节。
|
|
56
|
+
|
|
57
|
+
### 变更
|
|
58
|
+
|
|
59
|
+
- 发版时同步检查多语言 README 版本。
|
|
60
|
+
|
|
61
|
+
## [1.0.0] - 2026-09-24
|
|
62
|
+
|
|
63
|
+
### 新增
|
|
64
|
+
|
|
65
|
+
- 首个 1.0.0 正式版本发布到 PyPI。
|
|
66
|
+
|
|
67
|
+
### 变更
|
|
68
|
+
|
|
69
|
+
- 对齐 Octop:引入 `develop` 集成分支策略;禁止直推 `main`/`develop`;发版后由 `sync-main-to-develop.yml` 同步;新增 `/publish` skill(发版同步 CHANGELOG / README)。
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
### Changed
|
|
74
|
+
|
|
75
|
+
- Rename the project and distribution to `octop-memory`, the Python package to `octop_memory`, and host plugin IDs to `octopmemory`.
|
|
76
|
+
- Rename CLI entry points, environment variables, default paths, and the PostgreSQL shared schema. Existing installations require explicit migration; see [the migration guide](docs/integrations.md#更名与已有安装迁移).
|
|
77
|
+
- Update host adapters, build metadata, examples, documentation, and the README banner. SQLite checkpoint and portable package formats remain unchanged.
|
|
78
|
+
- 最低 Python 版本提升到 3.12,与 Octop 基线对齐;核心、Hermes 包声明、开发环境与 CI 同步调整,Python 3.11 不再受支持。
|
|
79
|
+
|
|
80
|
+
### Documentation
|
|
81
|
+
|
|
82
|
+
- README banner 改用仓库相对路径,补充代码目录与记忆数据流;明确 Candidate 可自动处理、EntityPage 按触发再生成、Episode 为独立提炼流程。
|
|
83
|
+
- 清理个人工具配置、重复发布 skill 和私人数据库诊断脚本;合并基础/树示例为公共 API 临时库演示,保留合成 recall eval 并明确指标与覆盖限制。
|
|
84
|
+
- 合并 OpenClaw/Hermes 安装、配置和排错到 `docs/integrations.md`;贡献入口集中到 CONTRIBUTING,AI 规则集中到 AGENTS;保留精简、脱敏的 `docs/agent/` Harness 澄清、决策与交接流程。
|
|
85
|
+
|
|
86
|
+
### Added
|
|
87
|
+
|
|
88
|
+
- 新增宿主协调的 SQLite/WAL 在线 checkpoint 瘦身:一致备份、并发安全的批次去重和显式空间回收结果,不删历史或共享正文。`scripts/memory-slim --online AGENT` 调用运行中的新版 Octop 显示维护提示并协调暂停/恢复,不能用于旧 reader。
|
|
89
|
+
|
|
90
|
+
- 新增 `db slim FILE` 简单瘦身入口:默认只读预览;`--apply --offline` 自动备份、复用 checkpoint 重复字段并回收文件空间,不删除历史。提供本地源码启动器 `scripts/memory-slim`。
|
|
91
|
+
|
|
92
|
+
- SQLite checkpoint 默认复用重复的 `skills_metadata` / `workspace_file_contents`(工作区文件内容;底层字段仍为 DeepAgents 的 `memory_contents`)内容版本,兼容读取旧 inline 快照;`OCTOP_MEMORY_CHECKPOINT_DEDUP=0` 可关闭新增引用写入。新增 `db checkpoints` 只读预览、离线批量迁移、保守历史裁剪、压缩及 `--expand` 格式回退。新格式须使用兼容读端,不能直接回退旧二进制;详见 [Checkpoint 维护](CONTRIBUTING.md#checkpoint-维护)。
|
|
93
|
+
|
|
94
|
+
### Fixed
|
|
95
|
+
|
|
96
|
+
- SQLite checkpoint 解码器支持为独立只读连接创建专用实例与缓存,供宿主安全回填历史;离线裁剪逐条释放正文,避免内存按重复正文总量增长。补充 SQLite/真实 PostgreSQL 重开后审批恢复且不重复已完成步骤的对照测试。
|
|
97
|
+
|
|
98
|
+
- **Episode 时间统一为 UTC**:LLM 返回不带时区的 `occurred_at` 时不再把 naive `datetime` 写入存储;SQLite/PostgreSQL 写入和查询边界统一规范化为 UTC,SQLite 读取历史 naive Episode 时也会兼容转换。Dashboard 对 Episode 的两个排序入口增加 UTC 防御,避免混合 naive/aware 历史数据触发 `TypeError: can't compare offset-naive and offset-aware datetimes` 并让情绪日记页面显示为空。
|
|
99
|
+
|
|
100
|
+
## [0.9.9] - 2026-09-04
|
|
101
|
+
|
|
102
|
+
### 修复
|
|
103
|
+
|
|
104
|
+
- **PostgreSQL 读事务泄漏**:长驻 dashboard 连接会停在 `idle in transaction` 并持有 `AccessShareLock`,导致另一个实例初始化时在 FTS `DROP INDEX` 上无限等待。`PostgresMemoryBackend._cursor()` 现在在非显式事务、非 schema bootstrap 的情况下,为每次公开操作建立并结束一个短事务,读操作返回后连接恢复 `IDLE`;显式的 `backend.transaction()` 仍然可以跨多个操作保持原子性。
|
|
105
|
+
- **启动 DDL 卡锁**:schema bootstrap 完成 `SET search_path` 后显式提交,不再由 session 设置遗留隐式事务;DDL 设置 `lock_timeout=5s`,遇到异常长锁等待时快速报错;FTS 索引已是目标形态时先查 `pg_indexes` 并完全跳过扩展检查与 DDL。
|
|
106
|
+
- **Dashboard 采纳 `conflict` / `needs_review` 候选不再报错**:`promote_candidate` 只允许 `pending`,所以记忆沉淀「采纳」一条 `conflict` 记录会抛错,重跑 5-check worker 也只会再次把它停在 `conflict`。用户批准后现在强制写入 atom(SQLite 与 Postgres 共用这条路径);已存在的矛盾 atom 被 supersede,召回只保留一侧。
|
|
107
|
+
|
|
108
|
+
### 变更
|
|
109
|
+
|
|
110
|
+
- 人工采纳路径达到发布门槛:修复 `PromotionWorker._approve_one()` 的 mypy 控制流类型错误——为分支间共用的 `entity_id` 显式声明 `str | None`,由 return/赋值分支收窄为 `str`,不使用 `cast` / `type: ignore` 掩盖。语义不变:exact duplicate 执行 merge,contradictory atom 被 supersede,candidate/journal 的决策来源记为 `user`。
|
|
111
|
+
- 补回 `chore: exclude node_modules from the published sdist`:hatchling 收集 sdist 时只认仓库根目录的 `.gitignore`,缺少 `node_modules/` 规则会把本地 `plugins/openclaw/octopmemory/node_modules`(约 373MB / 1.7 万文件)打进发布产物。
|
|
112
|
+
- 把此前滞留在 `## [Unreleased]`、实际已随 `0.9.8` 发布的条目归档到下方 `## [0.9.8]`,`## [Unreleased]` 恢复为空。
|
|
113
|
+
|
|
114
|
+
## [0.9.8] - 2026-09-02
|
|
115
|
+
|
|
116
|
+
### Added
|
|
117
|
+
|
|
118
|
+
- **Manual atom writes**: `Memory.create_atom()` creates a canonical atom (and optionally its entity) through the same RawEvent → Candidate → AtomCard → entity-branch leaf path as promotion. `Memory.replace_atom()` creates an append-only successor without fabricating a new RawEvent/Candidate, records the before/after correction in `user_edit`, and atomically supersedes only an active predecessor (ADR-010/ADR-034). Dashboard RPCs: `create_atom`, `replace_atom`.
|
|
119
|
+
|
|
120
|
+
- **Idle DB maintenance**: `run_idle_maintenance()` runs prune → GC → `nudge_vacuum` in one fail-soft pass for host idle timers. New SQLite files open with `auto_vacuum=INCREMENTAL` so nudge can reclaim without a prior compact.
|
|
121
|
+
- **Legacy SQLite bootstrap**: `maybe_bootstrap_incremental()` runs one idle/startup `compact_vacuum` to enable `INCREMENTAL` on existing NONE databases (≤200MB on short idle; no size cap on quiet startup / long idle). Skips with `insufficient_disk` when free space is below file+WAL + 64MB (retryable).
|
|
122
|
+
- **Idle WAL truncate**: `maybe_truncate_wal()` runs `wal_checkpoint(TRUNCATE)` when `-wal` is at least 2MB, only from a confirmed idle window.
|
|
123
|
+
|
|
124
|
+
### Changed
|
|
125
|
+
|
|
126
|
+
- **Checkpoint retention (ADR-029)**: default `keep_last` is **1** (latest **sealed** parent snapshot per thread). Before deleting ancestors, `prune_checkpoints` inlines delta-omitted `messages` onto a new root parent. If replay fails, that thread's parent ancestors are skipped. `drop_subgraph_streams=True` still deletes finished `tools:*` / subgraph streams after the parent is sealed. CLI unchanged.
|
|
127
|
+
- **Startup slim is cheaper and visible**: orphan-raw GC selects ids only (no full-row hydrate). Hosts can skip that pass via `run_idle_maintenance(include_orphan_raw=False)`. SQLite connections set `busy_timeout=30s`.
|
|
128
|
+
- **Journal retention (ADR-028)**: `run_gc` expires `extract_run` / `gc_*` / `page_regen*` / `consolidate` rows older than 14 days. Decision rows (promote/reject/…) are kept. Cleanup does not write journal. Extract passes overwrite `last_extract_run` in meta instead of appending journal; `stats_counts` exposes that summary.
|
|
129
|
+
- **`recall_for_prompt` auto-inject is stricter about raw**: default `raw_policy=fallback` keeps raw transcript only when no atom / page / episode candidate exists (no topping up to `limit`). Raw whose `session_id` or `thread_id` intersects the current session scope (`session_id` falling back to `thread_id`) is dropped, including sibling threads in the same session. `memory_search` still passes its configured `raw_policy` through, so `always` can mix raw with atoms. The eval baseline `recall_multi_source` is unchanged.
|
|
130
|
+
- **Postgres test suite is no longer skipped by default**: `psycopg` was not a dev dependency, so every test in `tests/test_postgres.py` skipped silently and the Postgres backend shipped unexercised. It is now in the `dev` group, and `mypy` tolerates it missing via an override rather than a per-import `type: ignore[import-not-found]` — the latter flips to "unused ignore" under `--strict` the moment the package *is* installed. The suite still skips (rather than fails) when no server is reachable.
|
|
131
|
+
- **Postgres checkpointer is no longer shipped unexercised**: `langgraph-checkpoint-postgres` (and its `psycopg_pool`) was missing from the `dev` group, so `_create_postgres_checkpointer` could only reach its `ImportError` branch and return `None`. The existing test monkeypatched the builder, so it proved the caching contract while never building a real pool. The dep is now declared and a suite builds a genuine Postgres-backed `Memory`: no pool before first use, a real `PostgresSaver` after it, and a checkpoint round-tripped through the database (skipping when no server is reachable). Making the real types visible also surfaced one mismatch — a bare `ConnectionPool` yields tuple rows while `PostgresSaver` requires dict rows; `row_factory=dict_row` already made that true at runtime, and the annotation now says so. The three `mypy --strict` errors this exposed on `main` are fixed too.
|
|
132
|
+
- **Idle GC is quieter**: the reason a GC pass is skipped is logged at `debug` instead of `info`, so an hourly idle maintenance timer no longer chats on every skip.
|
|
133
|
+
|
|
134
|
+
### Fixed
|
|
135
|
+
|
|
136
|
+
- **Lifecycle GC no longer corrupts a Postgres session**: the SQLite-only guard duck-typed on `_conn` / `_ns`, which `PostgresMemoryBackend` also exposes, so GC ran SQLite statements (`{ns}_atoms`, `?` placeholders) against Postgres. The resulting `UndefinedTable` aborted the shared transaction and every later write failed with `InFailedSqlTransaction`, silently disabling memory capture and extract for the rest of the process. `run_gc` now refuses on backend type up front, before any statement reaches the connection, and returns empty stats (rather than raising) so an hourly maintenance timer keeps ticking.
|
|
137
|
+
- **`memory export` no longer poisons a PostgreSQL connection**: `_iter_active_entities` duck-typed the same way, so it ran the SQLite statement (`{ns}_thread_active_entities`) against psycopg. The `UndefinedTable` was swallowed by a bare `except`, with no rollback, leaving the connection aborted — so **every later memory write in that process failed with `InFailedSqlTransaction`**. The exporter now dispatches on backend type. `thread_active_entities` is also genuinely exported on Postgres now instead of silently dropped from the dump.
|
|
138
|
+
- **A dropped connection is redialled instead of staying dead**: `_reset_if_aborted` only revives a *live* connection whose transaction is poisoned. A server restart, a network blip or an idle timeout is a different failure — `closed` is 1 and `transaction_status` reports `UNKNOWN`, where `rollback()` is a no-op — and nothing reopened the connection, so memory writes failed with `OperationalError: the connection is closed` until the process restarted. `_cursor()` now reconnects first and re-applies `search_path` (a session setting, not a database one; without it every unqualified table name resolves against `public`). Three exemptions: after an explicit `close()`, inside a `transaction()` block whose earlier writes died with the old connection, and during schema bootstrap. Redial attempts are spaced by a 2s cooldown so a genuinely down server does not cost every call a connect timeout.
|
|
139
|
+
- **A failed statement no longer disables Postgres memory for the whole process**: psycopg refuses *every* command — reads included — on a connection left in `INERROR`, but only `transaction()` and `save_raw_batch` recovered, leaving 27 of 29 write methods and all reads unable to come back. Every data-access method now opens its cursor through a `_cursor()` chokepoint that clears an aborted transaction first. Schema bootstrap and explicit `transaction()` blocks stay exempt: they own their own rollback, and an automatic one would undo half-built DDL or hide a failure the caller must see.
|
|
140
|
+
|
|
141
|
+
Note for PostgreSQL installs: `run_gc` still no-ops and `prune_checkpoints` still refuses (both SQLite-only, D46-C / M6), so retention has to be handled outside octop-memory for now.
|
|
142
|
+
|
|
143
|
+
## [0.9.1] - 2026-07-13
|
|
144
|
+
|
|
145
|
+
### Fixed
|
|
146
|
+
|
|
147
|
+
- **OpenClaw npm plugin**: bump package version to 0.9.1 in sync with Python package.
|
|
148
|
+
|
|
149
|
+
## [0.9.0] - 2026-07-13
|
|
150
|
+
|
|
151
|
+
### Added
|
|
152
|
+
|
|
153
|
+
- **portable adopt/doctor**: auto-resolve openclaw namespace from `~/.openclaw/openclaw.json`
|
|
154
|
+
(`plugins.entries.octopmemory.config.namespace`), so migrated memory lands in the
|
|
155
|
+
namespace the plugin actually opens — no more silent mismatch.
|
|
156
|
+
- **OpenClaw TS plugin**: new `/octopmemory` chat slash command (`status / search / show / reindex`)
|
|
157
|
+
dispatched via `api.registerCommand` (same surface as memory-core's `/dreaming`).
|
|
158
|
+
- **OpenClaw TS plugin**: `sdk-shim.ts` extended with `ChatCommandContext`, `ChatCommandReply`,
|
|
159
|
+
`RegisterChatCommandOptions` interfaces; `registerCommand?` added to `OpenClawPluginApi`
|
|
160
|
+
(feature-tested at runtime for older hosts).
|
|
161
|
+
|
|
162
|
+
### Fixed
|
|
163
|
+
|
|
164
|
+
- **OpenClaw setup**: always write `hooks.allowConversationAccess: true` into the plugin entry.
|
|
165
|
+
OpenClaw ≥2026.4.29 gates `agent_end` / `llm_input` / `llm_output` hooks behind this explicit
|
|
166
|
+
opt-in; without it, auto-capture silently stores nothing while doctor/status look healthy.
|
|
167
|
+
- **OpenClaw setup**: always write `namespace` explicitly (`openclaw__default`) so the plugin
|
|
168
|
+
never derives a divergent name at runtime.
|
|
169
|
+
- **OpenClaw doctor**: check `hooks.allowConversationAccess` and exit 1 with a clear remediation
|
|
170
|
+
hint when the field is absent.
|
|
171
|
+
- **OpenClaw doctor**: also search npm-managed plugin path
|
|
172
|
+
(`~/.openclaw/npm/projects/*/node_modules/@octop-memory/openclaw`) so `openclaw plugins install`
|
|
173
|
+
layout is accepted.
|
|
174
|
+
- **OpenClaw TS plugin**: fix npm package name (`@octopmemory/openclaw-plugin` →
|
|
175
|
+
`@octop-memory/openclaw`).
|
|
176
|
+
- **OpenClaw TS plugin**: remove invalid `kind: runtime-slash` from `commandAliases` entry
|
|
177
|
+
(caused plugin load warning on newer hosts).
|
|
178
|
+
|
|
179
|
+
## [0.2.0] - 2026-06-18
|
|
180
|
+
|
|
181
|
+
### Added
|
|
182
|
+
|
|
183
|
+
#### L0–L4 Memory Pipeline
|
|
184
|
+
- **L0 Raw Events** — `RawEvent` dataclass + SQLite table with FTS5 index. Immutable, append-only source of truth for all higher layers.
|
|
185
|
+
- **Async writer** (`io/`) — background thread with batch commit (50 events / 200 ms), 3-retry exponential backoff, dead-letter table, WAL-mode isolation.
|
|
186
|
+
- **L1 Candidates** — `CandidateExtractor` (prompt v2.1, anti-dilution rules, JSON parser with referential-integrity validation). `extract_session()` glue function.
|
|
187
|
+
- **L1→L2 Promotion worker** — 5-check pipeline (value → evidence → entity → duplicate → conflict). Pure-rule path + optional LLM escalation hook for grey-zone disambiguation. 7-day fallback rules. `PromotionResult` telemetry.
|
|
188
|
+
- **L2 AtomCard** — append-only structured facts with `superseded_by` deprecation chain. FTS5 index over `assertion + verbatim_quote + search_terms`.
|
|
189
|
+
- **L3 Entity + Alias** — entity anchor for atoms; alias table for name normalization and co-reference resolution.
|
|
190
|
+
- **L3 EntityPage** — long-form markdown summary per entity; `dirty` flag + async cron regen; `headline` hot field; `## My Notes` section preserved verbatim on regen.
|
|
191
|
+
- **L4 Journal** — append-only audit log of every promote / merge / conflict / deprecate / gc action.
|
|
192
|
+
|
|
193
|
+
#### Recall Pipeline (M4)
|
|
194
|
+
- **`recall_for_prompt_v2`** — 8-stage pipeline: query parser → router → multi-source gather → rerank (5-factor BM25+importance+confidence+recency+layer\_prior) → diversify → suppress → token budget → cache.
|
|
195
|
+
- **Active-entity LRU stack** — per-thread co-reference resolution ("那个项目") via `ActiveEntity` table and `thread_state` helpers.
|
|
196
|
+
- **Source layers**: `atom` (primary), `page_headline`, `tree` (MemoryNode), `raw` (fallback). Router selects based on query shape; time-bounded queries exclude tree.
|
|
197
|
+
- **`recall_for_prompt`** — simpler M2.9 baseline (atom + raw, no rerank).
|
|
198
|
+
|
|
199
|
+
#### MemoryNode Tree ↔ Pipeline Bridge
|
|
200
|
+
- **Write-side**: `PromotionWorker._sync_atom_to_tree()` — on every successful promote, auto-mirrors the AtomCard as a MemoryNode leaf under an entity branch node. Nodes tagged `metadata["mirror"]="auto"` to distinguish from hand-authored entries. Best-effort (tree failure does not abort promotion).
|
|
201
|
+
- **Read-side**: `"tree"` added as a recall source in `gather_candidates()` and `recall_for_prompt_v2`. Layer prior = 0.70 (between atom and raw). Token budget bucket = 30% of total.
|
|
202
|
+
|
|
203
|
+
#### Host Integrations
|
|
204
|
+
- **OpenClaw plugin** (`plugins/openclaw/octopmemory/`) — TypeScript shell spawning the Python bridge; registers `registerMemoryCapability` (D3 path); `setup / doctor / uninstall / print-config` CLI subcommands.
|
|
205
|
+
- **Hermes adapter** (`plugins/hermes/octopmemory/`) — Python `MemoryProvider` adapter; `install / doctor` CLI subcommands; runtime policy config.
|
|
206
|
+
- **Python bridge** (`bridge/`) — JSON-RPC over stdio server; `host_files` 30-second poll watcher; path projection for cross-OS environments.
|
|
207
|
+
|
|
208
|
+
#### Migration & Lifecycle (M5)
|
|
209
|
+
- **Export / Import** — streaming JSONL dump with optional gzip; full namespace round-trip (raw\_events → candidates → atoms → entities → aliases → entity\_pages → journal → thread\_active\_entities).
|
|
210
|
+
- **Rename / Preview** — safe namespace rename with dry-run preview.
|
|
211
|
+
- **Backfill** — rebuild L1–L4 from L0 raw events for schema migrations.
|
|
212
|
+
- **GC** — `lifecycle/gc.py`: prune rejected candidates, deprecated atoms, orphan raw events. Configurable age thresholds.
|
|
213
|
+
|
|
214
|
+
#### CLI Commands
|
|
215
|
+
New command groups: `raw`, `candidate`, `atom`, `entity`, `journal`, `page`, `recall`, `thread`, `export`, `import`, `migrate`, `backfill`, `gc`, `openclaw`, `hermes`.
|
|
216
|
+
|
|
217
|
+
#### Dev / Testing
|
|
218
|
+
- `pytest-asyncio>=0.23` added to dev extras; `asyncio_mode = "auto"` configured — all 6 async checkpointer tests now pass.
|
|
219
|
+
- 763 tests total (13 skipped for missing PostgreSQL environment).
|
|
220
|
+
|
|
221
|
+
### Changed
|
|
222
|
+
- **BREAKING**: `save_conversation` is now an upsert keyed on `thread_id`. Subsequent calls for the same `thread_id` append messages rather than replacing the record. Existing databases need to be recreated.
|
|
223
|
+
- `ConversationRecord` and `ConversationSummary` gained a `title` field; `ConversationSummary` exposes `ended_at` and `message_count`.
|
|
224
|
+
- `MemoryNode.metadata` is now a free-form dict persisted as JSON (not indexed by FTS); upper layers use it to store `entity_id`, `atom_id`, `mirror` references.
|
|
225
|
+
- Router default sources changed from `("atom", "raw")` to `("atom", "tree", "raw")` for non-time-bounded queries.
|
|
226
|
+
|
|
227
|
+
### Fixed
|
|
228
|
+
- `migration/export.py` — mypy strict `[assignment]` error caused by reusing the `row` loop variable across branches of different types; renamed each branch variable to a type-specific name.
|
|
229
|
+
- `recall/multi_source.py` — `_gather_atoms`, `_per_token_atom_search`, `_per_token_raw_search`, `_per_token_tree_search` now have fully-typed return annotations (`list[AtomCard]`, `list[RawEvent]`, `list[MemoryNode]`).
|
|
230
|
+
|
|
231
|
+
## [0.1.1] - 2026-05-24
|
|
232
|
+
|
|
233
|
+
### Added
|
|
234
|
+
- `Memory` class — unified interface for memory storage and recall.
|
|
235
|
+
- `MemoryBackend` protocol — pluggable backend abstraction.
|
|
236
|
+
- `SqliteMemoryBackend` — default backend with FTS5 full-text search.
|
|
237
|
+
- Data types: `MemoryNode`, `ConversationRecord`, `Message`, `SearchResult`, `ConversationSummary`.
|
|
238
|
+
- Memory tree: hierarchical root → branch → leaf structure.
|
|
239
|
+
- Namespace isolation: multiple agents share one database safely.
|
|
240
|
+
- Backend factory: resolve `"sqlite"` / `"postgres"` / `"qdrant"` strings to implementations.
|
|
241
|
+
|
|
242
|
+
[Unreleased]: https://github.com/TencentCloud/octop-memory/compare/v0.2.0...HEAD
|
|
243
|
+
[0.2.0]: https://github.com/TencentCloud/octop-memory/compare/v0.1.3...v0.2.0
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# 开发指南
|
|
2
|
+
|
|
3
|
+
从 [README](README_CN.md) 了解用途,从本文了解实现和贡献流程。AI 工作规则只维护在
|
|
4
|
+
[AGENTS.md](AGENTS.md);外部 Agent 的接入方式、已有适配的安装配置和宿主契约统一见[集成指南](docs/integrations.md)。
|
|
5
|
+
|
|
6
|
+
## 开始开发
|
|
7
|
+
|
|
8
|
+
要求 Python 3.12+、支持 FTS5 的 SQLite 和 uv。
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
git clone https://github.com/TencentCloud/octop-memory.git
|
|
12
|
+
cd octop-memory
|
|
13
|
+
make install
|
|
14
|
+
make install-hooks
|
|
15
|
+
make all
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
从 `develop` 创建 `feature/*` 或 `fix/*`,用合成数据复现问题,再添加实现和相关行为测试。
|
|
19
|
+
`make all` 包括 format、lint、strict mypy、pytest;format 会改写文件。pre-commit 执行相同门禁。
|
|
20
|
+
|
|
21
|
+
源码辅助目录各有用途:`examples/basic_usage.py` 是唯一的基础示例,使用临时数据库演示公共 API、
|
|
22
|
+
组织树和 prompt recall;`evals/recall/` 是合成数据回归工具,指标局限见测试矩阵。
|
|
23
|
+
`scripts/` 保留插件构建、部署和宿主验收入口;部署/E2E 脚本需专用环境,不属于普通单测。
|
|
24
|
+
个人工具设置留在被忽略的 `.claude/`、`.codebuddy/`、`.cursor/` 中;共享的发版流程除外(已纳入版本库的 `.cursor/skills/publish` / `.codebuddy/skills/publish`)。项目规则只维护在 AGENTS.md。
|
|
25
|
+
|
|
26
|
+
## Harness 维护流程
|
|
27
|
+
|
|
28
|
+
代码相关 bug / 新需求先写明问题、范围和验收,再实现、验证、同步项目认知。已有 Issue / PR 可作为澄清正文,
|
|
29
|
+
在 [HANDOFF](docs/agent/HANDOFF.md) 留链接和当前状态即可;尚未开 Issue 的任务直接使用其中的简短模板。
|
|
30
|
+
规则集中在 [AGENTS.md](AGENTS.md),人工开发者也沿用同一闭环。
|
|
31
|
+
banner、排版、链接、Python/依赖版本、构建/CI 等常规维护只更新对应文件与必要的用户说明,不写 Harness 记录。
|
|
32
|
+
若同时改变运行行为或数据契约,只记录代码影响。
|
|
33
|
+
|
|
34
|
+
| 文档 | 单一职责 |
|
|
35
|
+
|---|---|
|
|
36
|
+
| [HANDOFF](docs/agent/HANDOFF.md) | 当前任务的澄清、进度、验证、遗留问题和下一步 |
|
|
37
|
+
| [PROJECT_MAP](docs/agent/PROJECT_MAP.md) | 模块入口、调用链、数据流与边界 |
|
|
38
|
+
| [DECISIONS](docs/agent/DECISIONS.md) | 架构选择、理由、代价和替代关系 |
|
|
39
|
+
| [TEST_MATRIX](docs/agent/TEST_MATRIX.md) | 按改动范围选择验证命令和环境 |
|
|
40
|
+
| [KNOWN_RISKS](docs/agent/KNOWN_RISKS.md) | 当前缺口、限制与应对 |
|
|
41
|
+
| [GLOSSARY](docs/agent/GLOSSARY.md) | 核心术语 |
|
|
42
|
+
| [README_AUDIT](docs/agent/README_AUDIT.md) | 对外声明与实现的核对项 |
|
|
43
|
+
|
|
44
|
+
仅更新受影响的文档,不为每个任务新建文件;已完成任务的细节由 Issue / PR / Git 保存。
|
|
45
|
+
开发从 [项目地图](docs/agent/PROJECT_MAP.md) 开始,验证命令见 [测试矩阵](docs/agent/TEST_MATRIX.md),
|
|
46
|
+
已知限制见 [风险清单](docs/agent/KNOWN_RISKS.md)。
|
|
47
|
+
|
|
48
|
+
## Checkpoint 维护
|
|
49
|
+
|
|
50
|
+
SQLite `CompactSqliteSaver` 默认复用较大的 `skills_metadata` 和 `memory_contents`,在同库
|
|
51
|
+
`hm_checkpoint_blobs` 保存不可变内容,`harness-checkpoint-v1` checkpoint 保存引用。
|
|
52
|
+
内容和 checkpoint 原子提交,读取时恢复原值;旧 inline 仍可读,历史不会自动批量迁移。
|
|
53
|
+
独立 reader 使用 `CheckpointSerializer.with_connection(conn)` 获取自身 decoder/cache 和一致事务视图。
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# 默认只读预览。
|
|
57
|
+
octop-memory db slim /path/to/memory.sqlite
|
|
58
|
+
# 停止所有数据库使用者后:自动备份、去重、VACUUM,不删历史。
|
|
59
|
+
octop-memory db slim /path/to/memory.sqlite --apply --offline
|
|
60
|
+
# 降级 reader 前,显式展开旧格式;备份路径必须不存在。
|
|
61
|
+
octop-memory --db /path/to/memory.sqlite db checkpoints \
|
|
62
|
+
--apply --offline --backup /path/to/new-backup.sqlite --expand
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`--offline` 是操作者声明,不会停止进程。备份包含已提交 WAL,并需要额外磁盘空间。
|
|
66
|
+
`OCTOP_MEMORY_CHECKPOINT_DEDUP=0` 仅停止新引用写入,不展开存量;旧 reader 无法直接读取新格式。
|
|
67
|
+
迁移分批提交,重跑跳过已转换行;retention 需显式 completed thread、外部引用和依赖闭包。
|
|
68
|
+
在线 `slim_live_checkpoints` 由宿主负责暂停新 invocation、协调 reader 和恢复;长 reader 可能延期 WAL 回收。
|
|
69
|
+
这些格式维护仅支持 SQLite,明确拒绝 PostgreSQL;PG 使用原 saver,checkpoint_ns 不等于 memory namespace。
|
|
70
|
+
|
|
71
|
+
## PR 与发布
|
|
72
|
+
|
|
73
|
+
PR 描述说明问题、改动、验证和剩余限制;用户可见变更更新 `CHANGELOG.md` 的 Unreleased。
|
|
74
|
+
代码相关的非平凡改动更新现有 HANDOFF,并按影响同步地图、决策、测试、风险、术语和 README 核对项;不追加日期流水账。
|
|
75
|
+
|
|
76
|
+
### 分支策略
|
|
77
|
+
|
|
78
|
+
| 分支 | 角色 |
|
|
79
|
+
|------|------|
|
|
80
|
+
| `main` | 生产真源;GitHub 默认分支;仅合入 release / hotfix |
|
|
81
|
+
| `develop` | 日常集成;**特性 PR 请打向 `develop`** |
|
|
82
|
+
| `release/x.y.z` | 临时发版分支;发版完成后删除 |
|
|
83
|
+
| `hotfix/*` | 从 `main` 紧急修复;合入 `main` 后再合回 `develop` |
|
|
84
|
+
|
|
85
|
+
```
|
|
86
|
+
feature/* ──PR──► develop ──► release/x.y.z ──PR──► main ──tag v*──► publish
|
|
87
|
+
hotfix/* ──PR──► main (+ tag) and ──PR──► develop
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
**规则:**
|
|
91
|
+
|
|
92
|
+
- 禁止 `develop` 直推/直 merge 到 `main`;禁止直接 push 到 `main` / `develop`(GitHub 分支保护)。
|
|
93
|
+
- `release/x.y.z` → `main` 必须用 **merge commit**,不要 squash。
|
|
94
|
+
- 生产 `v*` tag 仅在合入 `main` 之后由 Actions 打在 main tip。
|
|
95
|
+
- 发版后由 `sync-main-to-develop.yml` 保持 `main` 为 `develop` 的祖先。
|
|
96
|
+
|
|
97
|
+
从 `develop` 创建 `feature/*` 或 `fix/*`,PR base 选 `develop`。发布从 `release/x.y.z`(或 `hotfix/*`)通过 PR 合入 main,
|
|
98
|
+
project version、CHANGELOG 与标签一致。现有 workflow 在合并后创建 `v*` tag 并触发 PyPI/GitHub Release,再 sync 回 develop;
|
|
99
|
+
没有发布授权时只验证构建,不推 tag 或上传。
|
|
100
|
+
公开发布统一走上述 PR 与 Actions 流程,不在本地用 `make publish` / `twine upload` 代替;
|
|
101
|
+
发布前检查版本未占用、Unreleased 归档正确和门禁结果,发布后核对 tag 与产物,再按仓库策略清理发布分支。
|
|
102
|
+
|
|
103
|
+
Agent 辅助发布:`.cursor/skills/publish` / `.codebuddy/skills/publish`(`/publish <version>`),发版时同步更新 CHANGELOG / README 等。
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
uv build --out-dir dist/package-review
|
|
107
|
+
uv build --wheel --out-dir dist/package-review/direct
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
首条从 sdist 重建 wheel;比较两种 wheel 解压后的文件名与内容。Python sdist 使用 allowlist,
|
|
112
|
+
独立插件另行构建,测试/CI 留在完整 checkout。插件短 README 是分发入口,详细说明只有集成指南一份。
|
|
113
|
+
|
|
114
|
+
不要提交 `.env`、数据库/WAL、备份、日志、`.hmpkg`、依赖安装目录或私人运维记录。
|
|
115
|
+
个人 editor 配置与访问真实库的诊断脚本不属于公共源码;共享 `/publish` skill 属于公共发版流程。
|
|
116
|
+
ignore 不删除已跟踪内容,工作树脱敏也不清理 Git 历史或已有附件。漏洞报告见 [SECURITY.md](SECURITY.md)。
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 orcakit
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|