Skip to content

getting-started.md

Latest commit

 

History

History
254 lines (187 loc) · 9.2 KB

getting-started.md

File metadata and controls

254 lines (187 loc) · 9.2 KB
Raw

Getting Started

Prerequisites

  • OpenClaw gateway running
  • OpenAI API key (for extraction; retrieval-only mode works without one)
  • QMD installed (recommended)

Installation

Option A: npm (recommended)

openclaw plugins install clawhub:@remnic/plugin-openclaw

Option B: Developer install (from Git)

git clone https://github.com/joshuaswarren/remnic.git \
  ~/.openclaw/extensions/remnic
cd ~/.openclaw/extensions/remnic
pnpm install && pnpm run build

Option C: Standalone (no OpenClaw)

Use Remnic as a standalone memory system without OpenClaw. Requires Node.js 22.12+ and tsx (npm install -g tsx).

Build from source and use the standalone CLI:

npm install -g tsx               # Required — CLI entry point is TypeScript
git clone https://github.com/joshuaswarren/remnic.git
cd remnic && pnpm install && pnpm run build
cd packages/remnic-cli && npm link # Makes `remnic` available on PATH
cd ../..
remnic init                      # Create config in current directory
export OPENAI_API_KEY=sk-...
export REMNIC_AUTH_TOKEN=$(openssl rand -hex 32)
remnic daemon start              # Start background server (requires source build)
remnic status                    # Verify it's running
remnic query "hello" --explain   # Test with tier breakdown

Note: The canonical CLI is remnic. The legacy engram binary remains as a forwarder during the rename window. Running npm link from packages/remnic-cli/ (not the repo root) makes the CLI globally available — the root package only exposes engram-access. Alternatively, invoke directly: npx tsx packages/remnic-cli/src/index.ts <command>.

Standalone mode provides 15+ CLI commands for querying, onboarding projects, curating files, managing spaces, running benchmarks, and more. See the Platform Migration Guide for standalone adoption details.

OpenClaw remains the recommended installation path for most users.

Minimal Config

Add to openclaw.json under plugins.entries.openclaw-engram.config:

{
  "openaiApiKey": "${OPENAI_API_KEY}",
  "recallBudgetChars": 64000
}

Important: The recallBudgetChars setting controls how much memory context is injected into agent prompts. The default (8,000 chars) is too small for most deployments — profile and shared context alone can exhaust it, leaving no room for actual memories. Set it to 64,000 for large-context models (Claude, GPT-5) or 32,000 for smaller models. See Recall Budget Tuning.

All other settings have sensible defaults. Config changes require a full gateway restart (hot reload via SIGUSR1 does not fire gateway_start):

launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway

Verify startup:

grep '\[engram\]' ~/.openclaw/logs/gateway.log | tail -5
# Should see the memory service start line (the log prefix remains [engram] during v1.x)

Set Up QMD (Recommended)

QMD provides hybrid BM25 + vector + reranking search. Without it, Remnic falls back to semantic embedding search (using your OpenAI key when available) and then recency-ordered file reads.

QMD 2.5.3 is the current supported target. QMD 1.x still works, but 2.0+ resolves several known issues natively (session ID crash, model override env vars, join performance), 2.5.0 adds runtime diagnostics, structured MCP searches, safer indexing, model/GPU env controls, and absolute snippet line numbers, and 2.5.3 adds the preferred --format selector plus line-range, docid-header, full-path, launcher, and Metal-teardown fixes. Remnic detects the installed QMD version and only uses newer flags when available. Install via npm or bun:

npm install -g @tobilu/qmd@2.5.3
# or: bun install -g @tobilu/qmd@2.5.3

# Verify
qmd --version  # should show 2.5.3

Add to ~/.config/qmd/index.yml:

openclaw-engram:
  path: ~/.openclaw/workspace/memory/local
  extensions: [.md]

Index the collection:

qmd update && qmd embed

Enable in your plugin config:

{
  "qmdEnabled": true,
  "qmdCollection": "openclaw-engram"
}

Upgrading QMD

QMD 2.5.3 is a drop-in upgrade from older 2.x installs. Existing collections, indexes, and config files work without changes. Remnic detects the installed version at startup and enables newer features only when the installed binary supports them.

