Skill: apptah/openclaw-memory-stack (version 0.6.1)

--- name: openclaw-memory-stack description: "Total recall, 90% fewer tokens. Open source OpenClaw memory plugin — 5-engine local search, structured fact extraction, smart dedup, cross-agent sharing, and self-healing. Replace native memory with something that actually remembers. No cloud API, no subscription, MIT licensed and free." version: "0.6.1" license: mit metadata: openclaw: requires: bins: - bash - python3 - sqlite3 anyBins: - bun - qmd emoji: "\U0001F9E0" homepage: https://github.com/Apptah/openclaw-memory-stack tags: - memory - search - rag - vector-search - code-search - knowledge-management - fact-extraction - entity-tracking - token-savings - long-term-memory - context-window - recall - local - offline - dedup - persistence pricing: model: free amount: 0 currency: usd url: https://github.com/Apptah/openclaw-memory-stack note: "Free and open source under MIT license. No activation, no cloud dependency." network: - host: openclaw-api.apptah.com purpose: "Update check on manual upgrade. Sends only current_version." - host: localhost:8080 purpose: "Local MLX LLM for fact extraction. Never leaves machine." - host: localhost:11434 purpose: "Local Ollama LLM for fact extraction. Never leaves machine." - host: api.openai.com purpose: "Cloud LLM fallback for fact extraction. Only active if user sets API key. User-configurable endpoint." permissions: shell: - binary: sqlite3 purpose: "Local database read/write for all 5 search engines. No arbitrary command execution." - binary: qmd purpose: "QMD CLI for vector search and collection management." fileAccess: read: ["~/.openclaw/memory-stack/", "~/.openclaw/memory/external/", ".openclaw/"] write: ["~/.openclaw/memory-stack/", "~/.openclaw/memory/"] envVars: - name: OPENCLAW_LLM_API_KEY purpose: "API key for cloud LLM fact extraction (optional)" sentTo: "user-configured llmEndpoint only" - name: OPENAI_API_KEY purpose: "Fallback API key for OpenAI (optional)" sentTo: "api.openai.com or user-configured llmEndpoint" - name: OPENCLAW_LCM_DB purpose: "Override lossless DB path (local only)" - name: OPENCLAW_ROUTER_CONFIG purpose: "Override router config path (local only)" - name: OPENCLAW_BACKENDS_JSON purpose: "Override backends config path (local only)" dataFlow: localOnly: "All search/storage (5 engines, sqlite3, markdown) runs on-device. Shell execution targets only local databases." remote: "LLM extraction sends conversation excerpts to user-configured endpoint only. No license verification, no activation keys." neverTransmitted: "Raw memory content never sent to apptah.com. No telemetry or analytics." --- # OpenClaw Memory Stack **Total recall. 90% fewer tokens.** Your agent forgets past decisions and burns tokens re-reading the same context. Memory Stack runs 5 search engines locally, returns only what matters, and never loses a fact. > **Free and open source. MIT license.** No subscription, no cloud API costs. > All search and storage runs entirely on your machine. > GitHub: [github.com/Apptah/openclaw-memory-stack](https://github.com/Apptah/openclaw-memory-stack) ## Architecture ``` ┌──────────────────────────────────────────────────────────────┐ │ OPENCLAW MEMORY STACK │ ├──────────────────────────────────────────────────────────────┤ │ │ │ SEARCH PIPELINE (runs on every conversation turn) │ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │ E1 │ │ E2 │ │ E3 │ │ E4 │ │ E5 │ │ │ │ Full │ │Vector│ │ DAG │ │ Fact │ │ MD │ │ │ │ Text │ │Search│ │Compr.│ │Store │ │Files │ │ │ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ │ │ └────────┴────────┴────────┴────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────┐ │ │ │ Result Fusion│ │ │ │ + Reranking │ │ │ └──────────────┘ │ │ │ │ │ ┌─────────┼─────────┐ │ │ ▼ ▼ ▼ │ │ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │ L0 │ │ L1 │ │ L2 │ Token Budget │ │ │~100t │ │~800t │ │ full │ Control │ │ └──────┘ └──────┘ └──────┘ │ │ │ │ CAPTURE (runs after every conversation turn) │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Fact │ │ Entity │ │ Dedup & │ │ │ │ Extraction │ │ Tracking │ │ Supersede │ │ │ │ (8 types) │ │ (queryable) │ │ (3-level) │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ CROSS-AGENT SHARING │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ CLI API │ │ Drop Zone │ │ Unified │ │ │ │ query/add/ │ │ ~/.openclaw │ │ Global │ │ │ │ recent │ │ /external/ │ │ Memory │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ ▲ ▲ ▲ │ │ Claude Code Cursor / Windsurf Any MCP client │ │ │ │ SELF-HEALING MAINTENANCE (24h cycle, zero config) │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Auto-Init │ │ Graceful │ │ Health │ │ │ │ workspace │ │ Fallback │ │ Monitor │ │ │ │ + indexing │ │ FTS5-only │ │ + alerting │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ └──────────────────────────────────────────────────────────────┘ ``` ## Built-in Code Search Find function names, variable names, or any pattern across your entire memory — instantly. No extra tools needed, works offline, gets faster the more you use it. ## 5-Engine Search Five engines search in parallel on every conversation turn: | Engine | What it does | |--------|-------------| | Full-text | Keyword matching with relevance ranking | | Vector | Semantic search — understands meaning, not just words | | Compressed history | Conversation DAG with drill-down | | Fact store | Structured facts — decisions, deadlines, requirements | | Markdown | Scans memory files directly | Results are merged with rank fusion, deduplicated, reranked for diversity, and scored with time decay. ## 3-Tier Token Control Every wasted token is money burned. Memory Stack eliminates the waste. | Tier | Tokens | When used | |------|--------|-----------| | L0 | ~100 | Auto-recall every turn — minimal cost | | L1 | ~800 | On-demand search summary | | L2 | full | Full content on request | **The agent generates summaries — no separate LLM service required.** When the OpenClaw agent stores or surfaces a memory, it should also produce L0/L1 summaries from its own context (it is already an LLM) and persist them via: ```bash openclaw-memory tier set <file> \ --l0 "<one-sentence abstract, ≤100 tokens>" \ --l1 "<focused overview, ≤800 tokens, covers what + why + when to use>" ``` Read back at any tier: ```bash openclaw-memory tier show <file> --level L0 # or L1, L2 ``` For unattended/offline contexts where no agent is available, fall back to a pure heuristic (first non-empty line for L0, char-bounded prefix for L1): ```bash openclaw-memory tier auto <file> ``` ## Structured Fact Memory Extracts 8 fact types automatically: decisions, deadlines, requirements, entities, preferences, workflows, relationships, corrections. - Structured key/value storage with confidence scores - Negation-aware — "We will NOT use MongoDB" preserved correctly - Automatic supersede — when a fact changes, old version archived, new one takes over ## Smart Dedup & Conflict Resolution - 3-level write-time dedup: exact match, normalized text, structured key match - Full audit trail via archive table - Removes duplicates before sending — you never pay twice for the same memory ## Cross-Agent Memory Sharing Works across Claude Code, Cursor, Windsurf, and any MCP-compatible client. - CLI commands: `openclaw-memory query/add/recent` — any tool can read/write facts - Drop zone: drop `.md` files into `~/.openclaw/memory/external/` — auto-ingested, no duplicates - Unified global memory under `~/.openclaw/memory/` — your memory follows you across workspaces ## Self-Healing Maintenance Zero maintenance. The plugin takes care of itself. - Auto-init: detects workspace, creates search index, schedules embedding — no manual setup - Graceful fallback: if vector search unavailable, runs in keyword-only mode — always functional - 24h maintenance cycle: rebuilds index on corruption, archives stale facts, alerts on health issues ## OpenClaw Native vs Memory Stack | | Native | Memory Stack | |---|--------|-------------| | Search engines | 2 | 5 (parallel, fused) | | Token efficiency | Full text every time | Up to 90% fewer | | Output tiers | Full text | 3 tiers (~100 / ~800 / full) | | Fact extraction | No | 8 types, structured, negation-aware | | Duplicate handling | Can pay twice | 3-level dedup, auto-supersede | | Entity tracking | No | Yes, queryable | | Cross-agent | No | CLI + drop zone, works with any tool | | Memory across projects | Separate per workspace | Unified global memory — follows you everywhere | | Self-healing | No | Auto-maintain, auto-fallback | | Runs locally | Yes | Yes — all search runs locally, no cloud dependency | ## Memory Stack vs Other AI Memory Systems Most AI memory systems make you choose between control and convenience. Memory Stack doesn't. | | Hermes Agent | Google Always-On | Memory Stack | |---|---|---|---| | **Trigger** | Explicit tool call | Automatic (Google decides) | Deterministic router — 7 explicit rules | | **Routing logic** | Agent judgment (opaque) | Black box | Keyword pattern matching — fully inspectable | | **Fallback on poor recall** | None | Uncontrollable | Sequential chain — relevance < 0.4 → next backend | | **Storage location** | Developer-managed DB | Google cloud | Local git branch + SQLite — nothing leaves your machine | | **Token control** | None | None | 3 tiers: ~100 / ~800 / full | | **Deduplication** | Manual | Unknown | 4-level auto-dedup | | **Works offline** | Depends on DB | No | Yes — core search fully offline | | **Open source** | Varies | No | MIT — full source on GitHub | | **Setup time** | Hours | Minutes (Gemini only) | One command, any MCP client | Hermes gives developers control but no routing or fallback infrastructure. Google gives convenience but no privacy and no control. Memory Stack gives you both. ## Install ```bash npx clawhub@latest package install openclaw-memory-stack ``` Or clone and run directly: ```bash git clone https://github.com/Apptah/openclaw-memory-stack cd openclaw-memory-stack ./install.sh ``` Runs on macOS, Linux, and Windows (WSL2). Requires bash, python3, and OpenClaw 2026.3.2 or later. Bun is optional (enables QMD vector search). ## What the installer does The included `install.sh` performs the following actions: - **Files**: Copies plugin and backend files to `~/.openclaw/memory-stack/`, registers plugin in `~/.openclaw/extensions/openclaw-memory-stack/`, updates `~/.openclaw/openclaw.json` - **Upgrade downloads**: `install.sh --upgrade` downloads new versions with mandatory SHA-256 checksum verification - **No telemetry**: No usage data, memory content, or analytics are ever sent - **Optional LLM**: `OPENCLAW_LLM_API_KEY` / `OPENAI_API_KEY` env vars are optional, used only for LLM-powered fact extraction. If not set, falls back to local Ollama/MLX. These keys are sent only to the endpoint you configure (default: api.openai.com), never to our servers All search and storage runs entirely on your machine. ## License MIT. Free and open source. See [LICENSE](https://github.com/Apptah/openclaw-memory-stack/blob/main/LICENSE). ## Support Questions or issues? Open a GitHub issue at [github.com/Apptah/openclaw-memory-stack](https://github.com/Apptah/openclaw-memory-stack/issues).

