Engram

   ███████╗███╗   ██╗ ██████╗ ██████╗  █████╗ ███╗   ███╗
   ██╔════╝████╗  ██║██╔════╝ ██╔══██╗██╔══██╗████╗ ████║
   █████╗  ██╔██╗ ██║██║  ███╗██████╔╝███████║██╔████╔██║
   ██╔══╝  ██║╚██╗██║██║   ██║██╔══██╗██╔══██║██║╚██╔╝██║
   ███████╗██║ ╚████║╚██████╔╝██║  ██║██║  ██║██║ ╚═╝ ██║
   ╚══════╝╚═╝  ╚═══╝ ╚═════╝ ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝

           hybrid long-term memory for OpenClaw agents

engram (n.) — the physical/biochemical trace a memory leaves behind. The thing that makes "remembering" actually possible.

Engram is a memory plugin for OpenClaw agents. It gives them a brain that doesn't forget between sessions — backed by SQLite + FTS5 for exact, structured recall and LanceDB for fuzzy semantic search over embeddings.

✨ Features

• 🧠 Hybrid recall — structured key/value facts + semantic vector search, queried together
• 🔍 FTS5 full-text search over fact text
• 📚 Categories — preference, fact, decision, entity, other
• ⏳ Decay classes — permanent, stable, active, session, checkpoint (with confidence decay)
• 🪝 Auto-capture / auto-recall hooks (configurable)
• 💾 Local-first — your memory stays on your machine
• 🔒 Embeddings via OpenAI (text-embedding-3-small or -large)

🚀 Install

One-liner (clones from this repo, copies the plugin into OpenClaw, wires the config):

curl -fsSL https://raw.githubusercontent.com/NanoFlow-io/engram/main/scripts/install.sh | bash

Or clone and run manually:

git clone https://github.com/NanoFlow-io/engram.git
cd engram
bash scripts/install.sh

After install:

export OPENAI_API_KEY="sk-proj-..."   # if not already set
openclaw gateway restart

Verify it loaded — look for engram: initialized in the gateway log.

🧪 Try It

From inside an OpenClaw agent session:

> Remember that I prefer dark mode and my coffee black.

Next session:

> What do you remember about me?

The agent recalls via the memory_recall / memory_store tools, both backed by Engram.

⚙️ Configuration

Engram is configured under plugins.entries.engram in ~/.openclaw/openclaw.json:

{
  "plugins": {
    "slots": { "memory": "engram" },
    "entries": {
      "engram": {
        "enabled": true,
        "hooks": { "allowConversationAccess": true },
        "config": {
          "embedding": {
            "apiKey": "${OPENAI_API_KEY}",
            "model": "text-embedding-3-small"
          },
          "autoCapture": true,
          "autoRecall": false,
          "sqlitePath": "~/.openclaw/memory/facts.db",
          "lanceDbPath": "~/.openclaw/memory/lancedb"
        }
      }
    }
  }
}

Field	Default	Notes
embedding.apiKey	—	required (use ${OPENAI_API_KEY})
embedding.model	text-embedding-3-small	or text-embedding-3-large
autoCapture	true	extract memories from conversations
autoRecall	false	inject relevant memories into context. Off by default — can be noisy.
sqlitePath	~/.openclaw/memory/facts.db	structured store
lanceDbPath	~/.openclaw/memory/lancedb	vector store

🛠 CLI

Engram registers a engram CLI command with subcommands:

openclaw engram stats          # show fact/vector counts
openclaw engram prune          # remove expired memories
openclaw engram checkpoint     # manual checkpoint
openclaw engram backfill-decay # backfill decay classes on legacy data
openclaw engram extract-daily  # extract from daily notes
openclaw engram search <q>     # hybrid search
openclaw engram lookup <key>   # exact lookup

Verify after install:

openclaw plugins doctor
openclaw plugins inspect engram --runtime

🧱 Architecture

                    ┌─────────────────────┐
                    │   OpenClaw Agent    │
                    └──────────┬──────────┘
                               │
                ┌──────────────┴──────────────┐
                │       Engram Plugin         │
                └──────┬───────────────┬──────┘
                       │               │
            ┌──────────▼─────┐  ┌─────▼─────────┐
            │  SQLite + FTS5 │  │   LanceDB     │
            │  structured    │  │   vectors     │
            │  facts, keys,  │  │   semantic    │
            │  categories    │  │   recall      │
            └────────────────┘  └───────────────┘
                       ▲               ▲
                       └──────┬────────┘
                              │
                       ┌──────▼──────┐
                       │  OpenAI     │
                       │ embeddings  │
                       └─────────────┘

Every memory gets written to both stores. Recall queries hit both and merge results by relevance.

🗑 Uninstall

bash scripts/uninstall.sh

Asks before wiping memory data.

🤝 Contributing

PRs welcome. Open an issue if you want to discuss architecture changes first.

📜 License

MIT © NanoFlow

---

   ░░░ remember everything. forget nothing. ░░░