Octop Memroy

Persistent, portable memory for LLM agents. Store facts, capture conversations, and retrieve relevant context through a shared Python runtime or host adapters.

中文 · Developer guide · Integrations · MIT License

Project scope

Octop Memory provides cross-session memory for personal assistants, ongoing project work, and existing agents. It is the memory component in the Octop ecosystem and can also run independently as a Python library, CLI, or JSON-RPC bridge, without installing Octop. This repository owns memory capture, extraction, retrieval, storage, and migration; the host application manages agent execution, tool scheduling, and user interfaces.

What it provides

• Long-term memory: extract candidates from raw events, then promote, merge, or review them into facts (AtomCard). Entity pages consolidate facts, episodes describe events, and the tree provides a hierarchical view.
• Recall: full-text search, optional vector search, ranking, deduplication, and a token budget for prompt context.
• Two storage backends: SQLite + FTS5 by default, PostgreSQL for server deployments. Chroma and Qdrant are optional vector indexes alongside either backend.
• External agent adapters: MemoryService for Python hosts and a JSON-RPC bridge for cross-language/subprocess hosts. Host adapters live in plugins/, currently including OpenClaw and Hermes.
• Portability: export/import and .hmpkg packages for moving memory between supported hosts.
• Optional LangGraph checkpoints: conversation recovery state alongside long-term memory.

The core requires Python 3.12+, aligned with Octop’s Python 3.12 baseline, and uses only the standard library, including sqlite3 with FTS5. Manual storage and lexical recall need no model. Automated extraction, promotion checks, and page regeneration can use an injected LLMClient; installing the package alone does not configure a model.

Quick start

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[chroma,embeddings]"	Chroma index and local embeddings
pip install "octop-memory[qdrant,embeddings]"	Qdrant index and local embeddings
pip install "octop-memory[langgraph]"	SQLite LangGraph checkpointer
pip install "octop-memory[langgraph-postgres]"	PostgreSQL LangGraph checkpointer

Vector search requires constructing and injecting vector_index and embedding_provider into Memory; an extra installs dependencies only. The database backend remains sqlite or postgres.

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

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

Code architecture

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.

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.

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.