What changed:

  • QMD 2.5.3: qmd query/qmd search prefer --format json; Remnic uses that form only for 2.5.3+ and keeps legacy --json for older QMD installs.
  • QMD 2.5.3: qmd get/qmd multi-get output is line-numbered by default, includes #docid headers, accepts :from:count line ranges, and supports --full-path for direct filesystem paths. These are useful for humans and agents reading QMD directly; Remnic's search path keeps JSON output with docids for provenance and dedupe.
  • QMD 2.5.2/2.5.3: global launcher fixes improve Windows, pnpm-global, Node/Bun source-mode selection, and macOS Metal teardown behavior.
  • Unified search() replaces the old query/search/structuredSearch split internally
  • MCP server rewritten as a clean SDK consumer (same external contract)
  • Source reorganized into src/cli/ and src/mcp/ subdirectories
  • New programmatic SDK: import { createStore } from '@tobilu/qmd'
  • better-sqlite3 bumped to ^12.4.5 (Node 25 support)

Patches no longer needed: The following QMD 1.x patches are resolved natively in 2.0:

  • PR #166 (MCP session ID crash) — built-in sessionIdGenerator
  • PR #112 (model override env vars) — QMD_EMBED_MODEL, QMD_GENERATE_MODEL, QMD_RERANK_MODEL supported
  • PR #117 (CROSS JOIN fix) — vector search uses two-step query pattern

Upgrade steps:

# 1. Install the supported QMD target
npm install -g @tobilu/qmd@2.5.3
# or: bun install -g @tobilu/qmd@2.5.3

# 2. If native bindings need repair, rebuild better-sqlite3 manually
cd ~/.bun/install/global/node_modules/better-sqlite3
npm rebuild better-sqlite3

# 3. Verify
qmd --version       # 2.5.3
qmd doctor          # available on QMD 2.5+
qmd status           # should show existing collections

# 4. Restart the gateway
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway

# 5. Verify Remnic picked up the new QMD version
grep "cliVersion" ~/.openclaw/logs/gateway.log | tail -1
# Should show: cliVersion=qmd 2.5.3

To let Remnic perform this upgrade for PATH/fallback installs, set qmdAutoUpgradeEnabled: true. Remnic will install @tobilu/qmd@qmdSupportedVersion at most once per qmdAutoUpgradeCheckIntervalMs. Explicit qmdPath installs are never auto-upgraded.

Note: If you used the OpenClaw patcher for QMD patches, those patches target QMD 1.x source paths that no longer exist in 2.0. The patcher will harmlessly skip them. You can remove old QMD patch entries from the patcher config.

Five-Minute Config

Enable the most impactful features incrementally:

{
  "openaiApiKey": "${OPENAI_API_KEY}",
  "recallBudgetChars": 64000,
  "qmdEnabled": true,
  "qmdCollection": "openclaw-engram",

  // v8.0: Recall Planner (enabled by default)
  "recallPlannerEnabled": true,

  // v8.0: Episode/Note dual store (opt-in)
  "episodeNoteModeEnabled": true,

  // v8.0: Memory Boxes (opt-in)
  "memoryBoxesEnabled": true,
  "traceWeaverEnabled": true
}

Verify It Works

Start a conversation with OpenClaw. After a few turns, check:

openclaw engram setup --json
openclaw engram config-review --json
openclaw engram doctor --json
openclaw engram inventory --json

# See extracted memories
ls ~/.openclaw/workspace/memory/local/facts/

# Search memories from CLI
openclaw engram search "your query"

Config Override (Service Environments)

Override the config file path via environment variable:

OPENCLAW_ENGRAM_CONFIG_PATH=/absolute/path/to/openclaw.json

Fallback: OPENCLAW_CONFIG_PATH.

Alternative Search Backends (v9.0)

QMD provides the highest quality retrieval, but Engram v9 supports five other backends. To use an alternative, set searchBackend in your config:

{
  "searchBackend": "orama"   // or "lancedb", "meilisearch", "remote", "noop"
}

Orama requires zero setup — no external server, no native dependencies. Just set the config and restart.

See Search Backends for a full comparison and configuration guide.

Next Steps