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.
- colink_memory-1.0.3.post1.dist-info/METADATA +272 -0
- colink_memory-1.0.3.post1.dist-info/RECORD +114 -0
- colink_memory-1.0.3.post1.dist-info/WHEEL +4 -0
- colink_memory-1.0.3.post1.dist-info/entry_points.txt +3 -0
- colink_memory-1.0.3.post1.dist-info/licenses/LICENSE +21 -0
- octop_memory/__init__.py +56 -0
- octop_memory/_config_io.py +98 -0
- octop_memory/adapters/__init__.py +1 -0
- octop_memory/adapters/bridge/__init__.py +37 -0
- octop_memory/adapters/bridge/handlers.py +127 -0
- octop_memory/adapters/bridge/server.py +343 -0
- octop_memory/adapters/cli/__init__.py +130 -0
- octop_memory/adapters/cli/atom_cmd.py +143 -0
- octop_memory/adapters/cli/candidate_cmd.py +795 -0
- octop_memory/adapters/cli/checkpoint_cmd.py +81 -0
- octop_memory/adapters/cli/config.py +155 -0
- octop_memory/adapters/cli/consolidate_cmd.py +123 -0
- octop_memory/adapters/cli/db_cmd.py +268 -0
- octop_memory/adapters/cli/entity_cmd.py +121 -0
- octop_memory/adapters/cli/episode_cmd.py +239 -0
- octop_memory/adapters/cli/gc_cmd.py +97 -0
- octop_memory/adapters/cli/journal_cmd.py +114 -0
- octop_memory/adapters/cli/memory_cmd.py +290 -0
- octop_memory/adapters/cli/migration_cmd.py +330 -0
- octop_memory/adapters/cli/openclaw_cmd.py +624 -0
- octop_memory/adapters/cli/page_cmd.py +267 -0
- octop_memory/adapters/cli/portable_cmd.py +279 -0
- octop_memory/adapters/cli/raw_cmd.py +229 -0
- octop_memory/adapters/cli/recall_cmd.py +127 -0
- octop_memory/adapters/cli/slim_cmd.py +84 -0
- octop_memory/adapters/cli/thread_cmd.py +152 -0
- octop_memory/application/__init__.py +1 -0
- octop_memory/application/checkpoint_maintenance.py +28 -0
- octop_memory/application/config.py +76 -0
- octop_memory/application/dashboard_data.py +1218 -0
- octop_memory/application/host_files.py +512 -0
- octop_memory/application/path_projection.py +349 -0
- octop_memory/application/runtime.py +1165 -0
- octop_memory/core.py +1887 -0
- octop_memory/domain/__init__.py +1 -0
- octop_memory/domain/alias.py +43 -0
- octop_memory/domain/datetime.py +23 -0
- octop_memory/domain/retention.py +50 -0
- octop_memory/operations/__init__.py +1 -0
- octop_memory/operations/migration/__init__.py +45 -0
- octop_memory/operations/migration/backfill.py +282 -0
- octop_memory/operations/migration/export.py +305 -0
- octop_memory/operations/migration/import_.py +384 -0
- octop_memory/operations/migration/portable/__init__.py +84 -0
- octop_memory/operations/migration/portable/adopter.py +469 -0
- octop_memory/operations/migration/portable/doctor.py +377 -0
- octop_memory/operations/migration/portable/models.py +253 -0
- octop_memory/operations/migration/portable/packer.py +264 -0
- octop_memory/operations/migration/portable/sources.py +246 -0
- octop_memory/operations/migration/preview.py +95 -0
- octop_memory/operations/migration/rename.py +420 -0
- octop_memory/operations/retention.py +507 -0
- octop_memory/pipeline/__init__.py +1 -0
- octop_memory/pipeline/episode/__init__.py +375 -0
- octop_memory/pipeline/episode/digest.py +496 -0
- octop_memory/pipeline/episode/prompts.py +157 -0
- octop_memory/pipeline/extractor/__init__.py +365 -0
- octop_memory/pipeline/extractor/parser.py +394 -0
- octop_memory/pipeline/extractor/prompts.py +471 -0
- octop_memory/pipeline/lifecycle/__init__.py +83 -0
- octop_memory/pipeline/lifecycle/checkpoint_gc.py +629 -0
- octop_memory/pipeline/lifecycle/consolidate.py +368 -0
- octop_memory/pipeline/lifecycle/gc.py +368 -0
- octop_memory/pipeline/lifecycle/maintenance.py +339 -0
- octop_memory/pipeline/lifecycle/vacuum.py +679 -0
- octop_memory/pipeline/page/__init__.py +54 -0
- octop_memory/pipeline/page/headline.py +58 -0
- octop_memory/pipeline/page/prompts.py +110 -0
- octop_memory/pipeline/page/regenerator.py +422 -0
- octop_memory/pipeline/page/trigger.py +73 -0
- octop_memory/pipeline/page/user_notes.py +105 -0
- octop_memory/pipeline/promotion/__init__.py +638 -0
- octop_memory/pipeline/promotion/checks.py +715 -0
- octop_memory/pipeline/promotion/fallback.py +294 -0
- octop_memory/pipeline/promotion/llm_hook.py +265 -0
- octop_memory/pipeline/recall/__init__.py +584 -0
- octop_memory/pipeline/recall/budget.py +164 -0
- octop_memory/pipeline/recall/cache.py +100 -0
- octop_memory/pipeline/recall/diversify.py +67 -0
- octop_memory/pipeline/recall/multi_source.py +489 -0
- octop_memory/pipeline/recall/parser.py +273 -0
- octop_memory/pipeline/recall/rerank.py +298 -0
- octop_memory/pipeline/recall/router.py +118 -0
- octop_memory/pipeline/recall/suppress.py +142 -0
- octop_memory/pipeline/recall/thread_state.py +148 -0
- octop_memory/pipeline/recall/timeout.py +123 -0
- octop_memory/ports/__init__.py +1 -0
- octop_memory/ports/llm/__init__.py +49 -0
- octop_memory/ports/llm/_protocol.py +114 -0
- octop_memory/ports/llm/mock.py +115 -0
- octop_memory/ports/llm/openai_compat.py +217 -0
- octop_memory/service.py +334 -0
- octop_memory/storage/__init__.py +1 -0
- octop_memory/storage/backends/__init__.py +623 -0
- octop_memory/storage/backends/forget.py +279 -0
- octop_memory/storage/backends/fts_text.py +91 -0
- octop_memory/storage/backends/postgres.py +2477 -0
- octop_memory/storage/backends/postgres_pool.py +140 -0
- octop_memory/storage/backends/sqlite.py +2491 -0
- octop_memory/storage/backends/sqlite_checkpoint.py +219 -0
- octop_memory/storage/backends/sqlite_checkpoint_job.py +114 -0
- octop_memory/storage/backends/sqlite_checkpoint_live.py +88 -0
- octop_memory/storage/backends/sqlite_checkpoint_maintenance.py +267 -0
- octop_memory/storage/driver_errors.py +64 -0
- octop_memory/storage/vector/__init__.py +104 -0
- octop_memory/storage/vector/chroma.py +165 -0
- octop_memory/storage/vector/embeddings.py +262 -0
- octop_memory/storage/vector/qdrant.py +196 -0
- 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&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&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,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.
|
octop_memory/__init__.py
ADDED
|
@@ -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."""
|