octop-memory

Octop Memory is a persistent, portable memory system for LLM agents. Give a personal assistant lasting preferences, keep decisions and project context available across conversations, or move accumulated memory between supported hosts. Start locally with SQLite, then add PostgreSQL or model-assisted extraction as needed.

It powers memory in the Octop ecosystem and also works independently as a Python library, CLI, or JSON-RPC bridge. OpenClaw and Hermes adapters connect their host hooks and tools to the same memory runtime. Your host manages agent execution and model scheduling; Octop Memory handles capture, extraction, recall, storage, and migration.

Memory worth keeping. Context worth bringing along. Save it, recall it, and carry it between supported agents.

✨ Highlights

	What stands out	What you get
🪶	Start small, add what you need	Zero core dependencies: Python's standard library + SQLite/FTS5. Manual storage and lexical recall work without a model.
🧠	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.
🔍	Recall that fits the prompt	Full-text search, ranking, deduplication, and token budgets select context for the current query.
🧳	Bring your memory along	Export/import and portable `.hmpkg` packages move memory between supported hosts, including OpenClaw and Hermes.
🔌	Connect to your agent	Python `MemoryService`, a JSON-RPC bridge, and dedicated host plugins share the same runtime.
💾	Choose your storage	SQLite for a local start; PostgreSQL for server deployments.
🌳	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.
🔖	Resume conversations	Optional LangGraph checkpoints preserve execution state alongside long-term memory, with SQLite and PostgreSQL support.

Python 3.12+ is required. Automated extraction, promotion checks, and page regeneration use an injected LLMClient; installing the package alone does not configure a model. See the integration guide for host setup. Existing installations should read the rename migration guide before upgrading.

Quick start

pip install octop-memory

from octop_memory import Memory, MemoryService

memory = Memory(
    namespace="demo",
    backend_config={"db_path": "./demo.sqlite"},
)
memory.store("User prefers Python for backend services", topic="preferences")

# Basic fact search returns MemoryNode leaf projections.
for node in memory.recall("Python"):
    print(node.content)

# Prompt recall adds source selection, ranking, deduplication, and budgeting.
result = MemoryService(memory).recall("Python")
print(result.rendered)

This creates a local database. Use terms present in the stored text for a minimal FTS example. Memory.search() searches archived conversation messages; it is a separate API from fact recall.

Optional dependencies

Install	Purpose
`pip install "octop-memory[cli]"`	CLI and OpenClaw setup commands
`pip install "octop-memory[postgres]"`	PostgreSQL memory backend
`pip install "octop-memory[langgraph]"`	SQLite LangGraph checkpointer
`pip install "octop-memory[langgraph-postgres]"`	PostgreSQL LangGraph checkpointer

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.

memory = Memory(
    namespace="demo",
    backend="postgres",
    backend_config={"dsn": "postgresql://user:pass@localhost/octop_memory"},
)

Use deployment configuration for real credentials. SQLite isolates memory with table prefixes; PostgreSQL uses namespace-first keys in the shared octop_memory schema.

CLI

Install [cli]. Global options precede subcommands; use an explicit database and namespace when following examples.

octop-memory --db ./demo.sqlite --namespace demo memory store --content "User prefers Python"
octop-memory --db ./demo.sqlite --namespace demo recall "Python"
octop-memory --db ./demo.sqlite --namespace demo memory tree
octop-memory --help

Commands	Purpose
`raw`, `candidate`, `atom`, `entity`, `page`	Inspect and manage memory layers
`episode`, `digest`, `journal`	Event summaries and decision records
`memory`, `recall`, `thread`	Tree operations, prompt recall, thread state
`export`, `import`, `migrate`, `portable`	Backup and migration
`db`, `gc`, `consolidate`	Storage maintenance and lifecycle operations
`config`, `openclaw`, `backfill`	Configuration, integration, historical extraction

Run <command> --help for arguments. db slim FILE previews SQLite checkpoint deduplication; --apply --offline creates a backup and performs it without deleting history. Read checkpoint compatibility and maintenance before migration or reader downgrade.

The dashboard is available from a source checkout with [dashboard] dependencies; its modules are currently excluded from the wheel. Installing octop-memory[dashboard] from PyPI alone does not provide the dashboard command.

