memento

# Memento — Local Persistent Memory for OpenClaw Agents

Memento gives your agents long-term memory. It captures conversations, extracts structured facts using an LLM, and auto-injects relevant knowledge before each AI turn.

**All stored data stays on your machine — no cloud sync, no subscriptions.** Extraction uses your configured LLM provider; use a local model (Ollama) for fully air-gapped operation.

> ⚠️ **Privacy note:** When `autoExtract` is enabled, conversation segments are sent to your configured LLM provider for fact extraction. If you use a cloud provider (Anthropic, OpenAI, Mistral), that text leaves your machine. For fully local operation, set `extractionModel` to `ollama/<model>` and keep Ollama running locally.

## What It Does

1. **Captures** every conversation turn, buffered per session
2. **Extracts** structured facts (preferences, decisions, people, action items) via configurable LLM (opt-in — see Privacy section)
3. **Recalls** relevant facts before each AI turn using FTS5 keyword search + optional semantic embeddings (BGE-M3)
4. **Respects privacy** — facts are classified as `shared`, `private`, or `secret` based on content, with hard overrides for sensitive categories (medical, financial, credentials)
5. **Cross-agent knowledge** — shared facts flow between agents with provenance tags; private/secret facts never cross boundaries

## Quick Start

Install the plugin, restart your gateway, and Memento starts capturing automatically. Extraction is **off by default** — enable it explicitly when ready.

### Optional: Semantic Search

Download a local embedding model for richer recall:

```bash
mkdir -p ~/.node-llama-cpp/models
curl -L -o ~/.node-llama-cpp/models/bge-m3-Q8_0.gguf \
  "https://huggingface.co/gpustack/bge-m3-GGUF/resolve/main/bge-m3-Q8_0.gguf"
```

## Environment Variables

All environment variables are **optional** — you only need the one matching your chosen LLM provider:

| Variable | When Needed |
|----------|-------------|
| `AN...

# Memento — Local Persistent Memory for OpenClaw Agents

**Memento** gives OpenClaw agents a long-term memory — structured, private, and stored entirely on your machine. All stored data stays local — no cloud sync, no subscriptions. Extraction uses your configured LLM provider; use a local model (Ollama) for fully air-gapped operation.

> ⚠️ **Privacy note:** When `autoExtract` is enabled, conversation segments are sent to your configured LLM provider for fact extraction. Memento uses OpenClaw's built-in model routing — it inherits whichever model you have configured for your agent (including fallbacks). If you use a cloud provider (Anthropic, OpenAI, Mistral), that text leaves your machine. For fully local operation, configure your OpenClaw agent to use Ollama.

---

## Features

- **📥 Capture** — buffers every conversation turn per session, auto-flushes on pause or session end
- **🧠 Extraction** — asynchronously extracts structured facts (preferences, decisions, people, etc.) using the configured LLM; **history-agnostic** — existing facts are NOT passed to the LLM (Phase 1)
- **🔍 Recall** — injects relevant facts before each AI turn via FTS5 keyword search + optional semantic embedding search
- **🔒 Privacy-first** — facts are classified by visibility (`shared` / `private` / `secret`); secret facts never leave your machine or cross agent boundaries
- **🌐 Cross-agent KB** — shared facts from multiple agents are surfaced with provenance tags in recall
- **📊 Temporal intelligence** — recency, frequency, and category weights govern recall ranking; `previous_value` shown when a fact has changed
- **🔗 Knowledge graph** — typed weighted relations between facts (`related_to`, `elaborates`, `contradicts`, `supports`, `caused_by`, `part_of`, `precondition_of`) with 1-hop graph traversal during recall; causal edges get a **1.5× score boost**; Phase 3 background sweep auto-builds relations from embedding similarity
- **🔮 Query planning** — optional LLM pre-pass before...