colink-memory 1.0.3.post1__py3-none-any.whl

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.
Files changed (114) hide show
  1. colink_memory-1.0.3.post1.dist-info/METADATA +272 -0
  2. colink_memory-1.0.3.post1.dist-info/RECORD +114 -0
  3. colink_memory-1.0.3.post1.dist-info/WHEEL +4 -0
  4. colink_memory-1.0.3.post1.dist-info/entry_points.txt +3 -0
  5. colink_memory-1.0.3.post1.dist-info/licenses/LICENSE +21 -0
  6. octop_memory/__init__.py +56 -0
  7. octop_memory/_config_io.py +98 -0
  8. octop_memory/adapters/__init__.py +1 -0
  9. octop_memory/adapters/bridge/__init__.py +37 -0
  10. octop_memory/adapters/bridge/handlers.py +127 -0
  11. octop_memory/adapters/bridge/server.py +343 -0
  12. octop_memory/adapters/cli/__init__.py +130 -0
  13. octop_memory/adapters/cli/atom_cmd.py +143 -0
  14. octop_memory/adapters/cli/candidate_cmd.py +795 -0
  15. octop_memory/adapters/cli/checkpoint_cmd.py +81 -0
  16. octop_memory/adapters/cli/config.py +155 -0
  17. octop_memory/adapters/cli/consolidate_cmd.py +123 -0
  18. octop_memory/adapters/cli/db_cmd.py +268 -0
  19. octop_memory/adapters/cli/entity_cmd.py +121 -0
  20. octop_memory/adapters/cli/episode_cmd.py +239 -0
  21. octop_memory/adapters/cli/gc_cmd.py +97 -0
  22. octop_memory/adapters/cli/journal_cmd.py +114 -0
  23. octop_memory/adapters/cli/memory_cmd.py +290 -0
  24. octop_memory/adapters/cli/migration_cmd.py +330 -0
  25. octop_memory/adapters/cli/openclaw_cmd.py +624 -0
  26. octop_memory/adapters/cli/page_cmd.py +267 -0
  27. octop_memory/adapters/cli/portable_cmd.py +279 -0
  28. octop_memory/adapters/cli/raw_cmd.py +229 -0
  29. octop_memory/adapters/cli/recall_cmd.py +127 -0
  30. octop_memory/adapters/cli/slim_cmd.py +84 -0
  31. octop_memory/adapters/cli/thread_cmd.py +152 -0
  32. octop_memory/application/__init__.py +1 -0
  33. octop_memory/application/checkpoint_maintenance.py +28 -0
  34. octop_memory/application/config.py +76 -0
  35. octop_memory/application/dashboard_data.py +1218 -0
  36. octop_memory/application/host_files.py +512 -0
  37. octop_memory/application/path_projection.py +349 -0
  38. octop_memory/application/runtime.py +1165 -0
  39. octop_memory/core.py +1887 -0
  40. octop_memory/domain/__init__.py +1 -0
  41. octop_memory/domain/alias.py +43 -0
  42. octop_memory/domain/datetime.py +23 -0
  43. octop_memory/domain/retention.py +50 -0
  44. octop_memory/operations/__init__.py +1 -0
  45. octop_memory/operations/migration/__init__.py +45 -0
  46. octop_memory/operations/migration/backfill.py +282 -0
  47. octop_memory/operations/migration/export.py +305 -0
  48. octop_memory/operations/migration/import_.py +384 -0
  49. octop_memory/operations/migration/portable/__init__.py +84 -0
  50. octop_memory/operations/migration/portable/adopter.py +469 -0
  51. octop_memory/operations/migration/portable/doctor.py +377 -0
  52. octop_memory/operations/migration/portable/models.py +253 -0
  53. octop_memory/operations/migration/portable/packer.py +264 -0
  54. octop_memory/operations/migration/portable/sources.py +246 -0
  55. octop_memory/operations/migration/preview.py +95 -0
  56. octop_memory/operations/migration/rename.py +420 -0
  57. octop_memory/operations/retention.py +507 -0
  58. octop_memory/pipeline/__init__.py +1 -0
  59. octop_memory/pipeline/episode/__init__.py +375 -0
  60. octop_memory/pipeline/episode/digest.py +496 -0
  61. octop_memory/pipeline/episode/prompts.py +157 -0
  62. octop_memory/pipeline/extractor/__init__.py +365 -0
  63. octop_memory/pipeline/extractor/parser.py +394 -0
  64. octop_memory/pipeline/extractor/prompts.py +471 -0
  65. octop_memory/pipeline/lifecycle/__init__.py +83 -0
  66. octop_memory/pipeline/lifecycle/checkpoint_gc.py +629 -0
  67. octop_memory/pipeline/lifecycle/consolidate.py +368 -0
  68. octop_memory/pipeline/lifecycle/gc.py +368 -0
  69. octop_memory/pipeline/lifecycle/maintenance.py +339 -0
  70. octop_memory/pipeline/lifecycle/vacuum.py +679 -0
  71. octop_memory/pipeline/page/__init__.py +54 -0
  72. octop_memory/pipeline/page/headline.py +58 -0
  73. octop_memory/pipeline/page/prompts.py +110 -0
  74. octop_memory/pipeline/page/regenerator.py +422 -0
  75. octop_memory/pipeline/page/trigger.py +73 -0
  76. octop_memory/pipeline/page/user_notes.py +105 -0
  77. octop_memory/pipeline/promotion/__init__.py +638 -0
  78. octop_memory/pipeline/promotion/checks.py +715 -0
  79. octop_memory/pipeline/promotion/fallback.py +294 -0
  80. octop_memory/pipeline/promotion/llm_hook.py +265 -0
  81. octop_memory/pipeline/recall/__init__.py +584 -0
  82. octop_memory/pipeline/recall/budget.py +164 -0
  83. octop_memory/pipeline/recall/cache.py +100 -0
  84. octop_memory/pipeline/recall/diversify.py +67 -0
  85. octop_memory/pipeline/recall/multi_source.py +489 -0
  86. octop_memory/pipeline/recall/parser.py +273 -0
  87. octop_memory/pipeline/recall/rerank.py +298 -0
  88. octop_memory/pipeline/recall/router.py +118 -0
  89. octop_memory/pipeline/recall/suppress.py +142 -0
  90. octop_memory/pipeline/recall/thread_state.py +148 -0
  91. octop_memory/pipeline/recall/timeout.py +123 -0
  92. octop_memory/ports/__init__.py +1 -0
  93. octop_memory/ports/llm/__init__.py +49 -0
  94. octop_memory/ports/llm/_protocol.py +114 -0
  95. octop_memory/ports/llm/mock.py +115 -0
  96. octop_memory/ports/llm/openai_compat.py +217 -0
  97. octop_memory/service.py +334 -0
  98. octop_memory/storage/__init__.py +1 -0
  99. octop_memory/storage/backends/__init__.py +623 -0
  100. octop_memory/storage/backends/forget.py +279 -0
  101. octop_memory/storage/backends/fts_text.py +91 -0
  102. octop_memory/storage/backends/postgres.py +2477 -0
  103. octop_memory/storage/backends/postgres_pool.py +140 -0
  104. octop_memory/storage/backends/sqlite.py +2491 -0
  105. octop_memory/storage/backends/sqlite_checkpoint.py +219 -0
  106. octop_memory/storage/backends/sqlite_checkpoint_job.py +114 -0
  107. octop_memory/storage/backends/sqlite_checkpoint_live.py +88 -0
  108. octop_memory/storage/backends/sqlite_checkpoint_maintenance.py +267 -0
  109. octop_memory/storage/driver_errors.py +64 -0
  110. octop_memory/storage/vector/__init__.py +104 -0
  111. octop_memory/storage/vector/chroma.py +165 -0
  112. octop_memory/storage/vector/embeddings.py +262 -0
  113. octop_memory/storage/vector/qdrant.py +196 -0
  114. octop_memory/types.py +575 -0
