{"id":50427192,"url":"https://github.com/rockywuest/openclaw-memory-local","last_synced_at":"2026-06-02T09:00:58.929Z","repository":{"id":343113832,"uuid":"1175914905","full_name":"rockywuest/openclaw-memory-local","owner":"rockywuest","description":"🧠 Local memory plugins for OpenClaw — checkpoint injection, Qdrant semantic recall, auto-capture. Your memories stay on your machine.","archived":false,"fork":false,"pushed_at":"2026-03-30T22:05:58.000Z","size":251,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-30T23:47:11.573Z","etag":null,"topics":["ai-agent","local-first","memory","openclaw","openclaw-plugin","privacy","qdrant","raspberry-pi"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rockywuest.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-08T11:05:44.000Z","updated_at":"2026-03-30T22:06:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rockywuest/openclaw-memory-local","commit_stats":null,"previous_names":["rockywuest/openclaw-memory-local"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rockywuest/openclaw-memory-local","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rockywuest%2Fopenclaw-memory-local","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rockywuest%2Fopenclaw-memory-local/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rockywuest%2Fopenclaw-memory-local/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rockywuest%2Fopenclaw-memory-local/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rockywuest","download_url":"https://codeload.github.com/rockywuest/openclaw-memory-local/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rockywuest%2Fopenclaw-memory-local/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33814312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","local-first","memory","openclaw","openclaw-plugin","privacy","qdrant","raspberry-pi"],"created_at":"2026-05-31T12:00:14.584Z","updated_at":"2026-06-02T09:00:58.916Z","avatar_url":"https://github.com/rockywuest.png","language":"JavaScript","funding_links":[],"categories":["Skills \u0026 Plugins"],"sub_categories":["Notable Skills \u0026 Plugins"],"readme":"# 🧠 openclaw-memory-local\n\n[![Tests](https://github.com/rockywuest/openclaw-memory-local/actions/workflows/test.yml/badge.svg)](https://github.com/rockywuest/openclaw-memory-local/actions/workflows/test.yml)\n[![agentskills.io](https://img.shields.io/badge/agentskills.io-compliant-brightgreen)](https://agentskills.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Your memories stay on your machine. Your agent actually learns from you.**\n\nTen OpenClaw plugins that give your agent persistent, searchable, biologically-inspired memory — with behavioral learning, ambient intelligence, cognitive adaptation, and emergency alerting. Without sending a single byte to the cloud.\n\n**New: One-line install with `nox-memory-suite`.** One plugin path, one config entry, full stack. [Quick Start →](#quick-start)\n\n\u003e Most agent memory is a glorified clipboard. Copy-paste your MEMORY.md, hope for the best. This is different: semantic search, automatic capture, behavioral adaptation, ambient awareness, and emergency escalation — all local, all open source. Core plugins (checkpoint, qdrant, auto-capture, preference-learner) running 24/7 in production since January 2026. Cognitive plugins (fademem, cooccurrence, fingerprint) are experimental — included but not yet battle-tested.\n\n## Quick Example\n\n### Before (no persistent memory)\n\n\u003e **User:** What did we discuss yesterday about the Python script?\n\u003e **Agent:** I don't have access to information from previous conversations.\n\n### After (with openclaw-memory-local)\n\n\u003e **User:** What did we discuss yesterday about the Python script?\n\u003e **Agent:** Yesterday you mentioned `analyze.py` was failing because pandas\n\u003e wasn't installed. We installed it with `pip install pandas` and verified\n\u003e the fix by running `python analyze.py --check`.\n\n_The agent retrieved this from semantic search across yesterday's\n`memory/2026-04-23.md` file (chunk indexed in Qdrant, ~150ms recall)._\n\n### How memories are captured (no manual logging needed)\n\n```text\n[User asks question] → auto-capture plugin\n                    → extracts user message\n                    → applies skip-patterns (commands, noise)\n                    → scores importance\n                    → writes to memory/YYYY-MM-DD.md\n                    → Qdrant-sync plugin embeds + indexes\n                    → memory_search() now finds it\n```\n\nYou don't write `remember this`. The plugins watch what flows through\nthe agent and persist what matters.\n\n---\n\n## Why Not Just MEMORY.md?\n\n| Approach                 | Token Cost          | Recall           | Learns Facts?   | Adapts Behavior?      | Watches for You?        |\n| ------------------------ | ------------------- | ---------------- | --------------- | --------------------- | ----------------------- |\n| Flat MEMORY.md           | 5-10K every session | ❌ Degrades      | ❌              | ❌                    | ❌                      |\n| Hierarchical files       | ~1.5K + drill-downs | 🟡 Manual        | ❌              | ❌                    | ❌                      |\n| Cloud memory (Mem0, Zep) | ~2K                 | ✅               | ✅              | ❌                    | ❌                      |\n| **This project**         | ~2K + semantic hits | ✅ Vector search | ✅ Auto-capture | ✅ Preference Learner | ✅ Ambient Intelligence |\n\nFlat files scale linearly. Vector search scales logarithmically. Nobody else adapts agent _behavior_ from conversation feedback — they only store facts. And nobody else watches for urgent events and surfaces them proactively.\n\n## Plugins\n\n| Plugin                                                      | What it does                                                                            | Layer                    |\n| ----------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------ |\n| **[auto-checkpoint](./auto-checkpoint/)**                   | Injects last operational state. Warns when stale. Backs up before compaction.           | Remember                 |\n| **[memory-qdrant](./memory-qdrant/)**                       | Semantic recall — searches Qdrant + facts.jsonl + knowledge-file routing.               | Recall                   |\n| **[auto-capture](./plugins/nox-auto-capture/)**             | Detects corrections, decisions, facts, lessons — stores them automatically.             | Learn                    |\n| **[preference-learner](./plugins/nox-preference-learner/)** | **Train by Talking.** Adapts agent behavior across 6 dimensions from your feedback.     | Adapt                    |\n| **[event-bus](./plugins/nox-event-bus/)**                   | Central event bus + sensor connectors (file, system). JSONL persistence.                | Sense                    |\n| **[preconscious](./plugins/nox-preconscious/)**             | Scores events by importance × recency. Surfaces top insights as context.                | Anticipate               |\n| **[emergency](./plugins/nox-emergency/)**                   | Escalates urgent events. Dedup, rate limiting, TTL expiry detection.                    | Alert                    |\n| **[fademem](./plugins/nox-fademem/)**                       | Access-weighted Memory Decay — memories that are never retrieved fade.                  | Cognitive (experimental) |\n| **[cooccurrence](./plugins/nox-cooccurrence/)**             | Hebbian Learning — tracks concept co-occurrences for associative memory.                | Cognitive (experimental) |\n| **[fingerprint](./plugins/nox-fingerprint/)**               | Cognitive Fingerprint — personality profile based on memory topology + drift detection. | Cognitive (experimental) |\n\n\u003e **Note (2026-03-19):** The three Cognitive plugins (fademem, cooccurrence, fingerprint) are experimental. They load and hook into the lifecycle correctly, but in production use their actual data output has been minimal. The core value comes from auto-checkpoint, memory-qdrant, auto-capture, and preference-learner. The Cognitive layer is included for experimentation and may be refined in future releases. For a simpler setup, use `nox-memory-suite` with preset `core`.\n\u003e | **[memory-suite](./plugins/nox-memory-suite/)** | **Meta-plugin** — one config entry activates all of the above. Presets: `full`, `core`, `minimal`. | All |\n\nAll plugins hook into `before_agent_start` — your agent gets the full picture before every response.\n\n## Architecture\n\n```\n                    External World\n                         │\n          ┌──────────────┼──────────────┐\n          ▼              ▼              ▼\n     [Sensors]      [User Talk]    [Agent Work]\n     email, cal,    corrections,   checkpoints,\n     files, system  decisions      state changes\n          │              │              │\n          ▼              ▼              ▼\n    ┌─────────────── event-bus ──────────────────┐\n    │            (JSONL persistence)              │\n    └──────┬─────────────┬──────────────┬────────┘\n           │             │              │\n           ▼             ▼              ▼\n     preconscious   auto-capture   emergency\n     (score+buffer) (→ Qdrant)     (urgent alerts)\n           │             │              │\n           ▼             ▼              ▼\n    ┌────────────────────────────────────────────┐\n    │          Session Context Injection          │\n    │                                            │\n    │  checkpoint + memories + preferences       │\n    │  + preconscious buffer + emergency alerts  │\n    └────────────────────────────────────────────┘\n           │             │              │\n           ▼             ▼              ▼\n     auto-checkpoint  memory-qdrant  preference-learner\n     (state/current)  (vector search) (behavioral scores)\n```\n\n**Total overhead per session start: \u003c 500ms** (tested on ARM64 and x86).\n\n## How It Works\n\n**auto-checkpoint** reads your `state/current.md` and injects it as context. Your agent always knows where it left off — even after context compaction. Before compaction, it backs up the current state so nothing is lost.\n\n**memory-qdrant** searches your local Qdrant for semantically relevant memories, matches keywords against a `facts.jsonl` file (verified facts, keyword-searched), and hints at relevant knowledge files based on configurable topic routing.\n\n**auto-capture** runs silently, detecting when conversations contain corrections, decisions, new facts, or lessons. Stores them in Qdrant automatically. User-only capture, SHA256 deduplication, 30+ skip patterns, metadata cleaning.\n\n**preference-learner** detects feedback signals in your conversations — praise, frustration, corrections — and maps them to 6 behavioral dimensions. Over time, your agent adapts _how_ it works with you:\n\n```\nYou: \"Dude, stop asking for permission every time — just do it!\"\n  → Signal: negative (-1.5)\n  → Categories: confirmation_seeking → LESS, autonomy → MORE\n  → Saved to preferences.json\n\nNext session, agent receives:\n  \"STRONG preference for LESS confirmation seeking (score: -4.5, 5x reinforced)\"\n  → Agent stops asking for permission on obvious tasks\n```\n\nSix dimensions: **autonomy**, **verbosity**, **proactivity**, **formality**, **technical depth**, **confirmation seeking**. Preferences decay if not reinforced (30-day half-life) — no overreaction to a single comment.\n\n**event-bus** is the nervous system. Any plugin or sensor can emit events with a topic, importance score, and TTL. Events persist as JSONL and auto-prune after 7 days. At session start, the most relevant recent events are injected as context.\n\n**preconscious** watches the event bus and asks: \"What's important right now, even if nobody asked?\" It scores events by `importance × recency_decay × reinforcement_count` and writes the top 5 as a Markdown buffer (max 500 tokens). Your agent gets ambient awareness without being overwhelmed.\n\n**emergency** watches for critical events (importance ≥ 0.85) and soon-to-expire TTLs. Deduplicates via SHA256, rate-limits to 2 alerts per day, and injects unhandled alerts as priority context. Your agent sees `⚠️ URGENT` before anything else.\n\n## What Makes This Different\n\n### vs. Flat MEMORY.md\n\nMEMORY.md grows until you summarize, losing detail. This project stores everything in Qdrant, recalls only what's relevant, and keeps MEMORY.md as a lightweight index.\n\n### vs. Cloud Memory (Mem0, Zep)\n\nCloud services send your data elsewhere and none adapt agent behavior. This runs on your machine, learns how you work, AND watches for problems proactively.\n\n### vs. [Total Recall](https://github.com/gavdalf/total-recall)\n\nTotal Recall pioneered ambient intelligence for agents. We build on that foundation:\n\n|               | Total Recall               | This project                |\n| ------------- | -------------------------- | --------------------------- |\n| Runtime       | Shell (bash + jq + python) | Node.js (OpenClaw plugins)  |\n| Scheduling    | Cron jobs                  | Runs on every session start |\n| Dependencies  | jq, python, PyYAML         | Node.js stdlib only         |\n| Testing       | Manual                     | 106 automated tests         |\n| Integration   | Standalone scripts         | Native OpenClaw hooks       |\n| Emergency     | Webhook/Telegram           | Context injection + dedup   |\n| Extensibility | Fork scripts               | Import + event listeners    |\n\n### Production-Proven\n\n- **2,000+ memories** stored and recalled daily\n- **4-layer compaction mitigation** (checkpoint backup → auto-checkpoint → compaction-summarizer → context re-injection)\n- **Embodied AI tested** — also used with a robot dog for sensor memory\n- Running continuously since January 2026 on a Raspberry Pi 5\n\n## Quick Start\n\n\u003e Start with `auto-checkpoint` + `memory-qdrant` — they give you 80% of the value. Add plugins as you need them.\n\n### Prerequisites\n\n- [OpenClaw](https://github.com/openclaw/openclaw) 2026.1.30+\n- [Qdrant](https://qdrant.tech/) running locally (or Qdrant MCP server)\n- [mcporter](https://github.com/steipete/mcporter) with a `qdrant-memory` server configured\n\n### Install\n\n```bash\ngit clone https://github.com/rockywuest/openclaw-memory-local.git\ncd openclaw-memory-local\n\npip3 install mcp-server-qdrant\nmcporter config add qdrant-memory stdio \\\n  --command \"python3 -m mcp_server_qdrant\" \\\n  --args \"--qdrant-local-path ~/.openclaw/memory/qdrant-data --collection-name memories\"\n```\n\n### Configure OpenClaw\n\n**Option A: One-line setup (recommended)**\n\nAdd `nox-memory-suite` — one path, one entry, full stack:\n\n```json\n{\n  \"plugins\": {\n    \"load\": {\n      \"paths\": [\n        \"/path/to/openclaw-memory-local/auto-checkpoint\",\n        \"/path/to/openclaw-memory-local/memory-qdrant\",\n        \"/path/to/openclaw-memory-local/plugins/nox-memory-suite\"\n      ]\n    },\n    \"entries\": {\n      \"nox-memory-suite\": { \"enabled\": true }\n    }\n  }\n}\n```\n\nThe suite auto-loads all 8 plugins in dependency order. Presets:\n\n| Preset           | Plugins                                               | Use Case                                          |\n| ---------------- | ----------------------------------------------------- | ------------------------------------------------- |\n| `full` (default) | All 8                                                 | Production — everything including cognitive layer |\n| `core`           | capture, events, preconscious, emergency, preferences | Daily use without cognitive analysis              |\n| `minimal`        | capture, preferences                                  | Lightweight — just learning and fact capture      |\n\nOverride individual plugins:\n\n```json\n{\n  \"nox-memory-suite\": {\n    \"enabled\": true,\n    \"preset\": \"core\",\n    \"plugins\": { \"fademem\": true }\n  }\n}\n```\n\n**Option B: Manual setup (pick and choose)**\n\nAdd individual plugin paths:\n\n```json\n{\n  \"plugins\": {\n    \"load\": {\n      \"paths\": [\n        \"/path/to/openclaw-memory-local/auto-checkpoint\",\n        \"/path/to/openclaw-memory-local/memory-qdrant\",\n        \"/path/to/openclaw-memory-local/plugins/nox-auto-capture\",\n        \"/path/to/openclaw-memory-local/plugins/nox-preference-learner\",\n        \"/path/to/openclaw-memory-local/plugins/nox-event-bus\",\n        \"/path/to/openclaw-memory-local/plugins/nox-preconscious\",\n        \"/path/to/openclaw-memory-local/plugins/nox-emergency\",\n        \"/path/to/openclaw-memory-local/plugins/nox-fademem\",\n        \"/path/to/openclaw-memory-local/plugins/nox-cooccurrence\",\n        \"/path/to/openclaw-memory-local/plugins/nox-fingerprint\"\n      ]\n    }\n  }\n}\n```\n\nThen:\n\n```bash\nopenclaw gateway restart\n```\n\nThat's it. Your agent now has memory, behavioral adaptation, and ambient intelligence.\n\n## Troubleshooting\n\n### memory_search returns empty results\n\nOpenClaw's built-in `memory_search` uses a **separate embedding provider** (OpenAI, Gemini, etc.) — independent of these plugins. If `memory_search` returns empty:\n\n1. Check provider config: `openclaw memory status`\n2. Common causes: API key expired, rate limit during reindex, provider switch without reindex\n3. Verify plugins work independently: `mcporter call qdrant-memory.qdrant-find query=\"test\"`\n\n\u003e These plugins use mcporter → Qdrant (local embeddings). OpenClaw's `memory_search` uses a cloud embedding provider. They are independent systems.\n\n### Monitoring\n\n```bash\nbash scripts/memory-health.sh\n```\n\nChecks 7 subsystems: Qdrant access, mcporter find/store, embedding cache, sync cron, memory files, provider config. Exit 0 = healthy. Run it in your agent's heartbeat loop.\n\n## Privacy\n\n- **Zero cloud dependency.** Qdrant runs locally. Nothing leaves your machine.\n- **No telemetry.** No analytics. No tracking.\n- **Your data, your disk.** Delete the Qdrant directory, delete the memories.\n\n## Development\n\n```bash\nnpm test    # 184 tests, zero external deps\n```\n\nEach plugin includes an [agentskills.io](https://agentskills.io)-compliant `SKILL.md`.\n\n## Roadmap\n\n- [x] Semantic recall via Qdrant\n- [x] Automatic fact/decision capture\n- [x] Behavioral preference learning\n- [x] Ambient Intelligence Engine (event bus, preconscious buffer, emergency surface)\n- [x] FadeMem: access-weighted decay\n- [x] Co-occurrence tracking (Hebbian links)\n- [x] Cognitive fingerprint (topology hash)\n- [x] Sensor connectors (file watchers, system monitoring)\n- [x] Meta-plugin (`nox-memory-suite`) — one-line activation with presets\n- [ ] ClawhHub listing\n\n## License\n\nMIT — use it, fork it, improve it.\n\n---\n\n**Contributors:** [Rocky Wüst](https://github.com/rockywuest) (creator), Nox ⚡ (architecture + implementation), Claude (Anthropic)\n\n_Running 24/7 since January 2026. Part of the [Sentinel Agent](https://rotomi.de/sentinel-agent.html) ecosystem._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frockywuest%2Fopenclaw-memory-local","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frockywuest%2Fopenclaw-memory-local","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frockywuest%2Fopenclaw-memory-local/lists"}