Overview
Memok gives your OpenClaw assistant durable memory: it can store salient facts from chats, recall them in later turns, and optionally run scheduled maintenance passes (sometimes described as dreaming or predream in the upstream docs). You install an OpenClaw extension (the Memok plugin); the heavy lifting uses the memok-ai engine and a local SQLite database on your machine.
This page focuses on install, verification, and safe operation. Algorithm details stay in the open-source repositories linked at the end.
For the memok-ai npm library (memok-ai/bridge APIs, MemokPipelineConfig, SQLite semantics, and integration patterns without OpenClaw), see this site’s core doc: /docs/memok-ai.
Terms and components
- Memok — the product capability: long-lived, recallable memory for assistants.
- OpenClaw — the gateway/runtime that hosts plugins and connects models to your tools.
- memok-ai — the core npm library (pipelines, SQLite, bridge APIs). The plugin depends on it; you rarely interact with it directly unless you develop on the core.
- Memok OpenClaw plugin — the extension you install from the memok-ai-openclaw repository (GitHub or Gitee mirror). Clone this repo when installing from source, not the core-only repo.
- TOML — a small config file format. Memok pipeline settings live in config.toml under the extension directory; keys match MemokPipelineConfig (see the example file below).
- Dreaming / predream — scheduled background passes that tidy or merge stored memories; optional and configured in the wizard or config.
System requirements
Meet all required items before installing. Missing any one item usually produces confusing errors.
| Item | Requirement | How to check |
|---|---|---|
| Node.js | Version 20 or newer (LTS recommended). | Run: node -v |
| npm | Available on PATH. | Run: npm -v |
| OpenClaw gateway | Compatible with this plugin: gateway and plugin API 2026.3.24 or newer (see openclaw.compat in the plugin package.json on GitHub). | Run: openclaw --version (or your distro’s equivalent). |
| One-line installers | git, node, npm, and openclaw available in the same shell you paste the script into. | Run: which git && which npm && which openclaw |
Tip
Disk: leave at least a few gigabytes free for dependencies and the SQLite file. Network: first install downloads packages; use the Chinese doc page if GitHub or npm is slow from your region.
Where configuration lives (before install)
You do not need to hand-write config before the first install. After the plugin is registered, you run openclaw memok setup; it writes Memok pipeline settings to a file such as ~/.openclaw/extensions/memok-ai/config.toml. The gateway may merge additional keys from ~/.openclaw/openclaw.json—see upstream docs for precedence.
The upstream repository publishes a commented example of every key (no real secrets): https://github.com/galaxy8691/memok-ai-openclaw/blob/main/config.toml.example
The full key-by-key table on this page sits under “Configuration reference (config.toml)” after the wizard section, once you know why each group exists.
Quick start (one-line install)
Warning
First run often takes several minutes: downloading dependencies and compiling native modules (for example better-sqlite3). A quiet terminal is usually still working, not frozen.
Tip
If you work from mainland China, open the Chinese version of this doc page first: its one-liner pulls the installer from Gitee and uses a domestic-friendly npm mirror by default.
Pick one command for your OS, paste it into a terminal, and wait until the script finishes.
Linux or macOS (GitHub script)
bash <(curl -fsSL https://raw.githubusercontent.com/galaxy8691/memok-ai-openclaw/main/scripts/install-linux-macos.sh)Windows (PowerShell, GitHub script)
irm https://raw.githubusercontent.com/galaxy8691/memok-ai-openclaw/main/scripts/install-windows.ps1 | iexTypical script flow: fetch sources as needed, npm install and build, openclaw plugins install, run openclaw memok setup, then attempt a gateway restart so new settings load.
Verify installation
After the script completes, confirm the plugin is registered and that Memok’s config file exists.
- List plugins and look for a Memok-related entry: openclaw plugins list
- Confirm the extension folder exists, for example: ls ~/.openclaw/extensions/memok-ai (paths can differ slightly by install id).
- Confirm the pipeline config was written: test -f ~/.openclaw/extensions/memok-ai/config.toml (on Windows, use PowerShell Test-Path with the same path shape).
- Restart the gateway if you changed anything manually: openclaw gateway restart
Note
Exact plugin id strings follow openclaw.plugin.json in the repo; if list output differs from examples here, trust the list command and the files on disk.
Manual installation
Use this path when corporate policy blocks curl-to-bash, or you want reproducible steps in an internal runbook.
- Clone the plugin repository (not the core-only repo).
- In the repo root: npm install, then npm run build.
- Still in the repo root: openclaw plugins install .
- Run: openclaw memok setup and answer prompts.
Example (GitHub)
git clone https://github.com/galaxy8691/memok-ai-openclaw.git
cd memok-ai-openclaw
npm install && npm run build
openclaw plugins install .
openclaw memok setupGitee clone URL for the same steps: https://gitee.com/wik20/memok-ai-openclaw.git
Expected signals: npm install ends without errors; npm run build emits compiled output; openclaw plugins install prints success; the setup wizard starts and finishes with a written config.toml.
Setup wizard (openclaw memok setup)
The wizard is a short guided flow in the terminal. It collects provider URL, API key, model id, optional dream schedule, and writes MemokPipelineConfig into ~/.openclaw/extensions/memok-ai/config.toml. You normally do not edit that file by hand.
If the gateway starts but Memok appears idle, confirm config.toml exists. If you edit plugin files or JSON config, restart the gateway so the running process reloads them.
If the wizard reports plugins.allow excludes memok, edit ~/.openclaw/openclaw.json, add "memok" to plugins.allow, save, and run openclaw memok setup again.
After setup: using memory
Once enabled, Memok participates in the normal OpenClaw chat loop: candidate memories may be injected before the model replies, and flows exist to reinforce items the model actually relied on (exact CLI names depend on your OpenClaw and plugin version—see the plugin README).
The tables below are illustrative only; real answers depend on model, sampling, and what was successfully stored.
| User question (follow-up) | Typical pattern without Memok | Typical pattern with Memok (when recall hits) |
|---|---|---|
| What did we lock for the release date last Tuesday? | Vague guess or “I don’t have earlier context.” | May restate the agreed date if that conversation was persisted and retrieved. |
| Paste the error we saw when running the deploy script. | You must paste the log again. | May surface the remembered error text or related notes if they were saved earlier. |
| Which auth header did we standardize on for service B? | Risk of contradicting an earlier decision. | May align with stored decision text if recall ranks it highly. |
Good practice: after a long planning thread, ask one or two “memory check” questions the next day. If answers ignore prior decisions, verify config.toml, model quality, and whether the gateway was restarted after edits.
Note
Wizard screenshots are not hosted on this static page; use the plugin repository README for UI visuals.
Choosing a model
Memok calls your provider through an OpenAI-compatible HTTP API. Match base URL and model id to the provider’s documentation. There is no universal best model: balance quality, latency, and cost.
- Start with a small, inexpensive model; upgrade only if recall or maintenance passes feel weak.
- Validate on a few real threads: are recalled facts actually used, or does the model hallucinate citations?
- If latency or cost rises, reduce model size or frequency of heavy background jobs.
Deeper technical background: https://github.com/galaxy8691/memok-ai
Capacity, limits, and expectations
Memok does not publish a fixed SLA on this marketing site. Treat the following as orientation, not benchmarks; measure on your own hardware and workload.
| Topic | Practical notes |
|---|---|
| SQLite file growth | The database grows as conversations and maintenance jobs run. Plan disk headroom; back up memok.sqlite before major upgrades (copy file while the gateway is stopped if your ops policy requires quiescence). |
| Latency | Each memory-related step is usually dominated by LLM round-trips and local SQLite I/O. Heavy models or large DBs increase wall time; upstream READMEs sometimes cite informal ranges—validate with your traces. |
| Token budgets | articleSentencesMaxOutputTokens and related caps in config.toml bound how much text a single stage may emit. Raising them increases cost and failure surface; lower them if you hit timeouts. |
| Dreaming / scheduled passes | Optional background work can add periodic API usage. If bills spike, widen the schedule interval or use a smaller model for maintenance-only passes. |
Advanced usage
For operators who already completed the wizard and need finer control than the prompts offer.
- Stop or restart the gateway before hand-editing config.toml so you do not race the running process.
- Keep a dated backup of ~/.openclaw/extensions/memok-ai/config.toml and the SQLite path referenced by dbPath.
- After edits, restart the gateway and run a short chat regression (recall + one dream window if enabled).
- To tune dreaming aggressiveness, adjust schedule in the wizard first; only then touch optional numeric thresholds in config.toml using the upstream example as reference.
- For multi-host or HA deployments, treat this plugin as a single-node memory store unless your team has an explicit replication design—default behavior is local SQLite.
Core pipeline semantics and extension hooks: https://github.com/galaxy8691/memok-ai and plugin issues https://github.com/galaxy8691/memok-ai-openclaw.
Configuration reference (config.toml)
Keys below map to MemokPipelineConfig as shown in the upstream example. Required vs optional follows that file; defaults may change between releases.
Annotated source of truth: https://github.com/galaxy8691/memok-ai-openclaw/blob/main/config.toml.example
| Key | Required | Meaning |
|---|---|---|
| dbPath | Yes | SQLite database path (wizard default under the memok-ai extension folder). |
| openaiApiKey | Yes | API key for the configured provider. |
| llmModel | Yes | Model id your provider expects (template example: gpt-4o-mini). |
| llmMaxWorkers | Usually set | Parallel LLM workers; 1 means serial stages. |
| articleSentencesMaxOutputTokens | Usually set | Output token cap for article-sentences stage. |
| coreWordsNormalizeMaxOutputTokens | Usually set | Output token cap for core-word normalization. |
| sentenceMergeMaxCompletionTokens | Usually set | Completion token cap for sentence merge. |
| openaiBaseUrl | No | Custom API base (Zhipu, DeepSeek, self-hosted); omit for SDK default. |
| skipLlmStructuredParse | No | Optional boolean to skip some structured parsing. |
| articleWordImportInitialWeight | No | Optional initial weight for imported sentences. |
| articleWordImportInitialDuration | No | Optional initial duration in days. |
| dreamShortTermToLongTermWeightThreshold | No | Predream short→long-term weight threshold (core default 7 if omitted). |
Troubleshooting
| Symptom | What to try |
|---|---|
| Setup or install prints “permission denied” | Re-run in a shell with rights to your home directory; avoid sudo for npm unless your org standard requires it—fix ownership of ~/.npm instead if possible. |
| openclaw plugins install hangs after success (Linux) | Check plugin issue tracker; some environments need a non-interactive TTY—upstream scripts may document workarounds. |
| Gateway runs but Memok never responds | Verify ~/.openclaw/extensions/memok-ai/config.toml exists; run openclaw memok setup again; restart gateway. |
| Wizard mentions plugins.allow | Add memok to plugins.allow in ~/.openclaw/openclaw.json, save, rerun openclaw memok setup. |
| Model errors (401, 404 model) | Re-check openaiBaseUrl and llmModel against provider docs; rotate keys if needed. |
| SQLite “database is locked” or similar | Ensure only one gateway process writes the DB; stop duplicate gateways; retry after a clean restart. |
| Recall always empty | Confirm conversations actually ran through the plugin path; verify API key and model can complete pipeline stages; inspect upstream logging guidance. |
| Upgraded OpenClaw and Memok broke | Re-run openclaw memok setup after reading the plugin release notes; reinstall the plugin directory if the compat matrix changed. |
Structured triage when “nothing works” after install:
- openclaw plugins list — confirm the Memok extension is listed.
- test -f ~/.openclaw/extensions/memok-ai/config.toml — confirm wizard output exists.
- openclaw gateway restart — reload JSON and TOML changes.
- Re-ask a simple fact you told the bot in the prior session; if still blank, collect gateway logs and open an issue with versions attached.
Logs and advanced diagnostics: see README and issues in https://github.com/galaxy8691/memok-ai-openclaw.
Source repositories
- OpenClaw plugin (GitHub): https://github.com/galaxy8691/memok-ai-openclaw
- OpenClaw plugin (Gitee mirror): https://gitee.com/wik20/memok-ai-openclaw
- Memok core (GitHub): https://github.com/galaxy8691/memok-ai
- Memok core (Gitee mirror): https://gitee.com/wik20/memok-ai