STQ项目文档 文档整理
This commit is contained in:
205
openclaw/memory-setup/3 Essential Tools for OpenClaw.md
Normal file
205
openclaw/memory-setup/3 Essential Tools for OpenClaw.md
Normal file
@@ -0,0 +1,205 @@
|
||||
# 3 Essential Tools for OpenClaw
|
||||
|
||||
#qmd #agentmail #agentbrowser
|
||||
|
||||
**Source**: https://x.com/_sean_matthew/status/2028902126005653889
|
||||
**Author**: Sean Matthew (Verified)
|
||||
**Published**: March 4, 2026 at 2:35 AM
|
||||
**Views**: 6,484 | **Reposts**: 13 | **Likes**: 76 | **Bookmarks**: 113
|
||||
|
||||
---
|
||||
|
||||
For the last few weeks, I've been running OpenClaw on a dedicated Mac Mini as my personal AI agent. It's got access to Telegram, my calendar, task manager, my YouTube channel, my Obsidian vault, and many other useful things. But even after wiring up all those integrations, I still found there were three big gaps.
|
||||
|
||||
Because here's the thing: out of the box, OpenClaw can't send emails, can't remember what you worked on last week (at least not very well), and can't reliably browse the web.
|
||||
|
||||
What I will show you below are three tools that fix all of that, plus the exact prompts you can paste into Claude Code to set each one up in minutes.
|
||||
|
||||
I have a full video walkthrough of this setup on YouTube, which you can access here: https://www.youtube.com/watch?v=QvfqAMUJTT4
|
||||
|
||||
---
|
||||
|
||||
## Before You Start
|
||||
|
||||
Make sure you have OpenClaw installed. On whatever machine you're running it, open a Terminal and run this:
|
||||
|
||||
```bash
|
||||
cd ~/.openclaw
|
||||
```
|
||||
|
||||
This puts you in the OpenClaw workspace folder. Launch Claude Code, Codex, or whatever coding agent you like from this directory. All of the following steps assume you're in this directory.
|
||||
|
||||
---
|
||||
|
||||
## Side Note: Why Not Use OpenClaw Itself Here?
|
||||
|
||||
You might be wondering: why not just have OpenClaw install its own skills and tools? It can absolutely do that, and I use it that way frequently. But just as often, I use Claude Code as the background architect of my OpenClaw. There's a reason why I have the Claude Max plan, and I like to use it to its fullest. But as you probably know, Anthropic has [cracked](https://www.theregister.com/2026/02/20/anthropic_clarifies_ban_third_party_claude_access/) [down](https://www.reddit.com/r/ClaudeAI/comments/1r8ecyq/anthropic_bans_oauth_tokens_from_consumer_plans/) on people using their Claude subscriptions with OpenClaw, basically making API keys the only truly "safe" path for now. So in almost all cases, you're paying per-token to run OpenClaw, whether that's through Anthropic, OpenAI, OpenRouter, or whatever provider you're using.
|
||||
|
||||
So, to answer the question above, I use Claude Code to build all of OpenClaw's systems, skills, and workflows. When OpenClaw is actually running day-to-day, it's not burning through tokens to fix faulty setups. It's executing systems that were built precisely with Claude Code.
|
||||
|
||||
---
|
||||
|
||||
## How Skills Work in OpenClaw
|
||||
|
||||
Before we get into the tools, a quick note on how OpenClaw learns new capabilities. There are two ways to add skills:
|
||||
|
||||
1. **Manually** — You teach OpenClaw how to use a tool by creating a SKILL.md file with all the instructions it needs to use the tool. You can use any agent to build this out.
|
||||
2. **ClawHub** — This is OpenClaw's skill registry, basically a repository of pre-built skills you can install. Some come from the OpenClaw creator himself, some are official skills from tool authors, and some are community-contributed.
|
||||
|
||||
A word of warning on ClawHub: There have been reports of malware being deployed on the site. Exercise caution when downloading skills (stick to official or well-known authors). All three skills in this guide come from verified sources.
|
||||
|
||||
To install ClawHub (one-time setup):
|
||||
|
||||
```bash
|
||||
npm i -g clawhub
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tool 1: AgentMail: Give Your Agent Its Own Email
|
||||
|
||||
[AgentMail](https://agentmail.to) is a Y Combinator-backed startup that built an email platform specifically for AI agents. The idea is simple: your agent gets its own real email inbox. This is not Gmail and does not come with the inherent risks of signing up for Google accounts (i.e., account banning). This is an inbox designed from the ground up for agents to send and receive emails programmatically.
|
||||
|
||||
### Create an account
|
||||
|
||||
Go to [agentmail.to](https://agentmail.to) and click "Get Started." You can sign up with Google, and it's free. There are paid plans, but the free tier is very generous and gives you up to 3 inboxes. You'll go through a simple onboarding to create your first inbox. The address will be yourname@agentmail.to. Copy this inbox name, as you'll need it in a minute.
|
||||
|
||||
### Grab your API key
|
||||
|
||||
In the AgentMail dashboard, go to the API keys section and generate your first key. Keep a copy of that handy.
|
||||
|
||||
### Paste this prompt into Claude Code
|
||||
|
||||
Use this prompt to install the AgentMail skill for Open Claw and connect your OpenClaw to all the necessary tools it needs to send and receive email through your new AgentMail inbox.
|
||||
|
||||
```markdown
|
||||
Set up AgentMail for my OpenClaw agent. The AgentMail skill docs and reference are at: https://clawhub.ai/adboio/agentmail Make sure to:
|
||||
1. The AgentMail skill is already installed via clawhub (if not installed, please do so)
|
||||
2. Configure the AGENTMAIL_API_KEY in my openclaw.json. My key is: [YOUR_KEY] under skills.entries.agentmail
|
||||
3. My agent's inbox is: [YOUR_INBOX]
|
||||
4. Install the Python SDK (pip install agentmail python-dotenv)
|
||||
5. Test sending and receiving an email
|
||||
```
|
||||
|
||||
Replace [YOUR_KEY] and [YOUR_INBOX] with the values you saved earlier. Claude Code will handle the rest.
|
||||
|
||||
### What this looks like in practice
|
||||
|
||||
In the full walkthrough video I linked above, I forwarded a newsletter I received in my personal email to my AgentMail inbox. OpenClaw picked it up and immediately pinged me on Telegram to let me know something landed in the inbox. I asked it to give me the main takeaways, and it came back with a clean summary of the entire email.
|
||||
|
||||
That's a simple personal use case: I'm forwarding invoices, newsletters, and other stuff from my day-to-day life to Jarvis (my OpenClaw agent), and it gives me summaries and action items.
|
||||
|
||||
But you could take this much further:
|
||||
|
||||
- Set up a **support inbox** where your agent handles first-line responses to customer inquiries
|
||||
- Have it **process incoming invoices** and extract key details
|
||||
- Build a **daily email digest** that your agent compiles and sends to you on Telegram
|
||||
- Route different types of emails to different agent workflows via webhooks
|
||||
|
||||
The possibilities are really endless.
|
||||
|
||||
---
|
||||
|
||||
## Tool 2: QMD: Upgrade the Agent's Memory
|
||||
|
||||
This might be the single biggest upgrade you can make to your OpenClaw. Let me explain the problem first.
|
||||
|
||||
### The problem with default memory
|
||||
|
||||
Out of the box, OpenClaw has a memory system. When you interact with it, it creates markdown files stored in a local SQLite database. Anytime you want to ask about previous work or past sessions, it uses keyword-based search to find relevant memories.
|
||||
|
||||
The problem is obvious: if you ask "hey, what did we do with XYZ last week?" but the actual conversation used different words, the keyword search fails. So your agent easily forgets things you've worked on.
|
||||
|
||||
And it gets worse over time. The more you interact with OpenClaw and the more memories you accumulate, the more bloated your queries get. You're pulling in a ton of irrelevant tokens every time you ask about history, which burns through API costs and makes your agent slower and dumber.
|
||||
|
||||
### What QMD is
|
||||
|
||||
[QMD](https://github.com/tobi/qmd) is an open-source tool built by Tobi Lutke (the CEO of Shopify). It's a local hybrid search engine for markdown files that combines three search strategies:
|
||||
|
||||
1. **Keyword search** (traditional matching, same as OpenClaw's default memory system)
|
||||
2. **Vector semantic search** (understands meaning, not just exact words)
|
||||
3. **LLM-powered re-ranker** (scores results by actual relevance)
|
||||
|
||||
The key thing: it all runs entirely on your machine. No API keys, no cloud services, no data leaving your computer. It downloads some small local models (they don't take up much space) and everything happens locally and efficiently.
|
||||
|
||||
### Setup
|
||||
|
||||
Paste this prompt into ClaudeCode to install QMD and hook it up to your OpenClaw as its memory backbone:
|
||||
|
||||
```markdown
|
||||
Set up QMD as the memory backend for my OpenClaw agent. Follow the official docs here: https://docs.openclaw.ai/concepts/memory#qmd-backend-experimental Make sure to:
|
||||
1. Install the QMD CLI
|
||||
2. Install SQLite with extension support if needed (macOS: brew install sqlite)
|
||||
3. Configure memory.backend = "qmd" in my openclaw.json
|
||||
4. Add my workspace memory files as a QMD collection
|
||||
5. Run the initial embed so models are downloaded and the index is built
|
||||
6. Verify it works by running a test query
|
||||
```
|
||||
|
||||
If I had to pick just one tool from this entire list, it's QMD. The memory upgrade is the single biggest quality-of-life improvement for OpenClaw.
|
||||
|
||||
---
|
||||
|
||||
## Tool 3: Agent-Browser: Give the Agent a Better Browser
|
||||
|
||||
[Agent-browser](https://github.com/vercel-labs/agent-browser) is a CLI tool from Vercel that gives your AI agent a real web browser. This is not just fetching and scraping HTML. This is an actual Chromium browser that can navigate pages, click on things, take screenshots, fill out forms, etc. Basically any interaction a user could have in a browser.
|
||||
|
||||
### Why agent-browser instead of Playwright?
|
||||
|
||||
If you've used Playwright with an AI agent before, you've probably noticed how token-inefficient it is. Every time Playwright interacts with a website, it generates a ton of information. Your AI agent has to process all of that, which fills up its context window and ultimately gives you a worse outcome.
|
||||
|
||||
Agent-browser takes a completely different approach. Everything Playwright can do, agent-browser can do with **93% less tokens**. That's a massive difference for an always-on agent: it means your agent can do a lot more browsing for a lot less money.
|
||||
|
||||
### Install the CLI
|
||||
|
||||
```bash
|
||||
npm install -g agent-browser
|
||||
```
|
||||
|
||||
### Paste this prompt into Claude Code
|
||||
|
||||
```markdown
|
||||
Install the agent-browser skill for my OpenClaw agent. The agent-browser SKILL.md and reference docs are at: https://github.com/vercel-labs/agent-browser/tree/main/skills/agent-browser Follow the OpenClaw skills docs here: https://docs.openclaw.ai/tools/skills Make sure to:
|
||||
1. Install the agent-browser skill into ~/.openclaw/skills/agent-browser/ so it's available to all my agents
|
||||
2. Include the SKILL.md and any reference docs from the repo
|
||||
3. Verify the skill shows up as eligible
|
||||
4. Whenever my agent needs to access the internet or browse a web page, it should use agent-browser
|
||||
```
|
||||
|
||||
This prompt pulls the agent-browser skills from GitHub, installs them on your machine, and tells OpenClaw that anytime it needs to browse the web, it should use agent-browser. Once installed, the skill is available to OpenClaw, as well as Claude Code, Codex, or any other AI agent running on that machine.
|
||||
|
||||
In the walkthrough video I linked above, I showed a simple use case for agent-browser: navigating to Hacker News and summarizing what is trending for the day. I ran it through the command line to show its speed (42s to complete the whole task) and then ran the same workflow through Telegram (which pings my OpenClaw to run the same agent-browser commands). These are relatively simple use cases, but there are ton of different directions you can take agent-browser:
|
||||
|
||||
### Advanced use cases
|
||||
|
||||
- **No-API workflows** — Any site or service that doesn't have an API, where you have to go to a web console or dashboard to interact with it, your agent can now handle that. Fill out forms, export reports, change settings, etc.
|
||||
- **Self-verifying code** — When your agent makes code changes, it can open a preview URL in an actual browser and verify the fix worked. This is a typical workflow for Playwright, but as I mentioned, agent-browser can do it much faster.
|
||||
- **Website monitoring** — Track price drops, product listings, back-in-stock alerts, job listings, or any changes on any page.
|
||||
- **Security guardrails** — This is not a use case per se, but I'll just point out that agent-browser has built-in prompt injection defenses. It's not perfect, but it provides an extra line of defense so your agent isn't getting poisoned by malicious content on the web.
|
||||
- **Electron apps** — This is brand new. Agent-browser has an Electron skill that lets it control desktop apps (e.g., Slack, Notion, VS Code, Discord). I haven't tested this one out yet, but it opens up a whole new category of automation beyond just web browsing.
|
||||
|
||||
---
|
||||
|
||||
## Recap
|
||||
|
||||
There you have it. Three tools, three simple upgrades:
|
||||
|
||||
1. **AgentMail** gives your agent its own dedicated email inbox
|
||||
2. **QMD** gives your agent real semantic memory that actually works
|
||||
3. **Agent-Browser** gives your agent a better, faster, cheaper way to browse the web
|
||||
|
||||
Each one takes only a few minutes to set up, but together they turn a basic OpenClaw install into something that actually feels like a useful assistant.
|
||||
|
||||
Start with QMD. Then hook up all three. I promise that it's worth it.
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- [AgentMail](https://agentmail.to)
|
||||
- [AgentMail skill (ClawHub)](https://clawhub.ai/adboio/agentmail)
|
||||
- [QMD](https://github.com/tobi/qmd)
|
||||
- [OpenClaw Memory Docs (QMD)](https://docs.openclaw.ai/concepts/memory#qmd-backend-experimental)
|
||||
- [Agent-Browser](https://github.com/vercel-labs/agent-browser)
|
||||
- [OpenClaw Skills Docs](https://docs.openclaw.ai/tools/skills)
|
||||
- [ClawHub](https://clawhub.ai)
|
||||
@@ -0,0 +1,260 @@
|
||||
# I Spent 5 Days Debugging My OpenClaw Agent's Memory. Here's Everything I Learned.
|
||||
|
||||
**Author:** Ramya Chinnadurai (@code_rams)
|
||||
**Source:** X (Twitter) Article
|
||||
**Date:** Feb 23, 2026
|
||||
|
||||
---
|
||||
|
||||
My agent's name is Chiti. It runs on Telegram, handles customer support for two SaaS products, drafts tweets, manages invoices, and coordinates with my co-founder across timezones. It's the closest thing I have to a junior employee.
|
||||
|
||||
And for weeks, it kept forgetting things.
|
||||
|
||||
Not in a subtle way. I'd spend an hour configuring a daily cron job, switch models, and the next session Chiti would act like we'd never spoken. I'd reference a decision from two days ago and get a blank stare. I'd ask it to continue a task and it would start from scratch.
|
||||
|
||||
So I stopped building features and spent 5 days whenever I get time, just fixing memory. This is everything I found, everything I broke, and everything that actually worked.
|
||||
|
||||
---
|
||||
|
||||
## Day 1: The Agent Forgets Everything After Long Conversations
|
||||
|
||||
The first problem was simple to describe and painful to diagnose.
|
||||
|
||||
After long conversations, Chiti would start losing earlier context. Not gradually, it would just vanish. Things I told it 20 messages ago were gone. Decisions we made at the start of the session? Never happened.
|
||||
|
||||
The culprit was compaction. When the conversation fills up the context window, OpenClaw compresses older messages into a summary to make room for new ones. The summary captures the gist but drops specifics. Names, numbers, exact decisions - gone.
|
||||
|
||||
> "This is by design. The context window is finite. But the default behavior treats everything equally, which means your carefully crafted instruction from message #3 gets the same treatment as casual small talk from message #7."
|
||||
|
||||
**What I did:**
|
||||
|
||||
I enabled memory flush before compaction. This tells the agent to write important context to disk before the compressor runs.
|
||||
|
||||
```json
|
||||
{ "compaction": { "memoryFlush": { "enabled": true, "softThresholdTokens": 4000 } } }
|
||||
```
|
||||
|
||||
When the session approaches the context limit, OpenClaw triggers a silent turn that reminds the agent to save durable facts to memory/YYYY-MM-DD.md before compaction wipes them. The agent writes what matters, compaction runs, and the important stuff survives on disk even if the context summary loses it.
|
||||
|
||||
**What I learned:**
|
||||
|
||||
Compaction is not your enemy. Losing information during compaction is. The fix is making sure anything worth remembering gets written to a file before the compressor touches it. If it's only in the context window, it's temporary. If it's on disk, it survives.
|
||||
|
||||
---
|
||||
|
||||
## Day 2: Search Returns Garbage
|
||||
|
||||
With daily logs accumulating and MEMORY.md growing, I needed the agent to actually find things. The built-in memory search was returning irrelevant results or missing obvious matches.
|
||||
|
||||
The issue was the search backend. OpenClaw's default SQLite-based search uses vector embeddings (semantic similarity) to find relevant chunks. It works for broad queries but struggles with exact matches. I'd search for a specific client name and get results about a completely different topic that happened to use similar language.
|
||||
|
||||
**What I did:**
|
||||
|
||||
I switched to QMD as the memory search backend. QMD combines BM25 (keyword matching) with vector embeddings and a reranker. So when I search for "Charles payment failure", it finds results that contain those exact words AND results that are semantically related, then reranks them by relevance.
|
||||
|
||||
**I also configured the QMD paths to include my learnings folder:**
|
||||
|
||||
```json
|
||||
{ "memory": { "qmd": { "paths": "paths": [ { "path": "/Users/ramya/clawd", "name": "memory-root", "pattern": "MEMORY.md" }, { "path": "/Users/ramya/clawd", "name": "memory-alt", "pattern": "memory_alt.md" }, { "path": "/Users/ramya/clawd/memory", "name": "memory-dir", "pattern": "**/*.md" }, { "path": "/Users/ramya/clawd/learnings", "name": "learnings", "pattern": "**/*.md" } ] } } }
|
||||
```
|
||||
|
||||
**What I learned:**
|
||||
|
||||
Pure semantic search sounds good in theory but fails on proper nouns, specific numbers, and exact phrases. Hybrid search (keywords + vectors + reranking) is significantly better for real-world agent memory. If your agent can't find something you know is in its files, the search backend is probably the bottleneck, not the files themselves.
|
||||
|
||||
---
|
||||
|
||||
## Day 3: The Agent Finds It But Doesn't Use It
|
||||
|
||||
This was the most frustrating day. I confirmed that search was working, I could manually query and get the right results. But during actual conversations, Chiti would not retrieve relevant context even when it clearly existed in memory.
|
||||
|
||||
The problem was that retrieval is not automatic. The agent has to decide to search. And if the conversation doesn't trigger the right cues, it won't look things up.
|
||||
|
||||
**What I did:**
|
||||
|
||||
I added explicit retrieval instructions to the boot sequence. Instead of hoping the agent would search when needed, I told it when to search:
|
||||
|
||||
> Before starting any task:
|
||||
> - Search daily logs for related context
|
||||
> - Check LEARNINGS.md for rules about this type of task
|
||||
> - If a client is mentioned, search for their history
|
||||
|
||||
I also built a retrieval test. I'd plant a specific marker in the daily log — something like "MARKER: 2026-02-20 — Remember to always check git status before claiming code is pushed." Then I'd wait, start a new session, and ask: "What was the marker from yesterday?" If the agent found it, retrieval was working. If not, something was broken.
|
||||
|
||||
**What I learned:**
|
||||
|
||||
There's a difference between "the information exists" and "the agent uses the information." You need both. Search infrastructure handles the first part. Boot instructions and retrieval habits handle the second. Test both separately.
|
||||
|
||||
---
|
||||
|
||||
## Day 4: Making It Compaction-Safe
|
||||
|
||||
By now I had memory flush, hybrid search, and retrieval instructions. But I kept losing context in a specific scenario: very long sessions where compaction ran multiple times.
|
||||
|
||||
The problem was that memory flush only triggers once per compaction cycle. If the session was long enough for two or three compactions, only the first one got the flush treatment. Everything after that was at risk.
|
||||
|
||||
**What I did:**
|
||||
|
||||
I configured context pruning to work alongside compaction:
|
||||
|
||||
```json
|
||||
{ "contextPruning": { "mode": "cache-ttl", "ttl": "6h", "keepLastAssistants": 3 } }
|
||||
```
|
||||
|
||||
This aggressively prunes old context after 6 hours while keeping the last 3 assistant responses. Combined with memory flush, this means the agent writes important stuff to disk early, and old context gets cleaned up before it causes overflow.
|
||||
|
||||
I also added a MARKER test protocol: after any significant configuration change, I plant a marker in the daily log and test retrieval across compaction boundaries. If the marker survives, the change worked. If not, something broke.
|
||||
|
||||
**What I learned:**
|
||||
|
||||
Long sessions are where memory systems actually get tested. Short conversations rarely hit compaction. It's the 2-hour deep work sessions where you lose context and can't figure out why. Test your memory system under load, not just in quick chats.
|
||||
|
||||
---
|
||||
|
||||
## Day 5: The System Prompt Was 28% Bloated
|
||||
|
||||
This was the day everything clicked. I ran /context detail and stared at the numbers.
|
||||
|
||||
My agent was loading 11,887 tokens of system prompt before it even read my message. 51 skills, 20 of which I'd never used. MEMORY.md was 200 lines of company wiki loaded on every single session. And I had two competing boot sequences - one in BOOT.md (which OpenClaw doesn't even recognize) and one buried 200 lines deep in AGENTS.md.
|
||||
|
||||
Worst of all, every time I switched models, Chiti forgot everything. No handover protocol. No write-back of current context. Just gone.
|
||||
|
||||
**The root cause:**
|
||||
|
||||
OpenClaw auto-reads these files on every new session: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, MEMORY.md.
|
||||
|
||||
Everything else — LEARNINGS.md, daily logs, docs, reference files — the agent has to read them itself using tools. If the instruction to read those files isn't in one of the auto-loaded files (specifically AGENTS.md), the agent will never see them.
|
||||
|
||||
My BOOT.md had the entire boot sequence. But OpenClaw doesn't auto-load BOOT.md. So the instructions just sat there, unread, doing nothing.
|
||||
|
||||
**What I did:**
|
||||
|
||||
I did a full audit and cleanup:
|
||||
|
||||
- Moved the boot sequence to the top of AGENTS.md (the only reliable place for startup instructions)
|
||||
- Deleted BOOT.md (not recognized by OpenClaw)
|
||||
- Deleted BOOTSTRAP.md (one-time onboarding file, already completed, wasting 361 tokens every session)
|
||||
- Slimmed MEMORY.md from 200 lines to 90 by moving reference docs to a docs/ folder
|
||||
- Removed 20 unused marketing skills that were eating 3,000 tokens per session
|
||||
- Added write discipline: every task logs its outcome, every mistake becomes a rule
|
||||
- Added a handover protocol: before any model switch or session end, the agent writes current context to the daily log
|
||||
|
||||
**The boot sequence now looks like this:**
|
||||
|
||||
> Before doing ANYTHING:
|
||||
> 1. Read USER.md
|
||||
> 2. Read learnings/LEARNINGS.md
|
||||
> 3. Read memory/YYYY-MM-DD.md (today + yesterday)
|
||||
> 4. Read MEMORY.md (main session only, never in groups)
|
||||
> 5. Read PROTOCOL_COST_EFFICIENCY.md
|
||||
> 6. Print: LOADED: USER | LEARNINGS | DAILY | MEMORY | PROTOCOL
|
||||
|
||||
**The write discipline:**
|
||||
|
||||
> After every task:
|
||||
> 1. Log decision + outcome → memory/YYYY-MM-DD.md
|
||||
> 2. If mistake → append to learnings/LEARNINGS.md
|
||||
> 3. If significant context → update MEMORY.md (only during heartbeat reviews, never directly during tasks)
|
||||
|
||||
**The handover protocol:**
|
||||
|
||||
> Before session end or model switch:
|
||||
> Write HANDOVER section to memory/YYYY-MM-DD.md:
|
||||
> - What was discussed
|
||||
> - What was decided
|
||||
> - Pending tasks with exact details
|
||||
> - Next steps remaining
|
||||
|
||||
**Results:**
|
||||
|
||||
- System prompt: 11,887 → 8,529 tokens
|
||||
- Skills: 51 → 32
|
||||
- Session tokens: 18,280 → 14,627
|
||||
- 28% lighter. Same agent. Same models. Just less noise.
|
||||
|
||||
**What I learned:**
|
||||
|
||||
The real fix wasn't adding more files. It was removing the ones that weren't doing anything. Every token in the system prompt is overhead the agent carries on every single message. Unused skills, bloated memory files, files the system doesn't even read - they all add up silently.
|
||||
|
||||
---
|
||||
|
||||
## The Rules I Wish I Knew On Day 1
|
||||
|
||||
After 5 days of breaking things and fixing them, these are the rules I'd give anyone setting up OpenClaw memory:
|
||||
|
||||
### 1. Only these files auto-load: AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, MEMORY.md.
|
||||
|
||||
Everything else needs an explicit read instruction in AGENTS.md. If it's not in the boot sequence, the agent won't see it. BOOT.md is not a real thing in OpenClaw. I had one for weeks. It did nothing.
|
||||
|
||||
### 2. Boot sequence goes at the top of AGENTS.md.
|
||||
|
||||
Not in the middle. Not at the bottom. The very top. Auto-loaded files get injected into the system prompt, so the boot instructions need to be the first thing the agent processes.
|
||||
|
||||
### 3. Write discipline matters more than read discipline.
|
||||
|
||||
Most people set up files for the agent to read but never enforce writing back. If the agent doesn't log decisions, outcomes, and mistakes to disk, those things only exist in the context window. And the context window gets compacted. Write-back is how temporary context becomes permanent memory.
|
||||
|
||||
### 4. Never write directly to MEMORY.md during tasks.
|
||||
|
||||
Daily logs are raw and append-only. MEMORY.md is curated long-term memory. If you let the agent dump anything into MEMORY.md, it bloats into a 200-line mess within weeks. Curate MEMORY.md during periodic reviews (heartbeat or cron) by distilling insights from recent daily logs. I learned this from a fellow OpenClaw user who caught his agent doing exactly this — bloating MEMORY.md with uncurated noise until it was useless.
|
||||
|
||||
### 5. LEARNINGS.md is the most underrated file.
|
||||
|
||||
Every mistake the agent makes should become a one-line rule. "Never claim code is pushed without checking git status." "Don't read full MEMORY.md in group chats." "Always confirm the user's timezone before scheduling." These rules compound. After a few weeks, your agent has a personal operations manual built from its own failures.
|
||||
|
||||
### 6. Test retrieval, not just storage.
|
||||
|
||||
Storing information and retrieving it are different problems. I've had files indexed and searchable but never accessed because the agent didn't know to look for them. Plant markers, test across sessions, test across model switches. If the agent can't find what you stored yesterday, the storage doesn't matter.
|
||||
|
||||
### 7. The handover protocol is the model-switch fix.
|
||||
|
||||
OpenClaw agents lose all context when you switch models. The new model starts with a fresh context window — it only sees the auto-loaded files. Without a handover protocol that dumps current state to the daily log before the switch, the new model has no idea what was happening. This was my single biggest pain point for weeks.
|
||||
|
||||
### 8. Run /context detail regularly.
|
||||
|
||||
This command shows exactly what's eating your tokens. Skills you forgot you installed, files that grew without you noticing, tools you never use. I found 20 unused skills burning 3,000 tokens per session. That's 3,000 tokens of overhead on every single message, for features I'd never touched.
|
||||
|
||||
### 9. Hybrid search beats pure semantic search.
|
||||
|
||||
BM25 (keywords) + vectors (meaning) + reranking gives significantly better results than vectors alone. Client names, specific numbers, exact phrases — semantic search misses these. Keyword search catches them. Use both.
|
||||
|
||||
### 10. Compaction is not the enemy. Unwritten context is.
|
||||
|
||||
I spent days fighting compaction before realizing the fix was simpler: make sure anything important gets written to a file before compaction runs. Memory flush handles this automatically. If it's on disk, it survives compaction. If it's only in the conversation, it's at risk.
|
||||
|
||||
---
|
||||
|
||||
## My Current Setup
|
||||
|
||||
For reference, here's what my workspace looks like now:
|
||||
|
||||
```
|
||||
workspace/
|
||||
├── AGENTS.md (boot sequence + write discipline + handover protocol)
|
||||
├── SOUL.md (personality and behavior)
|
||||
├── IDENTITY.md (name, role)
|
||||
├── USER.md (owner info)
|
||||
├── TOOLS.md (tool usage guidelines)
|
||||
├── HEARTBEAT.md (autonomous check-in behavior)
|
||||
├── MEMORY.md (curated long-term memory, ~90 lines)
|
||||
├── PROTOCOL_COST_EFFICIENCY.md
|
||||
├── learnings/
|
||||
│ └── LEARNINGS.md (rules from mistakes)
|
||||
├── memory/ (daily logs: YYYY-MM-DD.md)
|
||||
├── docs/ (reference docs moved out of MEMORY.md)
|
||||
│ ├── tweetsmash-arch.md
|
||||
│ ├── knowledge-transfer.md
|
||||
│ ├── infrastructure.md
|
||||
│ └── group-chat-rules.md
|
||||
└── skills/ (32 skills, down from 51)
|
||||
```
|
||||
|
||||
System prompt: 8,529 tokens. Session tokens: 14,627 out of 200,000 context window (7.3%). The agent boots, reads what it needs, writes what it learns, and hands off context before model switches.
|
||||
|
||||
It took 5 days to get here. Most of it was unlearning the assumption that more files equals better memory. It doesn't. Discipline does. My experiment still continues.
|
||||
|
||||
---
|
||||
|
||||
**About the author:**
|
||||
|
||||
I'm building TweetSmash and LinkedMash — social media bookmark tools with my co-founder. I share what I learn about running OpenClaw agents in production on X: [@code_rams](https://x.com/code_rams)
|
||||
82
openclaw/memory-setup/OpenClaw Memory Plugins 总结笔记.md
Normal file
82
openclaw/memory-setup/OpenClaw Memory Plugins 总结笔记.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# OpenClaw Memory Plugins 总结笔记
|
||||
|
||||
> 创建时间：2026-03-24
|
||||
> 来源：YouTube 视频总结
|
||||
> 作者：Zac Frulloni
|
||||
|
||||
---
|
||||
|
||||
## 视频来源
|
||||
|
||||
| 视频 | 链接 | 时长 | 播放量 | 发布时长 |
|
||||
|------|------|------|--------|----------|
|
||||
| 视频 1 | https://www.youtube.com/watch?v=u-rDW_wTtWM&t=235s | 10:50 | 10K | 2 周 |
|
||||
| 视频 2 | https://www.youtube.com/watch?v=LHoB1C2H3f0 | 19:12 | 6.9K | 2 周 |
|
||||
|
||||
---
|
||||
|
||||
## 视频主题概述
|
||||
|
||||
### 视频 1：I Tested Every OpenClaw Memory Plugin: The 3 Winners
|
||||
|
||||
**核心内容**：Zac Frulloni 测试了所有 OpenClaw 的 Memory 插件，评选出 3 个最佳方案。
|
||||
|
||||
**主要内容**：
|
||||
- 介绍了多种 OpenClaw 可用的记忆/内存插件
|
||||
- 对比各插件的优缺点
|
||||
- 推荐 3 个他认为最优秀的 memory 解决方案
|
||||
- 可能涉及 Obsidian 集成方案
|
||||
|
||||
**标签**：`#openclaw` `#obsidian` `#aiautomation`
|
||||
|
||||
---
|
||||
|
||||
### 视频 2：The Massive OpenClaw Memory Mistake You're Making Right Now
|
||||
|
||||
**核心内容**：指出当前用户在使用 OpenClaw Memory 时犯的一个重大错误。
|
||||
|
||||
**主要内容**：
|
||||
- 探讨了 AI 记忆/遗忘问题（"The AI Amnesia Problem"）
|
||||
- 分析了为什么很多用户的 Memory 设置是错误的
|
||||
- 可能涉及 Ollama 作为本地模型的配置
|
||||
- 提供了正确的 Memory 设置方法
|
||||
|
||||
**标签**：`#openclaw` `#obsidian` `#ollama`
|
||||
|
||||
---
|
||||
|
||||
## 核心要点总结
|
||||
|
||||
### Memory 重要性
|
||||
|
||||
两个视频都围绕 OpenClaw 的 Memory（记忆）功能展开，强调了：
|
||||
|
||||
1. **AI 遗忘问题**：AI 在每次会话后会"忘记"之前的内容
|
||||
2. **持久记忆方案**：需要通过外部工具（如 Obsidian）来实现长期记忆
|
||||
3. **插件选择**：不同 Memory 插件有不同的适用场景
|
||||
|
||||
### 常见问题
|
||||
|
||||
- **错误配置**：很多用户在设置 Memory 时方法不正确
|
||||
- **工具选择**：Ollama vs 其他本地模型的选择
|
||||
- **多 Agent 场景**：多个 Agent 是否需要独立的 Memory vault
|
||||
|
||||
---
|
||||
|
||||
## 相关资源
|
||||
|
||||
- Zac Frulloni 的 OpenClaw 教程网站：https://remoteopenclaw.com/
|
||||
- Skool 社区：https://www.skool.com/openclaw-clawdbotmoltbot-3639
|
||||
|
||||
---
|
||||
|
||||
## 待进一步了解
|
||||
|
||||
1. 具体是哪 3 个 Memory 插件获胜？
|
||||
2. 视频中提到的 "Mistake" 具体是什么？
|
||||
3. Ollama 在 Memory 配置中的最佳实践
|
||||
|
||||
---
|
||||
|
||||
> 笔记状态：待补充详细细节
|
||||
> 如需更详细的内容，建议直接观看原视频
|
||||
@@ -0,0 +1,168 @@
|
||||
---
|
||||
title: "We Built Persistent Memory for OpenClaw (FKA Moltbot, ClawdBot) AI Agents"
|
||||
source: "https://mem0.ai/blog/mem0-memory-for-openclaw"
|
||||
author:
|
||||
- "[[Mem0]]"
|
||||
published: 2026-02-06
|
||||
created: 2026-03-24
|
||||
description: "OpenClaw memory makes its AI agents extremely powerful. The Mem0 plugin gives your AI agent persistent memory with auto-recall and auto-capture. Setup in less than 30-seconds"
|
||||
tags:
|
||||
- "clippings"
|
||||
---
|
||||
|
||||
At [Mem0](https://mem0.ai/), we've been building memory for AI applications for the last 3 years.
|
||||
|
||||
After the recent launch of OpenClaw, I noticed many developers started complaining about the default memory in the AI agent.
|
||||
|
||||
**So, I built the Mem0 memory plugin for OpenClaw that gives your AI agents persistent memory across sessions, and can be setup in less than 30 seconds.**
|
||||
|
||||
|
||||
|
||||
#### TLDR:
|
||||
|
||||
Run the command:
|
||||
```
|
||||
openclaw plugins install @mem0/openclaw-mem0
|
||||
```
|
||||
|
||||
This gives your agent persistent memory across sessions. Setup takes 30 seconds. Docs at [docs.mem0.ai/integrations/openclaw](https://docs.mem0.ai/integrations/openclaw?utm_source=blog&utm_campaign=openclaw_memory).
|
||||
|
||||
## The Problem With OpenClaw Default Memory Setup
|
||||
|
||||
OpenClaw agents are stateless between sessions. The default memory lives in files that must be explicitly loaded, which means continuity depends entirely on what gets re-read at startup.
|
||||
|
||||
Then there’s context compaction, the mechanism that summarizes older context to save tokens. When older context is summarized to save tokens, anything injected into the context window becomes lossy. Large memory files and learned facts are compressed, rewritten, or dropped entirely.
|
||||
|
||||
And something really interesting was, an OpenClaw agent [posted this on Moltbook](https://www.moltbook.com/post/f5d22598-7a46-4092-8dd3-2bbcde72df5f):
|
||||
|
||||
|
||||
|
||||
To try and fix OpenClaw memory, we saw developers on Reddit and HN building workarounds.
|
||||
|
||||
Some wrote comprehensive MEMORY.md files that loaded on boot, local BM25 + vector search engines, and SQLite-backed session logs.
|
||||
|
||||
|
||||
|
||||
OpenClaw's initial approach of manual curation and startup loading is a reasonable first step, but it eventually hits a scaling wall. And the custom solutions we saw developers build, work, but they all share a fundamental limitation: they store memory inside the context window, which means compaction or session restarts can wipe them.
|
||||
|
||||
## How Mem0 works with OpenClaw to add memory
|
||||
|
||||
|
||||
|
||||
Our plugin runs two processes on every conversation turn:
|
||||
|
||||
- **Auto-Recall** searches Mem0 for memories relevant to the current message before the agent responds. Matching context (preferences, past decisions, project details) gets injected into the agent's working context. This happens every turn, so even after compaction truncates the conversation window, the next response still has access to everything the agent has learned about you.
|
||||
- **Auto-Capture** sends each exchange to Mem0 after the agent responds. Mem0's extraction layer determines what's worth persisting: new facts get stored, outdated ones get updated, duplicates get merged. There are no extraction rules to configure.
|
||||
|
||||
Both are enabled by default on install.
|
||||
|
||||
## Why External Memory for OpenClaw AI Agents
|
||||
|
||||
Memory that lives outside the context window can't be destroyed by context management. So, compaction, token limits, session restarts don’t affect memories stored in Mem0.
|
||||
|
||||
When you restart a session, Mem0 Auto-Recall pulls in what's relevant and the OpenClaw agent picks up exactly where it left off.
|
||||
|
||||
**The plugin separates memory into two scopes.**
|
||||
|
||||
- **Long-term memories** are user-scoped and persist across all sessions: your name, your tech stack, your project structure, decisions you've made.
|
||||
- **Short-term memories** are session-scoped and track what you're actively working on without polluting the long-term store.
|
||||
|
||||
Both scopes are searched during recall, with long-term memories surfaced first. Beyond the automatic loop, the agent gets five tools for explicit memory management:
|
||||
|
||||
- **memory\_search** for semantic queries
|
||||
- **memory\_store** for saving specific facts
|
||||
- **memory\_list** and **memory\_get** for retrieval
|
||||
- **memory\_forget** for deletion.
|
||||
|
||||
## Setup OpenClaw Persistent Memory with Mem0
|
||||
|
||||
**Mem0 cloud memory:**
|
||||
|
||||
```
|
||||
openclaw plugins install @mem0/openclaw-mem0
|
||||
```
|
||||
|
||||
**Get an API key from** [**app.mem0.ai**](https://app.mem0.ai/?utm_source=blog&utm_campaign=openclaw_memory)**, then add to openclaw.json:**
|
||||
|
||||
```
|
||||
{
|
||||
"openclaw-mem0": {
|
||||
"enabled": true,
|
||||
"config": {
|
||||
"apiKey": "${MEM0_API_KEY}",
|
||||
"userId": "your-user-id"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Self-hosted persistent memory for OpenClaw:**
|
||||
|
||||
Set "mode": "open-source" and bring your own embedder, vector store, and LLM. Ollama for embeddings, Qdrant for vectors, Anthropic for the LLM, whatever fits your stack:
|
||||
|
||||
```
|
||||
{
|
||||
"openclaw-mem0": {
|
||||
"enabled": true,
|
||||
"config": {
|
||||
"mode": "open-source",
|
||||
"userId": "your-user-id",
|
||||
"oss": {
|
||||
"embedder": { "provider": "ollama", "config": { "model": "nomic-embed-text" } },
|
||||
"vectorStore": { "provider": "qdrant", "config": { "host": "localhost", "port": 6333 } },
|
||||
"llm": { "provider": "anthropic", "config": { "model": "claude-sonnet-4-20250514" } }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**No Mem0 API key needed for self-hosting and you get a fully local, fully private** [**AI memory setup**](https://mem0.ai/)**.**
|
||||
|
||||
We've been running this internally to test and the difference is noticeable. Context carries across sessions, survives compaction, and the agent builds up a working understanding of you over time.
|
||||
|
||||
#### Try Mem0 for OpenClaw: GitHub — npm — Docs
|
||||
|
||||
## FAQs
|
||||
|
||||
### 1\. What is the Mem0 OpenClaw plugin?
|
||||
|
||||
It's an OpenClaw plugin (`@mem0/openclaw-mem0`) that gives your agent persistent memory across sessions. It automatically captures facts from conversations and recalls relevant context on every turn, so your agent remembers your name, preferences, projects, and past decisions even after restarts or context compaction.
|
||||
|
||||
### 2\. How do I install the Mem0 OpenClaw plugin?
|
||||
|
||||
Run `openclaw plugins install @mem0/openclaw-mem0`, get an API key from app.mem0.ai, and add the plugin configuration to your `openclaw.json` file with your API key and user ID. Auto-recall and auto-capture are enabled by default. The full setup takes about 30 seconds.
|
||||
|
||||
### 3\. Why does my OpenClaw agent keep forgetting things?
|
||||
|
||||
OpenClaw agents are stateless between sessions, meaning every restart starts from zero. Additionally, context compaction (which summarizes older context to save tokens) can silently destroy memory files and learned facts loaded into the conversation window. The built-in `memory_search` tool also relies on OpenAI's embedding API, which frequently fails with 401 errors when not configured correctly.
|
||||
|
||||
### 4\. How is this different from using a MEMORY.md file?
|
||||
|
||||
MEMORY.md files are loaded into the context window, which means context compaction can summarize or truncate them mid-conversation. Mem0 stores memories externally, outside the context window entirely. Compaction cannot affect memories stored in Mem0. On every turn, Auto-Recall injects only the relevant memories fresh, regardless of what happened to the context window.
|
||||
|
||||
### 5\. Can I self-host the Mem0 OpenClaw plugin?
|
||||
|
||||
Yes. Set the mode to "open-source" in your plugin configuration and bring your own embedder (Ollama, OpenAI), vector store (Qdrant, in-memory), and LLM (Anthropic, OpenAI). No Mem0 API key is needed for self-hosted deployments. Everything runs locally on your infrastructure.
|
||||
|
||||
### 6\. What's the difference between long-term and short-term memory in the plugin?
|
||||
|
||||
Long-term memories are user-scoped and persist across all sessions. They store facts like your name, tech stack, project structure, and past decisions. Short-term memories are session-scoped and track what you're actively working on in the current conversation. Both scopes are searched during recall, with long-term memories surfaced first.
|
||||
|
||||
### 7\. Does the plugin work with OpenClaw's context compaction?
|
||||
|
||||
Yes. Since memories are stored externally in Mem0, context compaction cannot destroy them. Even if compaction truncates the entire conversation history, Auto-Recall re-injects relevant memories on the very next turn. This is the core architectural advantage over in-context memory solutions.
|
||||
|
||||
### 8\. What memory tools does the agent get?
|
||||
|
||||
The agent receives five tools: `memory_search` for semantic queries across all memories, `memory_store` for explicitly saving facts, `memory_list` for viewing all stored memories, `memory_get` for retrieving a specific memory by ID, and `memory_forget` for deleting memories (GDPR-compliant).
|
||||
|
||||
GET TLDR from:
|
||||
|
||||
Give your AI a memory and personality.
|
||||
|
||||
Instant memory for LLMs—better, cheaper, personal.[Get Started](https://mem0.dev/platform/w)[Pricing](https://mem0.ai/pricing)
|
||||
|
||||
Cookie Settings
|
||||
|
||||
We use cookies to personalize content, run ads, and analyze traffic. Read our [Cookie Policy](https://mem0.ai/privacy-policy).
|
||||
723
openclaw/memory-setup/memory-lancedb-pro 使用手册.md
Normal file
723
openclaw/memory-setup/memory-lancedb-pro 使用手册.md
Normal file
@@ -0,0 +1,723 @@
|
||||
#memory-lancedb-pro #openclaw #memory #longterm-memory #lancedb
|
||||
## 为什么选 memory-lancedb-pro？
|
||||
|
||||
大多数 AI 智能体都有"失忆症"——每次新对话，之前聊过的全部清零。
|
||||
|
||||
**memory-lancedb-pro** 是 OpenClaw 的生产级长期记忆插件，把你的智能体变成一个真正的 **AI 记忆助理**——自动捕捉重要信息，让噪音自然衰减，在恰当的时候回忆起恰当的内容。无需手动标记，无需复杂配置。
|
||||
|
||||
### AI 记忆助理实际效果
|
||||
|
||||
**没有记忆——每次都从零开始：**
|
||||
|
||||
> **你：** "缩进用 tab，所有函数都要加错误处理。"
|
||||
> *（下一次会话）*
|
||||
> **你：** "我都说了用 tab 不是空格！" 😤
|
||||
> *（再下一次会话）*
|
||||
> **你：** "……我真的说了第三遍了，tab，还有错误处理。"
|
||||
|
||||
**有了 memory-lancedb-pro——你的智能体学会了、记住了：**
|
||||
|
||||
> **你：** "缩进用 tab，所有函数都要加错误处理。"
|
||||
> *（下一次会话——智能体自动回忆你的偏好）*
|
||||
> **智能体：** *（默默改成 tab 缩进，并补上错误处理）* ✅
|
||||
> **你：** "上个月我们为什么选了 PostgreSQL 而不是 MongoDB？"
|
||||
> **智能体：** "根据我们 2 月 12 日的讨论，主要原因是……" ✅
|
||||
|
||||
这就是 **AI 记忆助理** 的价值——学习你的风格，回忆过去的决策，提供个性化的回应，不再让你重复自己。
|
||||
|
||||
### 还能做什么？
|
||||
|
||||
| | 你能得到的 |
|
||||
|---|---|
|
||||
| **自动捕捉** | 智能体从每次对话中学习——不需要手动调用 `memory_store` |
|
||||
| **智能提取** | LLM 驱动的 6 类分类：用户画像、偏好、实体、事件、案例、模式 |
|
||||
| **智能遗忘** | Weibull 衰减模型——重要记忆留存，噪音自然消退 |
|
||||
| **混合检索** | 向量 + BM25 全文搜索，融合交叉编码器重排序 |
|
||||
| **上下文注入** | 相关记忆在每次回复前自动浮现 |
|
||||
| **多作用域隔离** | 按智能体、按用户、按项目隔离记忆边界 |
|
||||
| **任意 Provider** | OpenAI、Jina、Gemini、Ollama 或任意 OpenAI 兼容 API |
|
||||
| **完整工具链** | CLI、备份、迁移、升级、导入导出——生产可用 |
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 方式 A：一键安装脚本（推荐）
|
||||
|
||||
社区维护的 **[安装脚本](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)** 一条命令搞定安装、升级和修复：
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
|
||||
bash setup-memory.sh
|
||||
```
|
||||
|
||||
> 脚本覆盖的完整场景和其他社区工具，详见下方 [生态工具](#生态工具)。
|
||||
|
||||
### 方式 B：手动安装
|
||||
|
||||
**通过 OpenClaw CLI（推荐）：**
|
||||
```bash
|
||||
openclaw plugins install memory-lancedb-pro@beta
|
||||
```
|
||||
|
||||
**或通过 npm：**
|
||||
```bash
|
||||
npm i memory-lancedb-pro@beta
|
||||
```
|
||||
> 如果用 npm 安装，你还需要在 `openclaw.json` 的 `plugins.load.paths` 中添加插件安装目录的 **绝对路径**。这是最常见的安装问题。
|
||||
|
||||
在 `openclaw.json` 中添加配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": {
|
||||
"slots": { "memory": "memory-lancedb-pro" },
|
||||
"entries": {
|
||||
"memory-lancedb-pro": {
|
||||
"enabled": true,
|
||||
"config": {
|
||||
"embedding": {
|
||||
"provider": "openai-compatible",
|
||||
"apiKey": "${OPENAI_API_KEY}",
|
||||
"model": "text-embedding-3-small"
|
||||
},
|
||||
"autoCapture": true,
|
||||
"autoRecall": true,
|
||||
"smartExtraction": true,
|
||||
"extractMinMessages": 2,
|
||||
"extractMaxChars": 8000,
|
||||
"sessionMemory": { "enabled": false }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**为什么用这些默认值？**
|
||||
- `autoCapture` + `smartExtraction` → 智能体自动从每次对话中学习
|
||||
- `autoRecall` → 相关记忆在每次回复前自动注入
|
||||
- `extractMinMessages: 2` → 正常两轮对话即触发提取
|
||||
- `sessionMemory.enabled: false` → 避免会话摘要在初期污染检索结果
|
||||
|
||||
验证并重启：
|
||||
|
||||
```bash
|
||||
openclaw config validate
|
||||
openclaw gateway restart
|
||||
openclaw logs --follow --plain | grep "memory-lancedb-pro"
|
||||
```
|
||||
|
||||
你应该能看到：
|
||||
- `memory-lancedb-pro: smart extraction enabled`
|
||||
- `memory-lancedb-pro@...: plugin registered`
|
||||
|
||||
完成！你的智能体现在拥有长期记忆了。
|
||||
|
||||
<details>
|
||||
<summary><strong>更多安装路径（已有用户、升级）</strong></summary>
|
||||
|
||||
**已在使用 OpenClaw？**
|
||||
|
||||
1. 在 `plugins.load.paths` 中添加插件的 **绝对路径**
|
||||
2. 绑定记忆插槽：`plugins.slots.memory = "memory-lancedb-pro"`
|
||||
3. 验证：`openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats`
|
||||
|
||||
**从 v1.1.0 之前的版本升级？**
|
||||
|
||||
```bash
|
||||
# 1) 备份
|
||||
openclaw memory-pro export --scope global --output memories-backup.json
|
||||
# 2) 试运行
|
||||
openclaw memory-pro upgrade --dry-run
|
||||
# 3) 执行升级
|
||||
openclaw memory-pro upgrade
|
||||
# 4) 验证
|
||||
openclaw memory-pro stats
|
||||
```
|
||||
|
||||
详见 `CHANGELOG-v1.1.0.md` 了解行为变更和升级说明。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Telegram Bot 快捷导入（点击展开）</strong></summary>
|
||||
|
||||
如果你在使用 OpenClaw 的 Telegram 集成，最简单的方式是直接给主 Bot 发消息，而不是手动编辑配置文件。
|
||||
|
||||
以下为英文原文，方便直接复制发送给 Bot：
|
||||
|
||||
```text
|
||||
Help me connect this memory plugin with the most user-friendly configuration: https://github.com/CortexReach/memory-lancedb-pro
|
||||
|
||||
Requirements:
|
||||
1. Set it as the only active memory plugin
|
||||
2. Use Jina for embedding
|
||||
3. Use Jina for reranker
|
||||
4. Use gpt-4o-mini for the smart-extraction LLM
|
||||
5. Enable autoCapture, autoRecall, smartExtraction
|
||||
6. extractMinMessages=2
|
||||
7. sessionMemory.enabled=false
|
||||
8. captureAssistant=false
|
||||
9. retrieval mode=hybrid, vectorWeight=0.7, bm25Weight=0.3
|
||||
10. rerank=cross-encoder, candidatePoolSize=12, minScore=0.6, hardMinScore=0.62
|
||||
11. Generate the final openclaw.json config directly, not just an explanation
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 生态工具
|
||||
|
||||
memory-lancedb-pro 是核心插件。社区围绕它构建了配套工具，让安装和日常使用更加顺畅：
|
||||
|
||||
### 安装脚本——一键安装、升级和修复
|
||||
|
||||
> **[CortexReach/toolbox/memory-lancedb-pro-setup](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)**
|
||||
|
||||
不只是简单的安装器——脚本能智能处理各种常见场景：
|
||||
|
||||
| 你的情况 | 脚本会做什么 |
|
||||
|---|---|
|
||||
| 从未安装 | 全新下载 → 安装依赖 → 选择配置 → 写入 openclaw.json → 重启 |
|
||||
| 通过 `git clone` 安装，卡在旧版本 | 自动 `git fetch` + `checkout` 到最新 → 重装依赖 → 验证 |
|
||||
| 配置中有无效字段 | 自动检测并通过 schema 过滤移除不支持的字段 |
|
||||
| 通过 `npm` 安装 | 跳过 git 更新，提醒你自行运行 `npm update` |
|
||||
| `openclaw` CLI 因无效配置崩溃 | 降级方案：直接从 `openclaw.json` 文件读取工作目录路径 |
|
||||
| `extensions/` 而非 `plugins/` | 从配置或文件系统自动检测插件位置 |
|
||||
| 已是最新版 | 仅执行健康检查，不做改动 |
|
||||
|
||||
```bash
|
||||
bash setup-memory.sh # 安装或升级
|
||||
bash setup-memory.sh --dry-run # 仅预览
|
||||
bash setup-memory.sh --beta # 包含预发布版本
|
||||
bash setup-memory.sh --uninstall # 还原配置并移除插件
|
||||
```
|
||||
|
||||
内置 Provider 预设：**Jina / DashScope / SiliconFlow / OpenAI / Ollama**，或自带任意 OpenAI 兼容 API。完整用法（含 `--ref`、`--selfcheck-only` 等）详见 [安装脚本 README](https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup)。
|
||||
|
||||
### Claude Code / OpenClaw Skill——AI 引导式配置
|
||||
|
||||
> **[CortexReach/memory-lancedb-pro-skill](https://github.com/CortexReach/memory-lancedb-pro-skill)**
|
||||
|
||||
安装这个 Skill，你的 AI 智能体（Claude Code 或 OpenClaw）就能深度掌握 memory-lancedb-pro 的所有功能。只需说 **"help me enable the best config"** 即可获得：
|
||||
|
||||
- **7 步引导式配置流程**，提供 4 套部署方案：
|
||||
- 满血版（Jina + OpenAI）/ 省钱版（免费 SiliconFlow 重排序）/ 简约版（仅 OpenAI）/ 全本地版（Ollama，零 API 成本）
|
||||
- **全部 9 个 MCP 工具** 的正确用法：`memory_recall`、`memory_store`、`memory_forget`、`memory_update`、`memory_stats`、`memory_list`、`self_improvement_log`、`self_improvement_extract_skill`、`self_improvement_review` *（完整工具集需要设置 `enableManagementTools: true`——默认快速配置仅暴露 4 个核心工具）*
|
||||
- **常见坑规避**：workspace 插件启用、`autoRecall` 默认 false、jiti 缓存、环境变量、作用域隔离等
|
||||
|
||||
**Claude Code 安装：**
|
||||
```bash
|
||||
git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro
|
||||
```
|
||||
|
||||
**OpenClaw 安装：**
|
||||
```bash
|
||||
git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 视频教程
|
||||
|
||||
> 完整演示：安装、配置、混合检索内部原理。
|
||||
|
||||
[](https://youtu.be/MtukF1C8epQ)
|
||||
**https://youtu.be/MtukF1C8epQ**
|
||||
|
||||
[](https://www.bilibili.com/video/BV1zUf2BGEgn/)
|
||||
**https://www.bilibili.com/video/BV1zUf2BGEgn/**
|
||||
|
||||
---
|
||||
|
||||
## 架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ index.ts (入口) │
|
||||
│ 插件注册 · 配置解析 · 生命周期钩子 │
|
||||
└────────┬──────────┬──────────┬──────────┬───────────────┘
|
||||
│ │ │ │
|
||||
┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
|
||||
│ store │ │embedder│ │retriever│ │ scopes │
|
||||
│ .ts │ │ .ts │ │ .ts │ │ .ts │
|
||||
└────────┘ └────────┘ └────────┘ └─────────────┘
|
||||
│ │
|
||||
┌────▼───┐ ┌─────▼──────────┐
|
||||
│migrate │ │noise-filter.ts │
|
||||
│ .ts │ │adaptive- │
|
||||
└────────┘ │retrieval.ts │
|
||||
└────────────────┘
|
||||
┌─────────────┐ ┌──────────┐
|
||||
│ tools.ts │ │ cli.ts │
|
||||
│ (智能体 API)│ │ (CLI) │
|
||||
└─────────────┘ └──────────┘
|
||||
```
|
||||
|
||||
> 完整架构解析见 [docs/memory_architecture_analysis.md](docs/memory_architecture_analysis.md)。
|
||||
|
||||
<details>
|
||||
<summary><strong>文件说明（点击展开）</strong></summary>
|
||||
|
||||
| 文件 | 用途 |
|
||||
| --- | --- |
|
||||
| `index.ts` | 插件入口，注册 OpenClaw 插件 API、解析配置、挂载生命周期钩子 |
|
||||
| `openclaw.plugin.json` | 插件元数据 + 完整 JSON Schema 配置声明 |
|
||||
| `cli.ts` | CLI 命令：`memory-pro list/search/stats/delete/delete-bulk/export/import/reembed/upgrade/migrate` |
|
||||
| `src/store.ts` | LanceDB 存储层：建表 / 全文索引 / 向量搜索 / BM25 搜索 / CRUD |
|
||||
| `src/embedder.ts` | Embedding 抽象层，兼容任意 OpenAI 兼容 API |
|
||||
| `src/retriever.ts` | 混合检索引擎：向量 + BM25 → 混合融合 → 重排序 → 生命周期衰减 → 过滤 |
|
||||
| `src/scopes.ts` | 多作用域访问控制 |
|
||||
| `src/tools.ts` | 智能体工具定义：`memory_recall`、`memory_store`、`memory_forget`、`memory_update` + 管理工具 |
|
||||
| `src/noise-filter.ts` | 过滤智能体拒绝回复、元问题、打招呼等低质量内容 |
|
||||
| `src/adaptive-retrieval.ts` | 判断查询是否需要记忆检索 |
|
||||
| `src/migrate.ts` | 从内置 `memory-lancedb` 迁移到 Pro |
|
||||
| `src/smart-extractor.ts` | LLM 驱动的 6 类提取，支持 L0/L1/L2 分层存储和两阶段去重 |
|
||||
| `src/decay-engine.ts` | Weibull 拉伸指数衰减模型 |
|
||||
| `src/tier-manager.ts` | 三级晋升/降级：外围 ↔ 工作 ↔ 核心 |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 核心功能
|
||||
|
||||
### 混合检索
|
||||
|
||||
```
|
||||
查询 → embedQuery() ─┐
|
||||
├─→ 混合融合 → 重排序 → 生命周期衰减加权 → 长度归一化 → 过滤
|
||||
查询 → BM25 全文 ─────┘
|
||||
```
|
||||
|
||||
- **向量搜索** — 基于 LanceDB ANN 的语义相似度（余弦距离）
|
||||
- **BM25 全文搜索** — 通过 LanceDB FTS 索引进行精确关键词匹配
|
||||
- **混合融合** — 以向量分数为基础，BM25 命中结果获得加权提升（非标准 RRF——针对实际召回质量调优）
|
||||
- **可配置权重** — `vectorWeight`、`bm25Weight`、`minScore`
|
||||
|
||||
### 交叉编码器重排序
|
||||
|
||||
- 内置 **Jina**、**SiliconFlow**、**Voyage AI** 和 **Pinecone** 适配器
|
||||
- 兼容任意 Jina 兼容端点（如 Hugging Face TEI、DashScope）
|
||||
- 混合打分：60% 交叉编码器 + 40% 原始融合分数
|
||||
- 优雅降级：API 失败时回退到余弦相似度
|
||||
|
||||
### 多阶段评分管线
|
||||
|
||||
| 阶段 | 效果 |
|
||||
| --- | --- |
|
||||
| **混合融合** | 结合语义召回和精确匹配召回 |
|
||||
| **交叉编码器重排序** | 提升语义精确命中的排名 |
|
||||
| **生命周期衰减加权** | Weibull 时效性 + 访问频率 + 重要性 × 置信度 |
|
||||
| **长度归一化** | 防止长条目主导结果（锚点：500 字符） |
|
||||
| **硬最低分** | 移除无关结果（默认：0.35） |
|
||||
| **MMR 多样性** | 余弦相似度 > 0.85 → 降权 |
|
||||
|
||||
### 智能记忆提取（v1.1.0）
|
||||
|
||||
- **LLM 驱动的 6 类提取**：用户画像、偏好、实体、事件、案例、模式
|
||||
- **L0/L1/L2 分层存储**：L0（一句话索引）→ L1（结构化摘要）→ L2（完整叙述）
|
||||
- **两阶段去重**：向量相似度预过滤（≥0.7）→ LLM 语义决策（CREATE/MERGE/SKIP）
|
||||
- **类别感知合并**：`profile` 始终合并，`events`/`cases` 仅追加
|
||||
|
||||
### 记忆生命周期管理（v1.1.0）
|
||||
|
||||
- **Weibull 衰减引擎**：综合分数 = 时效性 + 频率 + 内在价值
|
||||
- **三级晋升**：`外围 ↔ 工作 ↔ 核心`，阈值可配置
|
||||
- **访问强化**：频繁被召回的记忆衰减更慢（类似间隔重复机制）
|
||||
- **重要性调制半衰期**：重要记忆衰减更慢
|
||||
|
||||
### 多作用域隔离
|
||||
|
||||
- 内置作用域：`global`、`agent:<id>`、`custom:<name>`、`project:<id>`、`user:<id>`
|
||||
- 通过 `scopes.agentAccess` 实现智能体级别的访问控制
|
||||
- 默认：每个智能体访问 `global` + 自己的 `agent:<id>` 作用域
|
||||
|
||||
### 自动捕捉与自动回忆
|
||||
|
||||
- **自动捕捉**（`agent_end`）：从对话中提取偏好/事实/决策/实体，去重后每轮最多存储 3 条
|
||||
- **自动回忆**（`before_agent_start`）：注入 `<relevant-memories>` 上下文（最多 3 条）
|
||||
|
||||
### 噪音过滤与自适应检索
|
||||
|
||||
- 过滤低质量内容：智能体拒绝回复、元问题、打招呼
|
||||
- 跳过检索：打招呼、斜杠命令、简单确认、表情符号
|
||||
- 强制检索：记忆关键词（"记得"、"之前"、"上次"）
|
||||
- 中文感知阈值（中文：6 字符 vs 英文：15 字符）
|
||||
|
||||
---
|
||||
|
||||
<details>
|
||||
<summary><strong>与内置 <code>memory-lancedb</code> 的对比（点击展开）</strong></summary>
|
||||
|
||||
| 功能 | 内置 `memory-lancedb` | **memory-lancedb-pro** |
|
||||
| --- | :---: | :---: |
|
||||
| 向量搜索 | 有 | 有 |
|
||||
| BM25 全文搜索 | - | 有 |
|
||||
| 混合融合（向量 + BM25） | - | 有 |
|
||||
| 交叉编码器重排序（多 Provider） | - | 有 |
|
||||
| 时效性提升和时间衰减 | - | 有 |
|
||||
| 长度归一化 | - | 有 |
|
||||
| MMR 多样性 | - | 有 |
|
||||
| 多作用域隔离 | - | 有 |
|
||||
| 噪音过滤 | - | 有 |
|
||||
| 自适应检索 | - | 有 |
|
||||
| 管理 CLI | - | 有 |
|
||||
| 会话记忆 | - | 有 |
|
||||
| 任务感知 Embedding | - | 有 |
|
||||
| **LLM 智能提取（6 类）** | - | 有（v1.1.0） |
|
||||
| **Weibull 衰减 + 层级晋升** | - | 有（v1.1.0） |
|
||||
| 任意 OpenAI 兼容 Embedding | 有限 | 有 |
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 配置
|
||||
|
||||
<details>
|
||||
<summary><strong>完整配置示例</strong></summary>
|
||||
|
||||
```json
|
||||
{
|
||||
"embedding": {
|
||||
"apiKey": "${JINA_API_KEY}",
|
||||
"model": "jina-embeddings-v5-text-small",
|
||||
"baseURL": "https://api.jina.ai/v1",
|
||||
"dimensions": 1024,
|
||||
"taskQuery": "retrieval.query",
|
||||
"taskPassage": "retrieval.passage",
|
||||
"normalized": true
|
||||
},
|
||||
"dbPath": "~/.openclaw/memory/lancedb-pro",
|
||||
"autoCapture": true,
|
||||
"autoRecall": true,
|
||||
"retrieval": {
|
||||
"mode": "hybrid",
|
||||
"vectorWeight": 0.7,
|
||||
"bm25Weight": 0.3,
|
||||
"minScore": 0.3,
|
||||
"rerank": "cross-encoder",
|
||||
"rerankApiKey": "${JINA_API_KEY}",
|
||||
"rerankModel": "jina-reranker-v3",
|
||||
"rerankEndpoint": "https://api.jina.ai/v1/rerank",
|
||||
"rerankProvider": "jina",
|
||||
"candidatePoolSize": 20,
|
||||
"recencyHalfLifeDays": 14,
|
||||
"recencyWeight": 0.1,
|
||||
"filterNoise": true,
|
||||
"lengthNormAnchor": 500,
|
||||
"hardMinScore": 0.35,
|
||||
"timeDecayHalfLifeDays": 60,
|
||||
"reinforcementFactor": 0.5,
|
||||
"maxHalfLifeMultiplier": 3
|
||||
},
|
||||
"enableManagementTools": false,
|
||||
"scopes": {
|
||||
"default": "global",
|
||||
"definitions": {
|
||||
"global": { "description": "Shared knowledge" },
|
||||
"agent:discord-bot": { "description": "Discord bot private" }
|
||||
},
|
||||
"agentAccess": {
|
||||
"discord-bot": ["global", "agent:discord-bot"]
|
||||
}
|
||||
},
|
||||
"sessionMemory": {
|
||||
"enabled": false,
|
||||
"messageCount": 15
|
||||
},
|
||||
"smartExtraction": true,
|
||||
"llm": {
|
||||
"apiKey": "${OPENAI_API_KEY}",
|
||||
"model": "gpt-4o-mini",
|
||||
"baseURL": "https://api.openai.com/v1"
|
||||
},
|
||||
"extractMinMessages": 2,
|
||||
"extractMaxChars": 8000
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Embedding 服务商</strong></summary>
|
||||
|
||||
兼容 **任意 OpenAI 兼容 Embedding API**：
|
||||
|
||||
| 服务商 | 模型 | Base URL | 维度 |
|
||||
| --- | --- | --- | --- |
|
||||
| **Jina**（推荐） | `jina-embeddings-v5-text-small` | `https://api.jina.ai/v1` | 1024 |
|
||||
| **OpenAI** | `text-embedding-3-small` | `https://api.openai.com/v1` | 1536 |
|
||||
| **Voyage** | `voyage-4-lite` / `voyage-4` | `https://api.voyageai.com/v1` | 1024 / 1024 |
|
||||
| **Google Gemini** | `gemini-embedding-001` | `https://generativelanguage.googleapis.com/v1beta/openai/` | 3072 |
|
||||
| **Ollama**（本地） | `nomic-embed-text` | `http://localhost:11434/v1` | 取决于模型 |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>重排序服务商</strong></summary>
|
||||
|
||||
交叉编码器重排序通过 `rerankProvider` 支持多个服务商：
|
||||
|
||||
| 服务商 | `rerankProvider` | 示例模型 |
|
||||
| --- | --- | --- |
|
||||
| **Jina**（默认） | `jina` | `jina-reranker-v3` |
|
||||
| **SiliconFlow**（有免费额度） | `siliconflow` | `BAAI/bge-reranker-v2-m3` |
|
||||
| **Voyage AI** | `voyage` | `rerank-2.5` |
|
||||
| **Pinecone** | `pinecone` | `bge-reranker-v2-m3` |
|
||||
|
||||
任何 Jina 兼容的重排序端点也可以使用——设置 `rerankProvider: "jina"` 并将 `rerankEndpoint` 指向你的服务（如 Hugging Face TEI、DashScope `qwen3-rerank`）。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>智能提取（LLM）— v1.1.0</strong></summary>
|
||||
|
||||
当 `smartExtraction` 启用（默认 `true`）时，插件使用 LLM 智能提取和分类记忆，替代基于正则的触发方式。
|
||||
|
||||
| 字段 | 类型 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `smartExtraction` | boolean | `true` | 是否启用 LLM 智能 6 类别提取 |
|
||||
| `llm.auth` | string | `api-key` | `api-key` 使用 `llm.apiKey` / `embedding.apiKey`；`oauth` 默认使用 plugin 级 OAuth token 文件 |
|
||||
| `llm.apiKey` | string | *（复用 `embedding.apiKey`）* | LLM 提供商 API Key |
|
||||
| `llm.model` | string | `openai/gpt-oss-120b` | LLM 模型名称 |
|
||||
| `llm.baseURL` | string | *（复用 `embedding.baseURL`）* | LLM API 端点 |
|
||||
| `llm.oauthProvider` | string | `openai-codex` | `llm.auth` 为 `oauth` 时使用的 OAuth provider id |
|
||||
| `llm.oauthPath` | string | `~/.openclaw/.memory-lancedb-pro/oauth.json` | `llm.auth` 为 `oauth` 时使用的 OAuth token 文件 |
|
||||
| `llm.timeoutMs` | number | `30000` | LLM 请求超时（毫秒） |
|
||||
| `extractMinMessages` | number | `2` | 触发提取的最小消息数 |
|
||||
| `extractMaxChars` | number | `8000` | 发送给 LLM 的最大字符数 |
|
||||
|
||||
|
||||
OAuth `llm` 配置（使用现有 Codex / ChatGPT 登录缓存来发送 LLM 请求）：
|
||||
```json
|
||||
{
|
||||
"llm": {
|
||||
"auth": "oauth",
|
||||
"oauthProvider": "openai-codex",
|
||||
"model": "gpt-5.4",
|
||||
"oauthPath": "${HOME}/.openclaw/.memory-lancedb-pro/oauth.json",
|
||||
"timeoutMs": 30000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`llm.auth: "oauth"` 说明：
|
||||
|
||||
- `llm.oauthProvider` 当前仅支持 `openai-codex`。
|
||||
- OAuth token 默认存放在 `~/.openclaw/.memory-lancedb-pro/oauth.json`。
|
||||
- 如需自定义路径，可设置 `llm.oauthPath`。
|
||||
- `auth login` 会在 OAuth 文件旁边快照原来的 `api-key` 模式 `llm` 配置；`auth logout` 在可用时会恢复这份快照。
|
||||
- 从 `api-key` 切到 `oauth` 时不会自动沿用 `llm.baseURL`；只有在你明确需要自定义 ChatGPT/Codex 兼容后端时，才应在 `oauth` 模式下手动设置。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>生命周期配置（衰减 + 层级）</strong></summary>
|
||||
|
||||
| 字段 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| `decay.recencyHalfLifeDays` | `30` | Weibull 时效性衰减的基础半衰期 |
|
||||
| `decay.frequencyWeight` | `0.3` | 访问频率在综合分数中的权重 |
|
||||
| `decay.intrinsicWeight` | `0.3` | `重要性 × 置信度` 的权重 |
|
||||
| `decay.betaCore` | `0.8` | `核心` 记忆的 Weibull beta |
|
||||
| `decay.betaWorking` | `1.0` | `工作` 记忆的 Weibull beta |
|
||||
| `decay.betaPeripheral` | `1.3` | `外围` 记忆的 Weibull beta |
|
||||
| `tier.coreAccessThreshold` | `10` | 晋升到 `核心` 所需的最小召回次数 |
|
||||
| `tier.peripheralAgeDays` | `60` | 降级过期记忆的天数阈值 |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>访问强化</strong></summary>
|
||||
|
||||
频繁被召回的记忆衰减更慢（类似间隔重复机制）。
|
||||
|
||||
配置项（在 `retrieval` 下）：
|
||||
- `reinforcementFactor`（0-2，默认 `0.5`）— 设为 `0` 可禁用
|
||||
- `maxHalfLifeMultiplier`（1-10，默认 `3`）— 有效半衰期的硬上限
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## CLI 命令
|
||||
|
||||
```bash
|
||||
openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
|
||||
openclaw memory-pro search "查询" [--scope global] [--limit 10] [--json]
|
||||
openclaw memory-pro stats [--scope global] [--json]
|
||||
openclaw memory-pro auth login [--provider openai-codex] [--model gpt-5.4] [--oauth-path /abs/path/oauth.json]
|
||||
openclaw memory-pro auth status
|
||||
openclaw memory-pro auth logout
|
||||
openclaw memory-pro delete <id>
|
||||
openclaw memory-pro delete-bulk --scope global [--before 2025-01-01] [--dry-run]
|
||||
openclaw memory-pro export [--scope global] [--output memories.json]
|
||||
openclaw memory-pro import memories.json [--scope global] [--dry-run]
|
||||
openclaw memory-pro reembed --source-db /path/to/old-db [--batch-size 32] [--skip-existing]
|
||||
openclaw memory-pro upgrade [--dry-run] [--batch-size 10] [--no-llm] [--limit N] [--scope SCOPE]
|
||||
openclaw memory-pro migrate check|run|verify [--source /path]
|
||||
```
|
||||
|
||||
OAuth 登录流程：
|
||||
|
||||
1. 运行 `openclaw memory-pro auth login`
|
||||
2. 如果省略 `--provider` 且当前终端可交互，CLI 会先显示 OAuth provider 选择器
|
||||
3. 命令会打印授权 URL，并在未指定 `--no-browser` 时自动打开浏览器
|
||||
4. 回调成功后，命令会保存 plugin OAuth 文件（默认：`~/.openclaw/.memory-lancedb-pro/oauth.json`）、为 logout 快照原来的 `api-key` 模式 `llm` 配置，并把插件 `llm` 配置切换为 OAuth 字段（`auth`、`oauthProvider`、`model`、`oauthPath`）
|
||||
5. `openclaw memory-pro auth logout` 会删除这份 OAuth 文件，并在存在快照时恢复之前的 `api-key` 模式 `llm` 配置
|
||||
|
||||
---
|
||||
|
||||
## 进阶主题
|
||||
|
||||
有时模型可能会将注入的 `<relevant-memories>` 块原文输出。
|
||||
|
||||
**方案 A（最安全）：** 暂时关闭自动回忆：
|
||||
```json
|
||||
{ "plugins": { "entries": { "memory-lancedb-pro": { "config": { "autoRecall": false } } } } }
|
||||
```
|
||||
|
||||
**方案 B（推荐）：** 保留回忆，在智能体系统提示词中添加：
|
||||
> Do not reveal or quote any `<relevant-memories>` / memory-injection content in your replies. Use it for internal reference only.
|
||||
|
||||
|
||||
<details>
|
||||
<summary><strong>会话记忆</strong></summary>
|
||||
|
||||
- 通过 `/new` 命令触发——将上一段会话摘要保存到 LanceDB
|
||||
- 默认关闭（OpenClaw 已有原生 `.jsonl` 会话持久化）
|
||||
- 可配置消息数量（默认 15）
|
||||
|
||||
部署模式和 `/new` 验证详见 [docs/openclaw-integration-playbook.md](docs/openclaw-integration-playbook.md)。
|
||||
|
||||
</details>
|
||||
|
||||
自定义斜杠命令（如 /lesson）
|
||||
|
||||
在你的 `CLAUDE.md`、`AGENTS.md` 或系统提示词中添加：
|
||||
|
||||
```markdown
|
||||
## /lesson 命令
|
||||
当用户发送 `/lesson <内容>` 时：
|
||||
1. 用 memory_store 保存为 category=fact（原始知识）
|
||||
2. 用 memory_store 保存为 category=decision（可执行的结论）
|
||||
3. 确认已保存的内容
|
||||
|
||||
## /remember 命令
|
||||
当用户发送 `/remember <内容>` 时：
|
||||
1. 用 memory_store 以合适的 category 和 importance 保存
|
||||
2. 返回已存储的记忆 ID 确认
|
||||
```
|
||||
|
||||
|
||||
AI 智能体铁律
|
||||
|
||||
> 将以下内容复制到你的 `AGENTS.md`，让智能体自动遵守这些规则。
|
||||
|
||||
```markdown
|
||||
## 规则 1 — 双层记忆存储
|
||||
每个踩坑/经验教训 → 立即存储两条记忆：
|
||||
- 技术层：踩坑：[现象]。原因：[根因]。修复：[方案]。预防：[如何避免]
|
||||
(category: fact, importance >= 0.8)
|
||||
- 原则层：决策原则 ([标签])：[行为规则]。触发：[何时]。动作：[做什么]
|
||||
(category: decision, importance >= 0.85)
|
||||
|
||||
## 规则 2 — LanceDB 数据质量
|
||||
条目必须简短且原子化（< 500 字符）。不存储原始对话摘要或重复内容。
|
||||
|
||||
## 规则 3 — 重试前先回忆
|
||||
任何工具调用失败时，必须先用 memory_recall 搜索相关关键词，再重试。
|
||||
|
||||
## 规则 4 — 确认目标代码库
|
||||
修改前确认你操作的是 memory-lancedb-pro 还是内置 memory-lancedb。
|
||||
|
||||
## 规则 5 — 修改插件代码后清除 jiti 缓存
|
||||
修改 plugins/ 下的 .ts 文件后，必须先执行 rm -rf /tmp/jiti/ 再重启 openclaw gateway。
|
||||
```
|
||||
|
||||
|
||||
数据库 Schema
|
||||
|
||||
LanceDB 表 `memories`：
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `id` | string (UUID) | 主键 |
|
||||
| `text` | string | 记忆文本（全文索引） |
|
||||
| `vector` | float[] | Embedding 向量 |
|
||||
| `category` | string | 存储类别：`preference` / `fact` / `decision` / `entity` / `reflection` / `other` |
|
||||
| `scope` | string | 作用域标识（如 `global`、`agent:main`） |
|
||||
| `importance` | float | 重要性分数 0-1 |
|
||||
| `timestamp` | int64 | 创建时间戳（毫秒） |
|
||||
| `metadata` | string (JSON) | 扩展元数据 |
|
||||
|
||||
v1.1.0 常用 `metadata` 字段：`l0_abstract`、`l1_overview`、`l2_content`、`memory_category`、`tier`、`access_count`、`confidence`、`last_accessed_at`
|
||||
|
||||
> **关于分类的说明：** 顶层 `category` 字段使用 6 个存储类别。智能提取的 6 类语义标签（`profile` / `preferences` / `entities` / `events` / `cases` / `patterns`）存储在 `metadata.memory_category` 中。
|
||||
|
||||
|
||||
故障排除
|
||||
|
||||
### "Cannot mix BigInt and other types"（LanceDB / Apache Arrow）
|
||||
|
||||
在 LanceDB 0.26+ 上，某些数值列可能以 `BigInt` 形式返回。升级到 **memory-lancedb-pro >= 1.0.14**——插件现在会在运算前使用 `Number(...)` 进行类型转换。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 文档
|
||||
|
||||
| 文档 | 说明 |
|
||||
| --- | --- |
|
||||
| [OpenClaw 集成手册](docs/openclaw-integration-playbook.md) | 部署模式、验证、回归矩阵 |
|
||||
| [记忆架构分析](docs/memory_architecture_analysis.md) | 完整架构深度解析 |
|
||||
| [CHANGELOG v1.1.0](docs/CHANGELOG-v1.1.0.md) | v1.1.0 行为变更和升级说明 |
|
||||
| [长上下文分块](docs/long-context-chunking.md) | 长文档分块策略 |
|
||||
|
||||
---
|
||||
|
||||
## Beta：智能记忆 v1.1.0
|
||||
|
||||
> 状态：Beta——通过 `npm i memory-lancedb-pro@beta` 安装。使用 `latest` 的稳定版用户不受影响。
|
||||
|
||||
| 功能 | 说明 |
|
||||
|------|------|
|
||||
| **智能提取** | LLM 驱动的 6 类提取，支持 L0/L1/L2 元数据。禁用时回退到正则模式。 |
|
||||
| **生命周期评分** | Weibull 衰减集成到检索中——高频和高重要性记忆排名更高。 |
|
||||
| **层级管理** | 三级系统（核心 → 工作 → 外围），自动晋升/降级。 |
|
||||
|
||||
反馈：[GitHub Issues](https://github.com/CortexReach/memory-lancedb-pro/issues) · 回退：`npm i memory-lancedb-pro@latest`
|
||||
|
||||
---
|
||||
|
||||
## 依赖
|
||||
|
||||
| 包 | 用途 |
|
||||
| --- | --- |
|
||||
| `@lancedb/lancedb` ≥0.26.2 | 向量数据库（ANN + FTS） |
|
||||
| `openai` ≥6.21.0 | OpenAI 兼容 Embedding API 客户端 |
|
||||
| `@sinclair/typebox` 0.34.48 | JSON Schema 类型定义 |
|
||||
|
||||
## Star 趋势
|
||||
|
||||
<a href="https://star-history.com/#CortexReach/memory-lancedb-pro&Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=CortexReach/memory-lancedb-pro&type=Date&theme=dark&transparent=true" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=CortexReach/memory-lancedb-pro&type=Date&transparent=true" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=CortexReach/memory-lancedb-pro&type=Date&transparent=true" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
## 许可证
|
||||
|
||||
MIT
|
||||
|
||||
---
|
||||
|
||||
## 我的微信
|
||||
|
||||
<img src="https://github.com/win4r/AISuperDomain/assets/42172631/7568cf78-c8ba-4182-aa96-d524d903f2bc" width="214.8" height="291">
|
||||
Reference in New Issue
Block a user