path: lib/adapter-template.sh
content: #!/usr/bin/env bash
# OpenClaw Memory Stack — Adapter Template
# This is the canonical adapter implementation skeleton.
# All 8 wrappers MUST copy this parsing logic into their adapter() function.
#
# Usage in wrapper.sh:
#   source "$(dirname "$0")/../../lib/contracts.sh"
#   # (contracts.sh already sources platform.sh)
#
#   adapter() {
#     # === Canonical argument parser (copy from adapter-template.sh) ===
#     local query="" hint=""
#     while [ $# -gt 0 ]; do
#       case "$1" in
#         --hint) hint="$2"; shift 2 ;;
#         *)      query="$1"; shift ;;
#       esac
#     done
#
#     if [ -z "$query" ]; then
#       contract_error "" "BACKEND_NAME" "BACKEND_ERROR" "No query provided"
#       return 1
#     fi
#
#     local start_ms
#     start_ms=$(now_ms)
#
#     # === Backend-specific search logic here ===
#     # Use $hint to optimize:
#     #   exact   → prefer exact/BM25 search
#     #   semantic → prefer vector/semantic search
#     #   relationship → prefer graph traversal
#     #   timeline → prefer time-sorted results
#     #   decision → prefer decision/causal chain search
#     #   grep    → prefer pattern matching
#     #   ""      → use default/hybrid strategy
#
#     # ... perform search, collect results ...
#
#     local end_ms duration_ms
#     end_ms=$(now_ms)
#     duration_ms=$(( end_ms - start_ms ))
#
#     # === Build contract response ===
#     # contract_success "$query" "BACKEND_NAME" "$results_json" "$count" "$duration_ms" "$normalized_relevance"
#     # contract_empty "$query" "BACKEND_NAME" "$duration_ms"
#     # contract_error "$query" "BACKEND_NAME" "ERROR_CODE" "error message"
#   }
#
#   # === Dispatch (bottom of wrapper.sh) ===
#   case "$1" in
#     --adapter) shift; adapter "$@" ;;
#     *)         cmd_"${1//-/_}" "${@:2}" ;;
#   esac

# This file is documentation/reference only. It is NOT sourced by wrappers.
# Wrappers source lib/contracts.sh (which sources lib/platform.sh).


path: lib/license.sh
content: #!/usr/bin/env bash
# OpenClaw Memory Stack — License (open source, no restrictions)

# No-op stubs — all license checks pass unconditionally.
require_installed() { return 0; }
require_licensed()  { return 0; }


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)