External agent adapters

plugins/<host>/ maps external agent hooks, tools, and configuration to the shared Python runtime. OpenClaw and Hermes adapters are available today. Other agents can integrate through the Python API or JSON-RPC, with an adapter implementing their host contract.

Integration	Use case	Entry point
In-process Python	Custom agents / Python applications	`MemoryService.capture_turn()` / `recall()` / `search()` / `get()` / `extract()`
JSON-RPC bridge	Cross-language or separate processes	stdio `octopmemory-bridge`
Host plugin	Agent-specific lifecycle and tool interfaces	`plugins/<host>/`; OpenClaw and Hermes currently implemented

See the integration guide for installation, configuration, profiles, troubleshooting, and adapter boundaries.

Move memory with octop-memory portable list-sources / pack / adopt / doctor. Exported .hmpkg files contain memory data; keep them out of source control.

Code architecture

src/octop_memory/
├── core.py / types.py     # Public Memory API and data structures
├── service.py            # MemoryService: Python host entry point
├── application/          # MemoryRuntime, config, host files, path projection
├── pipeline/             # Extraction, promotion, recall, pages, episodes, lifecycle
├── storage/              # SQLite / PostgreSQL, checkpoints, vector indexes
├── ports/                # External capability interfaces, including LLM clients
├── domain/               # Shared alias and time rules
├── adapters/             # JSON-RPC bridge, CLI, source-only dashboard
└── operations/           # Import/export, migration, portable packages
plugins/                  # External agent adapters, organized by host
examples/                 # Public API example
tests/ / evals/           # Behavior tests / synthetic recall evaluation
docs/agent/               # Harness project map, decisions, and handoff

Adapters call inward through application and pipeline/core/storage layers. MemoryService and Bridge share MemoryRuntime; pipeline/storage do not depend on adapters, and backend-specific SQL stays in storage. The source dashboard's direct SQLite access is an existing exception.

Host call flow

Python host → MemoryService ─────────┐
Hermes → in-process Bridge ──────────┤
OpenClaw → JSON-RPC bridge ───────────┴→ MemoryRuntime → pipelines → Memory
CLI → application / operations ────────────────────────────────────┘
                                                     ├→ SQLite / PostgreSQL
                                                     └→ optional vector index

Hermes currently calls Bridge in-process; OpenClaw uses a bridge subprocess. MemoryService.recall() also calls the recall pipeline directly. Facts live in AtomCard; tree leaves reference atoms and project their content. The tree is an organization view, not an additional copy or independent recall source.

Long-term memory flow

RawEvent ──extraction──→ Candidate ──promotion──→ AtomCard ──dirty / regeneration──→ EntityPage
    └──episode extraction──→ Episode                └──atom_id reference──→ tree leaf

Candidates do not all require human approval. Promotion checks value, evidence, entity resolution, duplicates, and conflicts; it can promote, merge, or drop candidates automatically, leaving review/conflict cases for user action. Pages are marked dirty and regenerated when triggered by runtime/CLI/host, rather than immediately after every write. Episode extraction is a parallel path from raw events. Manual Memory.store() needs no model and directly creates RawEvent/Candidate/AtomCard plus a leaf reference.

Prompt recall routes atom and raw by default, adds page_headline when an entity is resolved, and adds vector when configured. With the default raw fallback policy, durable hits suppress raw; passing the current session/thread excludes its raw events from prompt injection.

Start with CONTRIBUTING.md; the project map covers architecture and data flow. AI contributors use AGENTS.md, with task clarification and handoff in HANDOFF.md.

Development

make install          # uv sync --group dev
make install-hooks    # required once per clone
make all              # format + lint + strict mypy + tests
uv build              # Python wheel + source distribution

Run PostgreSQL behavior tests against a real test server with TEST_POSTGRES_DSN; skipped PG cases do not prove compatibility. OpenClaw has its own npm ci, npm test, and npm run build under plugins/openclaw/octopmemory/.

The repository retains tests, CI, examples, and plugins; the Python sdist contains the sources needed to rebuild the wheel. Development and release procedures live in CONTRIBUTING.md.

License

MIT. Report vulnerabilities through the channels in SECURITY.md.