@@ -0,0 +1,272 @@
1
+ Metadata-Version: 2.5
2
+ Name: colink-memory
3
+ Version: 1.0.3.post1
4
+ Summary: Pluggable memory system with hierarchical recall, FTS search, and multiple backend support.
5
+ Project-URL: Homepage, https://github.com/mh567/Colink-memory
6
+ Project-URL: Repository, https://github.com/mh567/Colink-memory
7
+ Project-URL: Issues, https://github.com/mh567/Colink-memory/issues
8
+ Project-URL: Changelog, https://github.com/mh567/Colink-memory/blob/main/CHANGELOG.md
9
+ Author: orcakit
10
+ License: MIT
11
+ License-File: LICENSE
12
+ Keywords: agent,fts,llm,memory,recall,sqlite
13
+ Classifier: Development Status :: 3 - Alpha
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
21
+ Requires-Python: >=3.12
22
+ Provides-Extra: chroma
23
+ Requires-Dist: chromadb>=0.4; extra == 'chroma'
24
+ Provides-Extra: cli
25
+ Requires-Dist: click>=8.0; extra == 'cli'
26
+ Provides-Extra: dashboard
27
+ Requires-Dist: click>=8.0; extra == 'dashboard'
28
+ Requires-Dist: fastapi>=0.110; extra == 'dashboard'
29
+ Requires-Dist: uvicorn[standard]>=0.29; extra == 'dashboard'
30
+ Provides-Extra: embeddings
31
+ Requires-Dist: sentence-transformers>=2.2; extra == 'embeddings'
32
+ Provides-Extra: langgraph
33
+ Requires-Dist: langgraph-checkpoint-sqlite>=2.0; extra == 'langgraph'
34
+ Requires-Dist: langgraph-checkpoint>=2.0; extra == 'langgraph'
35
+ Provides-Extra: langgraph-postgres
36
+ Requires-Dist: langgraph-checkpoint-postgres>=2.0; extra == 'langgraph-postgres'
37
+ Requires-Dist: langgraph-checkpoint>=2.0; extra == 'langgraph-postgres'
38
+ Requires-Dist: psycopg[binary]>=3.1; extra == 'langgraph-postgres'
39
+ Provides-Extra: postgres
40
+ Requires-Dist: psycopg-pool>=3.2; extra == 'postgres'
41
+ Requires-Dist: psycopg[binary]>=3.1; extra == 'postgres'
42
+ Provides-Extra: qdrant
43
+ Requires-Dist: qdrant-client>=1.7; extra == 'qdrant'
44
+ Description-Content-Type: text/markdown
45
+
46
+ <p align="center">
47
+ <img src="assets/images/banner.jpeg" alt="Octop Memory — a little octopus keeping memories safe" width="880" />
48
+ </p>
49
+
50
+ <p align="center">
51
+ <strong>Help your agent remember what matters.</strong><br />
52
+ Keep preferences, carry context across sessions, and bring your memory to the next agent.
53
+ </p>
54
+
55
+ <p align="center">
56
+ <a href="pyproject.toml"><img alt="Python 3.12+" src="https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&amp;logoColor=white" /></a>
57
+ <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-E85D75" /></a>
58
+ <a href="pyproject.toml"><img alt="Core dependencies: 0" src="https://img.shields.io/badge/Core_dependencies-0-E85D75" /></a>
59
+ <a href="#optional-dependencies"><img alt="Storage: SQLite and PostgreSQL" src="https://img.shields.io/badge/Storage-SQLite_%7C_PostgreSQL-4169E1" /></a>
60
+ <a href="CONTRIBUTING.md"><img alt="Code style: Ruff" src="https://img.shields.io/badge/Code_style-Ruff-261230?logo=ruff&amp;logoColor=white" /></a>
61
+ </p>
62
+
63
+ <p align="center">
64
+ <a href="#highlights">Highlights</a> ·
65
+ <a href="#quick-start">Quick start</a> ·
66
+ <a href="#external-agent-adapters">Integrations</a> ·
67
+ <a href="#cli">CLI</a> ·
68
+ <a href="#code-architecture">Architecture</a> ·
69
+ <a href="CONTRIBUTING.md">Contributing</a>
70
+ </p>
71
+
72
+ <p align="center">
73
+ <b>English</b> · <a href="README_CN.md">中文</a>
74
+ </p>
75
+
76
+ ---
77
+
78
+ **Octop Memory** is a persistent, portable memory system for LLM agents. Give a personal assistant lasting preferences,
79
+ keep decisions and project context available across conversations, or move accumulated memory between supported hosts.
80
+ Start locally with SQLite, then add PostgreSQL or model-assisted extraction as needed.
81
+
82
+ It powers memory in the **Octop ecosystem** and also works independently as a Python library, CLI, or JSON-RPC bridge.
83
+ **OpenClaw** and **Hermes** adapters connect their host hooks and tools to the same memory runtime.
84
+ Your host manages agent execution and model scheduling; Octop Memory handles capture, extraction, recall, storage, and migration.
85
+
86
+ > **Memory worth keeping. Context worth bringing along.** Save it, recall it, and carry it between supported agents.
87
+
88
+ <a id="highlights"></a>
89
+
90
+ ## ✨ Highlights
91
+
92
+ | | What stands out | What you get |
93
+ |---|---|---|
94
+ | 🪶 | **Start small, add what you need** | Zero core dependencies: Python's standard library + SQLite/FTS5. Manual storage and lexical recall work without a model. |
95
+ | 🧠 | **Turn conversations into lasting memory** | Model-assisted extraction and promotion turn raw events into facts with evidence references; entity pages and episodes organize the context. |
96
+ | 🔍 | **Recall that fits the prompt** | Full-text search, ranking, deduplication, and token budgets select context for the current query. |
97
+ | 🧳 | **Bring your memory along** | Export/import and portable `.hmpkg` packages move memory between supported hosts, including OpenClaw and Hermes. |
98
+ | 🔌 | **Connect to your agent** | Python `MemoryService`, a JSON-RPC bridge, and dedicated host plugins share the same runtime. |
99
+ | 💾 | **Choose your storage** | SQLite for a local start; PostgreSQL for server deployments. |
100
+ | 🌳 | **Keep facts organized** | Canonical `AtomCard` facts, entity pages, and a `root → branch → leaf` tree make memory easier to navigate; namespaces separate stores within a backend. |
101
+ | 🔖 | **Resume conversations** | Optional LangGraph checkpoints preserve execution state alongside long-term memory, with SQLite and PostgreSQL support. |
102
+
103
+ **Python 3.12+** is required. Automated extraction, promotion checks, and page regeneration use an injected `LLMClient`;
104
+ installing the package alone does not configure a model. See the [integration guide](docs/integrations.md) for host setup.
105
+ Existing installations should read the [rename migration guide](docs/integrations.md#更名与已有安装迁移) before upgrading.
106
+
107
+ ## Quick start
108
+
109
+ ```bash
110
+ pip install colink-memory
111
+ ```
112
+
113
+ Current release: **1.0.3**. See the [release notes](CHANGELOG.md).
114
+
115
+ ```python
116
+ from octop_memory import Memory, MemoryService
117
+
118
+ memory = Memory(
119
+ namespace="demo",
120
+ backend_config={"db_path": "./demo.sqlite"},
121
+ )
122
+ memory.store("User prefers Python for backend services", topic="preferences")
123
+
124
+ # Basic fact search returns MemoryNode leaf projections.
125
+ for node in memory.recall("Python"):
126
+ print(node.content)
127
+
128
+ # Prompt recall adds source selection, ranking, deduplication, and budgeting.
129
+ result = MemoryService(memory).recall("Python")
130
+ print(result.rendered)
131
+ ```
132
+
133
+ 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.
134
+
135
+ ### Optional dependencies
136
+
137
+ | Install | Purpose |
138
+ |---|---|
139
+ | `pip install "octop-memory[cli]"` | CLI and OpenClaw setup commands |
140
+ | `pip install "octop-memory[postgres]"` | PostgreSQL memory backend |
141
+ | `pip install "octop-memory[langgraph]"` | SQLite LangGraph checkpointer |
142
+ | `pip install "octop-memory[langgraph-postgres]"` | PostgreSQL LangGraph checkpointer |
143
+
144
+ Vector search interfaces and Chroma/Qdrant adapters exist in the code, but current tests use fake/mock implementations; real Chroma/Qdrant integration remains unverified. Vector search is not enabled by default and is not yet presented as a fully supported installation option. Using it requires initializing an index and injecting `vector_index` and `embedding_provider` into `Memory`; installing dependencies alone does not enable it. The database backend remains `sqlite` or `postgres`.
145
+
146
+ ```python
147
+ memory = Memory(
148
+ namespace="demo",
149
+ backend="postgres",
150
+ backend_config={"dsn": "postgresql://user:pass@localhost/octop_memory"},
151
+ )
152
+ ```
153
+
154
+ Use deployment configuration for real credentials. SQLite isolates memory with table prefixes; PostgreSQL uses namespace-first keys in the shared `octop_memory` schema.
155
+
156
+ The PostgreSQL upgrade for Chinese Atom search rebuilds the shared Atom full-text index on first open. Plan a maintenance window for large stores: the one-time migration takes an exclusive lock on the Atom table.
157
+
158
+ Within one process, PostgreSQL instances with the same connection settings share a business pool (up to 8 connections) and a checkpoint/maintenance pool (up to 4), independent of agent count. Each pool allows at most 64 queued requests with a 30-second checkout timeout; saturation raises an explicit error. Idle pools can shrink to zero, and closing one instance leaves other instances usable. Budget separately for multiple processes, different connection settings, and the host's own database connections.
159
+
160
+ ## CLI
161
+
162
+ Install `[cli]`. Global options precede subcommands; use an explicit database and namespace when following examples.
163
+
164
+ ```bash
165
+ octop-memory --db ./demo.sqlite --namespace demo memory store --content "User prefers Python"
166
+ octop-memory --db ./demo.sqlite --namespace demo recall "Python"
167
+ octop-memory --db ./demo.sqlite --namespace demo memory tree
168
+ octop-memory --help
169
+ ```
170
+
171
+ | Commands | Purpose |
172
+ |---|---|
173
+ | `raw`, `candidate`, `atom`, `entity`, `page` | Inspect and manage memory layers |
174
+ | `episode`, `digest`, `journal` | Event summaries and decision records |
175
+ | `memory`, `recall`, `thread` | Tree operations, prompt recall, thread state |
176
+ | `export`, `import`, `migrate`, `portable` | Backup and migration |
177
+ | `db`, `gc`, `consolidate` | Storage maintenance and lifecycle operations |
178
+ | `config`, `openclaw`, `backfill` | Configuration, integration, historical extraction |
179
+
180
+ 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.
181
+
182
+ 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.
183
+
184
+ ## External agent adapters
185
+
186
+ `plugins/<host>/` maps external agent hooks, tools, and configuration to the shared Python runtime.
187
+ OpenClaw and Hermes adapters are available today. Other agents can integrate through the Python API or JSON-RPC,
188
+ with an adapter implementing their host contract.
189
+
190
+ | Integration | Use case | Entry point |
191
+ |---|---|---|
192
+ | In-process Python | Custom agents / Python applications | `MemoryService.capture_turn()` / `recall()` / `search()` / `get()` / `extract()` |
193
+ | JSON-RPC bridge | Cross-language or separate processes | stdio `octopmemory-bridge` |
194
+ | Host plugin | Agent-specific lifecycle and tool interfaces | `plugins/<host>/`; OpenClaw and Hermes currently implemented |
195
+
196
+ See the [integration guide](docs/integrations.md) for installation, configuration, profiles, troubleshooting, and adapter boundaries.
197
+
198
+ Move memory with `octop-memory portable list-sources / pack / adopt / doctor`. Exported `.hmpkg` files contain memory data; keep them out of source control.
199
+
200
+ ## Code architecture
201
+
202
+ ```text
203
+ src/octop_memory/
204
+ ├── core.py / types.py # Public Memory API and data structures
205
+ ├── service.py # MemoryService: Python host entry point
206
+ ├── application/ # MemoryRuntime, config, host files, path projection
207
+ ├── pipeline/ # Extraction, promotion, recall, pages, episodes, lifecycle
208
+ ├── storage/ # SQLite / PostgreSQL, checkpoints, vector indexes
209
+ ├── ports/ # External capability interfaces, including LLM clients
210
+ ├── domain/ # Shared alias and time rules
211
+ ├── adapters/ # JSON-RPC bridge, CLI, source-only dashboard
212
+ └── operations/ # Import/export, migration, portable packages
213
+ plugins/ # External agent adapters, organized by host
214
+ examples/ # Public API example
215
+ tests/ / evals/ # Behavior tests / synthetic recall evaluation
216
+ docs/agent/ # Harness project map, decisions, and handoff
217
+ ```
218
+
219
+ Adapters call inward through application and pipeline/core/storage layers. `MemoryService` and `Bridge`
220
+ share `MemoryRuntime`; pipeline/storage do not depend on adapters, and backend-specific SQL stays in storage.
221
+ The source dashboard's direct SQLite access is an existing exception.
222
+
223
+ ### Host call flow
224
+
225
+ ```text
226
+ Python host → MemoryService ─────────┐
227
+ Hermes → in-process Bridge ──────────┤
228
+ OpenClaw → JSON-RPC bridge ───────────┴→ MemoryRuntime → pipelines → Memory
229
+ CLI → application / operations ────────────────────────────────────┘
230
+ ├→ SQLite / PostgreSQL
231
+ └→ optional vector index
232
+ ```
233
+
234
+ 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.
235
+
236
+ ### Long-term memory flow
237
+
238
+ ```text
239
+ RawEvent ──extraction──→ Candidate ──promotion──→ AtomCard ──dirty / regeneration──→ EntityPage
240
+ └──episode extraction──→ Episode └──atom_id reference──→ tree leaf
241
+ ```
242
+
243
+ Candidates do not all require human approval. Promotion checks value, evidence, entity resolution,
244
+ duplicates, and conflicts; it can promote, merge, or drop candidates automatically, leaving review/conflict
245
+ cases for user action. Pages are marked dirty and regenerated when triggered by runtime/CLI/host,
246
+ rather than immediately after every write. Episode extraction is a parallel path from raw events.
247
+ Manual `Memory.store()` needs no model and directly creates RawEvent/Candidate/AtomCard plus a leaf reference.
248
+
249
+ 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.
250
+
251
+ Synthetic runtime failures are excluded from automatic capture, extraction and raw prompt fallback. octop-harness / Octop raise model errors into checkpoint task failures and display diagnostics separately; automatic team failure notifications are excluded from capture. Hosts that still create synthetic replies must mark them with `payload.octop_runtime_error=true`; online filtering uses structured provenance only. Agents decide when to call `memory_save`; approvals and manual saves are protected by their provenance, without intent or troubleshooting-value keyword lists. Automatic capture keeps its length policy with no intent-keyword exception; explicit saves bypass that capture policy. Original diagnostics remain inspectable by ID. `operations.retention.audit_runtime_errors(memory)` previews eligible records by default; even `apply=True` retires only automatic atoms whose evidence is entirely marked as runtime failures. The fixed legacy retry envelope only nominates `review_atom_ids` / `review_candidate_ids`; missing and mixed evidence stays unchanged for human review.
252
+
253
+ `MemoryService.reconcile_manual_documents({"USER.md": text, "MEMORY.md": text})` gives owner-edited documents priority. Bridge exposes the same operation and `manual_document_review_status`. Proven conflicts softly retire the old atom and create a replacement review candidate with original evidence and a journal trail; acceptance makes the replacement a confirmed fact. Duplicate atoms remain stored; pass the actual session snapshot as `recall(..., manual_context=documents)` to suppress repeated context. An optional `manual_documents_provider` supplies current files to background review. `save`, extraction, and promotion do not synchronously run manual-document comparison; the host calls the public `MemoryService.review_new_memory(max_atoms=20)` on a background worker (the method itself is synchronous). An explicit reconcile still checks up to 100 new facts per call and accepts at most 100,000 document characters. A failed model batch is deferred, and three failures mark those facts uncertain without retiring them. Partial checks are resumable; unavailable/uncertain/invalid semantic checks are explicit and never force retirement. Full documents are comparison metadata, not indexed atoms. See ADR-042.
254
+
255
+ 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).
256
+
257
+ ## Development
258
+
259
+ ```bash
260
+ make install # uv sync --group dev
261
+ make install-hooks # required once per clone
262
+ make all # format + lint + strict mypy + tests
263
+ uv build # Python wheel + source distribution
264
+ ```
265
+
266
+ 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/`.
267
+
268
+ 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).
269
+
270
+ ## License
271
+
272
+ [MIT](LICENSE). Report vulnerabilities through the channels in [SECURITY.md](SECURITY.md).
@@ -0,0 +1,114 @@
1
+ octop_memory/__init__.py,sha256=7zXaetz0jQdilhp_G7cln9vKQJ6PrnxJhQOo2n0UDTE,1810
2
+ octop_memory/_config_io.py,sha256=1FrDiu-ExcDlFSHMYYkelt_n6KfdsDCGfBBG0dK0bis,2623
3
+ octop_memory/core.py,sha256=SIJgX7cGyXkw_kcc0BELRBEW_zwIDvEJ3iDgg3syaLU,72622
4
+ octop_memory/service.py,sha256=NB-z9X8TMWUIf1N3qBLMZD6qPKlZMh3P7nMft0TyaDI,12969
5
+ octop_memory/types.py,sha256=iG-EilW5e08WYJF0MN2hK6IKciecuJthORTBdsvhIVo,19278
6
+ octop_memory/adapters/__init__.py,sha256=gWehBqJHxw2sMvGrG-UGxFcppLLG7ulLALpq_jQNzzY,72
7
+ octop_memory/adapters/bridge/__init__.py,sha256=nXQVb8P4-B7EruLjxuy5n6745WwzSD5WQ3U5kC33UWY,1448
8
+ octop_memory/adapters/bridge/handlers.py,sha256=fBAUo1p9M5K8yKzfh8RnpKdOANMlxuy3WGrGjgBIUYY,4537
9
+ octop_memory/adapters/bridge/server.py,sha256=SIWzyu-xDF6hGmo7K8t8ukj8soCb04FaDk6dt8Dsaxw,12163
10
+ octop_memory/adapters/cli/__init__.py,sha256=cGbFutH_G0TiSmdJm2tEHZNKAggDBuDL5MAVe8aUGAE,4720
11
+ octop_memory/adapters/cli/atom_cmd.py,sha256=RmQjZdrifn0bDYDd_PKBk_Zfgd_T7vVkBv_oGnXglDs,4823
12
+ octop_memory/adapters/cli/candidate_cmd.py,sha256=paVGT39inwYVsD5PIYwEjVFeCnsZqBB9NpeJuGG8hOY,28513
13
+ octop_memory/adapters/cli/checkpoint_cmd.py,sha256=_72jr3-6Ljwqv74DcoNlDoINuCVSKr15DEpPaYi-ENY,2921
14
+ octop_memory/adapters/cli/config.py,sha256=PL0zqmt3WrEuo2gDyvM5JVIZ5Pj9hezD8CRJ4cFczKI,4580
15
+ octop_memory/adapters/cli/consolidate_cmd.py,sha256=GsujzBm1isf3O2mr7PNacuhEVi9Ya125X3-wLLaigm0,4529
16
+ octop_memory/adapters/cli/db_cmd.py,sha256=SeU-WWAw353r7aP_L2Ay1ePdaYGoo9Yf5uMjwj3xcig,10314
17
+ octop_memory/adapters/cli/entity_cmd.py,sha256=Ho_n8ACLxxyg1H06HGeDWdU0CrRRdwp1cPZr44GuBE0,3961
18
+ octop_memory/adapters/cli/episode_cmd.py,sha256=S47HtvxGB-Tn44E3ccB5pmQfJ1VDmyz3dHMHwqGUwlc,7753
19
+ octop_memory/adapters/cli/gc_cmd.py,sha256=FNoA5b5P8gV-_0SIMN7jgIPPk7pPNrbVfTK4e9MxAks,3243
20
+ octop_memory/adapters/cli/journal_cmd.py,sha256=fqR01K_1mP-HjPH87p-0lmXOHQ8ylT3aDcDpjRlnIEE,3840
21
+ octop_memory/adapters/cli/memory_cmd.py,sha256=HaTJj3Yksz3cXe3aiBI9NLXEiJINtBYKMvHfvo0t4Hw,9141
22
+ octop_memory/adapters/cli/migration_cmd.py,sha256=ZhEUOM0mqfaCmy7JBUxlALWuXvSpbQEsAcdbO_u65dc,11773
23
+ octop_memory/adapters/cli/openclaw_cmd.py,sha256=bfyZr7WX7UytOnrZpjrYOUJk7BXBZ61Hlz378aR1BJU,24697
24
+ octop_memory/adapters/cli/page_cmd.py,sha256=vkd5FXAyUUODaYywqLbcRx2Pr1YoDdp_YdjnZG9sqYA,9790
25
+ octop_memory/adapters/cli/portable_cmd.py,sha256=QPv9DPbivzXkVmxSQfkJgs7e5y9uDoFRPpIsax_A0pA,8971
26
+ octop_memory/adapters/cli/raw_cmd.py,sha256=RHcQwGR4LhcEIc3cKTCBs2fYL3YMdWCSXg5ENZkPdFw,6886
27
+ octop_memory/adapters/cli/recall_cmd.py,sha256=DsMDnhG0QfHZt_wQdfn2Dez-vheNviKafqlNYpoJOJ0,4107
28
+ octop_memory/adapters/cli/slim_cmd.py,sha256=ftDr5PkqhnvRvMrsc5Pp4b6uDAhkAof2hdsz6L0oRT8,4142
29
+ octop_memory/adapters/cli/thread_cmd.py,sha256=1yaQnfoI_L6Lk_LSfEeD0J9J4fTYLjZeSHj8VfF_9g0,5097
30
+ octop_memory/application/__init__.py,sha256=7kQuAmH_3mVz8VIhVNOifg6ros9uZPu0Q5jxcaSYw50,73
31
+ octop_memory/application/checkpoint_maintenance.py,sha256=OwXgwom0zoJCv4oUym_cgI_i9vMr2Ywk1BlieLV9P8w,1218
32
+ octop_memory/application/config.py,sha256=hihj2PyESNVmZLy9nJJVCIHwk8hRMmGugcPJqB36LfQ,2644
33
+ octop_memory/application/dashboard_data.py,sha256=6FR45-dbi_eN5FKIe5lYlSlF6caBtXt8mllI7KAdilo,46149
34
+ octop_memory/application/host_files.py,sha256=_NgmRQPwn-Fb1D2FFz6mtzUrMty0JbjUjru5N__uciA,19491
35
+ octop_memory/application/path_projection.py,sha256=cgaIveqAfCdS1LXm9-EWvwoLEcyxlgn8qAHCBjeh0qM,12372
36
+ octop_memory/application/runtime.py,sha256=zbsIHDkzmn-bYORu2RjU8Ci9nzb1aYlDVaoQ6JYMSRY,48637
37
+ octop_memory/domain/__init__.py,sha256=Yya0CvfY75YQGecRKxg0OyHeOm9v7YZ4JRPP4AF9ryw,73
38
+ octop_memory/domain/alias.py,sha256=xr876--WHQRtw8qk2EDXksi_O3AL-je-HTrKGm0cP68,1372
39
+ octop_memory/domain/datetime.py,sha256=tOkgncqYoKmRRp6IjlhRzG8HK-eHNyrVwmHGrjpmZZo,864
40
+ octop_memory/domain/retention.py,sha256=ygiphqbMKUXbvtEMv42-WaOvKM5aju5qEWxcroydUds,2197
41
+ octop_memory/operations/__init__.py,sha256=LTqZPYeT4aIXOi7I2Xu17c0cq_Nkhl6Oc8p7q3y5qJw,77
42
+ octop_memory/operations/retention.py,sha256=fol02D2B1xvi9SGkSfvqy6wi4ARpmoL49xJkjiV8_zs,24342
43
+ octop_memory/operations/migration/__init__.py,sha256=MKCiMqnjyPyZb8NeH7_53VsAgTZ4ML-AG0VDIUjAIek,1481
44
+ octop_memory/operations/migration/backfill.py,sha256=49G-IPLscGzWNm4fiAS6RJ7G7oW-_DnN8FkS3Ih5tak,9796
45
+ octop_memory/operations/migration/export.py,sha256=HKlKquytvdwODJQjFkRj2QS2tlPZr7qwWYMd5c2byFM,11057
46
+ octop_memory/operations/migration/import_.py,sha256=SJXaTPBhub7xqMUPPHspDTs_kjGnJf1kKMSiiLY1xJw,14007
47
+ octop_memory/operations/migration/preview.py,sha256=03MU0j-fYdm3wMA16ojkqvyAP1UZbZzOQEDBNdJy-3k,3213
48
+ octop_memory/operations/migration/rename.py,sha256=m6AcZM93WBcCS8WVkyoeSfAioGInl8gP8AxUah6rzG0,17599
49
+ octop_memory/operations/migration/portable/__init__.py,sha256=sJucbOs5mkpFGSy3Lo_XomPSZxi-tOZNB1awoeU1QpQ,2225
50
+ octop_memory/operations/migration/portable/adopter.py,sha256=1eCGh7pGqujqh1aocqVB9RcjEuN_v0PgPVlmUXZjNac,18212
51
+ octop_memory/operations/migration/portable/doctor.py,sha256=BIpK_0t0GlJ_UpDA0YYkeVOUp6nfFUiDIQ7n363T1T4,13680
52
+ octop_memory/operations/migration/portable/models.py,sha256=-6Vuis8gCKmnt0jjDGTmPuasI3r0twcuVBffzT9EO1U,7731
53
+ octop_memory/operations/migration/portable/packer.py,sha256=e5hdox5BXs5zTjVYUkcZccmltMzmb24JYQqzC89yk98,8906
54
+ octop_memory/operations/migration/portable/sources.py,sha256=Aa5dpK26dueLIUy8oWgt6Wkq2-Aj1Kk6CmTPd6hW5lY,9259
55
+ octop_memory/pipeline/__init__.py,sha256=jw9U7qJ_BstolRGMjgX-rECp8GBuntEGNYLVcu_OPJs,75
56
+ octop_memory/pipeline/episode/__init__.py,sha256=2_Xc7g7CIWWLiq1SahkJC5iJlwLqxFka5ecHl53picM,12118
57
+ octop_memory/pipeline/episode/digest.py,sha256=sPlE4Hr7XWROt5tNLyk07JphJr--Q0FcCMe1BYvJjgI,17298
58
+ octop_memory/pipeline/episode/prompts.py,sha256=vkb6bETBgGJwm7uyM60wuee85daU7qzVFBbWL-cqIEA,5226
59
+ octop_memory/pipeline/extractor/__init__.py,sha256=bP9caTHmxE5Yrk_khcofYjVh_HO7jS3WISQvpqp-95o,13639
60
+ octop_memory/pipeline/extractor/parser.py,sha256=6XzqbmlNTkQFFZ08IbgUHEIVTAPPto2BCBdAwe31fd8,15392
61
+ octop_memory/pipeline/extractor/prompts.py,sha256=RJgmREDu_GPBaDHQEFwkQZqMjQLXU3RvXggl3CJV8K8,22018
62
+ octop_memory/pipeline/lifecycle/__init__.py,sha256=YrOvPbHxJIiAqikgRj5ZT21CiWPp1M6VW2uYDoOkZRQ,2302
63
+ octop_memory/pipeline/lifecycle/checkpoint_gc.py,sha256=sYtfh8W54oXsWMxvUFs0Aq-D-2wVjOdPz83NEVnBJQw,25788
64
+ octop_memory/pipeline/lifecycle/consolidate.py,sha256=AvUXNA3kUEwfrDbOwlG8eKSBRr135CXCqDhdmrrWLcg,13135
65
+ octop_memory/pipeline/lifecycle/gc.py,sha256=68uAZi9Ri1sirTl4XEQQSB0YqgzWn71MueTZOWciZKw,12538
66
+ octop_memory/pipeline/lifecycle/maintenance.py,sha256=Km4H8GboKDWKz-L2xEC6TQpAreC-V0IwBrQT2ZZGlj0,11768
67
+ octop_memory/pipeline/lifecycle/vacuum.py,sha256=pUWcsjWiEoT4etczYMgOgk1FsQXqob8sWtfIkW3tXfk,29871
68
+ octop_memory/pipeline/page/__init__.py,sha256=psim4bQC3LUrFNfgbzDsoOKbu5j_gWhkE6L9fDJFBSE,1713
69
+ octop_memory/pipeline/page/headline.py,sha256=xBufgHfhWEnXd4ZwLyh_-cY8LCXMEN1wu43tn_PwTzw,2141
70
+ octop_memory/pipeline/page/prompts.py,sha256=8638Oyn2f3nwIwwUknRRGh0h7R-OQJbqXx8CuSzPgxM,3837
71
+ octop_memory/pipeline/page/regenerator.py,sha256=_aSFQ_OBQZWlpQPy-nD6YG3NU2sweWJfhte76CONHok,13562
72
+ octop_memory/pipeline/page/trigger.py,sha256=Jk-0L8TrXtm693qchNiP8V0Vc59PHOWV-7d6MkH7BI4,2584
73
+ octop_memory/pipeline/page/user_notes.py,sha256=NYyjyMGiprYsC2lzBbbbROHmhRwhbsXRam9th90RZAQ,4016
74
+ octop_memory/pipeline/promotion/__init__.py,sha256=FP0Q77YK86kL6spv5jwhuygFnoK0RRZO9spYMDTQHI4,25358
75
+ octop_memory/pipeline/promotion/checks.py,sha256=YW-goaOER4fYPbKh0kTIMyh5XkHv0df3Bz0dt2c4FLA,25126
76
+ octop_memory/pipeline/promotion/fallback.py,sha256=2RGZ1gWDA4mLaXA5Zrq3cVz3irBZB86b2rpw1qz0plc,9835
77
+ octop_memory/pipeline/promotion/llm_hook.py,sha256=sO20_DA8_gt7UZ8X5TL27mbXirOtzYel7Lno8SmOSzg,9374
78
+ octop_memory/pipeline/recall/__init__.py,sha256=jToWYdYskHSemSBMBdtFGfzzJhsNtS0g63Fx1raxtpY,22333
79
+ octop_memory/pipeline/recall/budget.py,sha256=gSGaFG7tAD67zkPNAX4Hj3_4mtp9CLMP_YC6T3G4KTE,6154
80
+ octop_memory/pipeline/recall/cache.py,sha256=5_ZZ_nqZwcqm3QbFi2McvIf_w_t6mWTdT7D5srtfQLw,3315
81
+ octop_memory/pipeline/recall/diversify.py,sha256=njICPpZ-T4EAuvnDkyma0WeC-Qn4OmMErkFFDnMI4Yw,2284
82
+ octop_memory/pipeline/recall/multi_source.py,sha256=7VJWGthiLBQ2BxSgr4LdjoyLZJ1RBFcvIu6pOxWxcP8,18824
83
+ octop_memory/pipeline/recall/parser.py,sha256=psfbwg-nRGqXacCsDDQugJw-LG7Vlyym6sont7xr-RA,10328
84
+ octop_memory/pipeline/recall/rerank.py,sha256=8f5whD1IVmhMy8gD0wec_25hCrwzZ9KfXVTsIwmetIA,10173
85
+ octop_memory/pipeline/recall/router.py,sha256=YmuiOAeQHPPGUC94neuGPPyFPeeA4xWF1zdhr73aQmE,4636
86
+ octop_memory/pipeline/recall/suppress.py,sha256=JLZbeQNwHNxDCAkx8jlIYXsDAW-XLZF9y1rp3HZlt4E,4954
87
+ octop_memory/pipeline/recall/thread_state.py,sha256=Dxr6FtNIr9L6QkSfSJSscSWVHbx1M-_mwznzTSosVxw,4021
88
+ octop_memory/pipeline/recall/timeout.py,sha256=eDGN95NWGKQtJ_UvRS2losR5lurohJZjcTsGV7T8JFc,3961
89
+ octop_memory/ports/__init__.py,sha256=pc9ySPosIpLQV0xsaMi0HkyIN3LuurgDnwGcPEGPFsM,56
90
+ octop_memory/ports/llm/__init__.py,sha256=BByqfZKOIfHRryyfVGZCc8wFFcwWEPJvCkZEXgr3JM4,1971
91
+ octop_memory/ports/llm/_protocol.py,sha256=wNgcOkA0XWmtFWAWoLFupGvUbH_vJcTd136ZPbI9-kw,4339
92
+ octop_memory/ports/llm/mock.py,sha256=EFgarZk8QNFgYrWTyEUIYZLgUPPEqBSnY7cMbhCMhw4,3654
93
+ octop_memory/ports/llm/openai_compat.py,sha256=ykOjyn8ZM9UkB06lp54jmgUh7P7YYb_Z4DquPmLOTdQ,9387
94
+ octop_memory/storage/__init__.py,sha256=-oUriwsqwO_uDRhVYdRaWQdGe80AUpFlUO3D_KT3ZsI,63
95
+ octop_memory/storage/driver_errors.py,sha256=-YvWl8jT00kYfE71SN3LH8eY9g2H17kkJDnIJMlgea0,1918
96
+ octop_memory/storage/backends/__init__.py,sha256=ZWnV_L4xO-A-EkXbczsrGpILRjHPzND-Yw87S2bYrTg,20012
97
+ octop_memory/storage/backends/forget.py,sha256=he2eCVcSnEo6A3FrBJfF5L8RIf-i4dZbVmKrI2KaLMA,12395
98
+ octop_memory/storage/backends/fts_text.py,sha256=tzIcHbdJahCMT0DqZr5FiFGJcOhfjgswgWWFdMUd-S4,3383
99
+ octop_memory/storage/backends/postgres.py,sha256=BEj_b7h1IjgPdRrZbvm-DymtHgIPqhW5lvx2UazIPiM,102188
100
+ octop_memory/storage/backends/postgres_pool.py,sha256=203rOS5uyZOhMGhdvmOEiedw0LhJaC1HmZNlt3Bcix4,4798
101
+ octop_memory/storage/backends/sqlite.py,sha256=2U4S8L6j-dOe-lQGm9VgZjYMx_j4En6abmpr9_W6DQc,98523
102
+ octop_memory/storage/backends/sqlite_checkpoint.py,sha256=6jQYBYX9QMCUJ6JEdoNrY1_IGLeeTi16-pfyaG-ezj0,9552
103
+ octop_memory/storage/backends/sqlite_checkpoint_job.py,sha256=_vxS_ttnDe739nFTf9U_ROHm2cXBOQCp64oPkTsm86k,4921
104
+ octop_memory/storage/backends/sqlite_checkpoint_live.py,sha256=gF275mCYf9ICirWQ8gESHLrBL15E1deGI2iCmxKKPrU,3699
105
+ octop_memory/storage/backends/sqlite_checkpoint_maintenance.py,sha256=z9-2F-ZRVF7d_S2wyudS0Z0ick06bMTkGcgO4hizWQI,10911
106
+ octop_memory/storage/vector/__init__.py,sha256=s3qzse1bOG3C51MjOZr7YkORD7MaaEl0eiG2HGrmuqo,3565
107
+ octop_memory/storage/vector/chroma.py,sha256=vIsEfa3Cp2oDX6fqPn0j1htXMBoABGlymgcLvqi9Dng,5684
108
+ octop_memory/storage/vector/embeddings.py,sha256=ktL_faDs16pT3K9sT7o891-3WY1ZK0H6DQM7DlrQ8xc,9619
109
+ octop_memory/storage/vector/qdrant.py,sha256=zXb9wtZCuyvPZ6kupGby7p-11Tu4nDiFL_amIUxyIok,6826
110
+ colink_memory-1.0.3.post1.dist-info/METADATA,sha256=Bdsdp6RdAR3275DGjnVn0ZouzkOUcegRoVSQyhDOMNQ,17718
111
+ colink_memory-1.0.3.post1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
112
+ colink_memory-1.0.3.post1.dist-info/entry_points.txt,sha256=doyhHkOski5mYZbxAWY4ARNR-GiSB9uVmlZW60a8us8,126
113
+ colink_memory-1.0.3.post1.dist-info/licenses/LICENSE,sha256=KZQwXHx21B5YVep7xogAySPBO_wSTi3er7AUfUK5zuQ,1064
114
+ colink_memory-1.0.3.post1.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ octop-memory = octop_memory.adapters.cli:main
3
+ octopmemory-bridge = octop_memory.adapters.bridge.server:main
@@ -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.
@@ -0,0 +1,56 @@
1
+ """octop-memory: pluggable memory system for LLM agents."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import TYPE_CHECKING
6
+
7
+ from octop_memory.core import Memory
8
+ from octop_memory.types import (
9
+ MemoryNode,
10
+ ThreadState,
11
+ ThreadSummary,
12
+ )
13
+
14
+ try:
15
+ from octop_memory._version import __version__ # type: ignore[import-untyped]
16
+ except ImportError:
17
+ # No build-time _version module (the version in pyproject.toml is static,
18
+ # so nothing generates one). Installed wheels must report the real version
19
+ # from distribution metadata instead of the "+unknown" placeholder, which
20
+ # previously leaked into `--version`, bridge --probe, and doctor output.
21
+ try:
22
+ from importlib.metadata import PackageNotFoundError, version
23
+
24
+ __version__ = version("colink-memory")
25
+ except PackageNotFoundError:
26
+ # Source checkout without an installed distribution.
27
+ __version__ = "0.0.0+unknown"
28
+
29
+ if TYPE_CHECKING:
30
+ # Type-checker-visible without paying the import at runtime.
31
+ from octop_memory.service import MemoryService
32
+
33
+
34
+ def __getattr__(name: str) -> object:
35
+ """Lazily expose :class:`MemoryService` (PEP 562).
36
+
37
+ ``MemoryService`` pulls in the bridge + extraction + CLI stack, so importing
38
+ it eagerly here would (a) make ``import octop_memory`` heavy and (b) create
39
+ a circular import via ``cli`` reading ``__version__`` back from this module.
40
+ Loading it on first attribute access keeps the top-level package light.
41
+ """
42
+ if name == "MemoryService":
43
+ from octop_memory.service import MemoryService
44
+
45
+ return MemoryService
46
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
47
+
48
+
49
+ __all__ = [
50
+ "Memory",
51
+ "MemoryNode",
52
+ "MemoryService",
53
+ "ThreadState",
54
+ "ThreadSummary",
55
+ "__version__",
56
+ ]
@@ -0,0 +1,98 @@
1
+ """Plain config IO module (no click dependency).
2
+
3
+ Provides load/save for ``~/.octop-memory/config.json``, used by:
4
+
5
+ - :mod:`octop_memory.adapters.cli.config` when building CLI commands (adds the
6
+ click dependency on top)
7
+ - core modules that need to run without click
8
+
9
+ Decoupling this layer from click / Memory means facades like
10
+ ``MemoryService`` don't have to treat ``[cli]`` as a hard dependency.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import json
16
+ from pathlib import Path
17
+ from typing import Any
18
+
19
+ CONFIG_DIR = Path("~/.octop-memory").expanduser()
20
+ CONFIG_FILE = CONFIG_DIR / "config.json"
21
+
22
+
23
+ class _ConfigPathState:
24
+ """Mutable holder for the config file path override.
25
+
26
+ Using an attribute on a module-level singleton (rather than reassigning
27
+ a bare module-level name) lets ``set_config_path`` mutate the override
28
+ without a ``global`` statement.
29
+ """
30
+
31
+ override: Path | None = None
32
+
33
+
34
+ _state = _ConfigPathState()
35
+
36
+
37
+ def set_config_path(path: Path | None) -> None:
38
+ """Set the config file path (called by CLI --config flag)."""
39
+ _state.override = path
40
+
41
+
42
+ def get_config_path() -> Path:
43
+ """Get the effective config file path."""
44
+ return _state.override or CONFIG_FILE
45
+
46
+
47
+ DEFAULTS: dict[str, Any] = {
48
+ "backend": "sqlite",
49
+ "namespace": "default",
50
+ "sqlite": {
51
+ "db_path": "~/.octop-memory/memory.db",
52
+ },
53
+ "postgres": {
54
+ "dsn": "postgresql://localhost/octop_memory",
55
+ },
56
+ "qdrant": {
57
+ "url": "http://localhost:6333",
58
+ },
59
+ }
60
+
61
+
62
+ def load_config() -> dict[str, Any]:
63
+ """Load config from file, merged with defaults."""
64
+ config_file = get_config_path()
65
+ config = dict(DEFAULTS)
66
+ if config_file.exists():
67
+ try:
68
+ with open(config_file) as f:
69
+ user_config = json.load(f)
70
+ # Deep merge for backend-specific sections
71
+ for key, value in user_config.items():
72
+ if isinstance(value, dict) and isinstance(config.get(key), dict):
73
+ config[key] = {**config[key], **value}
74
+ else:
75
+ config[key] = value
76
+ except (json.JSONDecodeError, OSError):
77
+ pass
78
+ return config
79
+
80
+
81
+ def save_config(config: dict[str, Any]) -> None:
82
+ """Save config to file."""
83
+ config_file = get_config_path()
84
+ config_file.parent.mkdir(parents=True, exist_ok=True)
85
+ with open(config_file, "w") as f:
86
+ json.dump(config, f, indent=2, ensure_ascii=False)
87
+ f.write("\n")
88
+
89
+
90
+ __all__ = [
91
+ "CONFIG_DIR",
92
+ "CONFIG_FILE",
93
+ "DEFAULTS",
94
+ "get_config_path",
95
+ "load_config",
96
+ "save_config",
97
+ "set_config_path",
98
+ ]
@@ -0,0 +1 @@
1
+ """Host-facing adapters for CLI, bridge, and dashboard integrations."""
@@ -0,0 +1,37 @@
1
+ """OpenClaw/Hermes memory bridge protocol.
2
+
3
+ This subpackage hosts the Python side of the octopmemory ↔ OpenClaw
4
+ plugin bridge. The TS plugin shell (``plugins/openclaw/octopmemory/``)
5
+ spawns ``octopmemory-bridge`` as a subprocess and talks to it over
6
+ stdin/stdout using a tiny JSON-RPC 2.0 dialect.
7
+
8
+ Design:
9
+
10
+ - **D51-C** (path projection, 2026-06-04 locked):
11
+ ``path_projection`` projects SQLite-backed atoms / pages / raw events
12
+ onto a *virtual* file tree (``atom/<id>.md`` etc.) so OpenClaw's
13
+ file-shaped ``memory_get(path, from, lines)`` API works against our
14
+ storage. Real files (``MEMORY.md``, ``memory/YYYY-MM-DD.md``) are
15
+ ALSO indexed via ``host_files`` so the host's compaction
16
+ silent turn is preserved verbatim.
17
+
18
+ - **D52-C** (auto-capture, 2026-06-04 locked):
19
+ ``handlers.capture`` is the entry point for the TS ``agent_end``
20
+ hook; it validates and filters a batch, then writes it synchronously
21
+ through ``Memory.add_raw_batch``.
22
+
23
+ The bridge is intentionally minimal: no auth, no encryption — it runs
24
+ as a child process of OpenClaw on the same machine as the user.
25
+ It does not expose a TCP/HTTP or remote multi-tenant transport.
26
+ """
27
+
28
+ from __future__ import annotations
29
+
30
+ __all__ = [
31
+ "PROTOCOL_VERSION",
32
+ ]
33
+
34
+ PROTOCOL_VERSION = "1.0"
35
+ """Wire protocol version. Bumped only on breaking changes to the JSON-RPC
36
+ method names or payload schemas. The TS client checks this on
37
+ ``handshake`` and refuses to start on mismatch."""