Add: AI agents structure article and memory-lancedb-pro guide

This commit is contained in:
2026-03-25 15:37:23 +08:00
parent e8ae7fe1d0
commit ee7778036f
3 changed files with 683 additions and 0 deletions

View File

@@ -0,0 +1,116 @@
I run 5 AI agents on Claude Code. Here's how I structure the CLAUDE.md and .claude/ directory to keep each one focused.
I've been building an ecosystem of AI agents using Claude Code and Preemptively Codex, each one is just a directory with a CLAUDE.md file and some config. After a lot of trial and error, I've landed on patterns that actually work. Figured I'd share what I've learned about structuring these files.
Each agent lives in its own directory under ~/Documents/:
~/Documents/
├── planner/ # Executive function, routing, accountability
├── content/ # Content pipeline
├── youtube/ # YouTube production (scripting, SEO, metrics)
├── life/ # Personal domains (health, finance, energy)
└── control-center/ # Dashboard, database, API
Every agent follows the same template structure:
agent-name/
├── CLAUDE.md # Identity + mission + capabilities
├── .claude/
│ ├── rules/ # Auto-loaded context (always-on)
│ └── skills/ # On-demand workflows
├── inbox/ # Input from other agents
├── outputs/ # Generated output
└── archive/ # Nothing gets deleted without archiving
The key insight: rules/ vs skills/
This is the thing that took me the longest to figure out.
.claude/rules/ files are loaded automatically at the start of every session. Claude reads them as part of its context window. This is where you put things the agent needs to know always — its scope, business context, how it should behave.
.claude/skills/ files are on-demand. They only load when you invoke them with /skill-name. This is where you put specific workflows like multi-step processes, templates, structured routines.
Why this matters: Rules files load into your context window at session start and stay there. Claude Code uses prompt caching so repeated content isn't billed at full price each turn, but large rules files still increase context pressure and can cause response degradation. You're carrying that weight every interaction whether you need it or not. With skills, only the name and description live in context by default; the full workflow loads on-demand, either when you call it or when Claude decides it's relevant. And this sent me down a rabbit hole into how token usage and context costs actually work.
• Rules (always-on): Scope boundaries, business context, routing logic, naming conventions — things that affect every decision
Rules (always-on): Scope boundaries, business context, routing logic, naming conventions — things that affect every decision
• Skills (on-demand): Step-by-step workflows, templates, batch operations. Things you do occasionally
(Note: skill descriptions are always in context so Claude knows what's available; only the full content is on-demand)
Skills (on-demand): Step-by-step workflows, templates, batch operations. Things you do occasionally (Note: skill descriptions are always in context so Claude knows what's available; only the full content is on-demand)
I try to keep CLAUDE.md under 120 lines. It covers:
• Identity (2-3 lines): who this agent is and what it does
Identity (2-3 lines): who this agent is and what it does
• Current phase (2-3 lines): what we're working on right now
Current phase (2-3 lines): what we're working on right now
• Core capabilities (10-15 lines): what skills are available, what it can do
Core capabilities (10-15 lines): what skills are available, what it can do
• Key locations (10-15 lines): file paths it needs to reference
Key locations (10-15 lines): file paths it needs to reference
• What's been built (10-20 lines): history of completed work
What's been built (10-20 lines): history of completed work
• What's next (5-10 lines): immediate priorities
What's next (5-10 lines): immediate priorities
• Principles (5-10 lines): behavioral guardrails
Principles (5-10 lines): behavioral guardrails
The biggest mistake I made early on was cramming everything into CLAUDE.md. It was 300+ lines and Claude's responses got worse because of context dilution. Splitting into rules/ files fixed that.
Example rules/ structure (my Planning Agent)
.claude/rules/
├── 01-business-context.md # Revenue model, positioning, target customers
├── 02-agent-ecosystem.md # All agents, their missions, how they connect
├── 03-roadmap.md # Current phase, milestones, exit criteria
├── 04-content-architecture.md # Content channels, pillars, workflow
├── 05-daily-routine.md # Schedule, idea filtering, anti-distraction rules
├── 07-godin-strategy.md # Marketing principles, milestone tracking
├── 08-control-center.md # CLI tools reference, DB schema
├── 98-end-of-session.md # Ritual: update roadmap, capture knowledge
└── 99-content-capture.md # Auto-extract content signals from every session
The numbering is intentional, it controls load order and makes it easy to find things.
The agents don't call each other directly. They coordinate through:
• SQLite database: Source of truth for tasks, content pipeline state, sessions, metrics
SQLite database: Source of truth for tasks, content pipeline state, sessions, metrics
• Inbox files: When one agent needs to hand context to another, it drops a markdown file in the target's inbox/
Inbox files: When one agent needs to hand context to another, it drops a markdown file in the target's inbox/
• API endpoints: Dashboard reads/writes through a FastAPI backend
API endpoints: Dashboard reads/writes through a FastAPI backend
Example: when I finish a build session, the planning agent captures content signals (what was built, what was learned) and drops them in content/inbox/. The content agent picks these up during its weekly batch and drafts social posts from them.
• Too much in CLAUDE.md: Split into rules/ files. CLAUDE.md is the summary, rules/ are the details.
Too much in CLAUDE.md: Split into rules/ files. CLAUDE.md is the summary, rules/ are the details.
• No scope boundaries: Agents would try to do everything. Now every agent has a 00-scope.md rule that explicitly says what it does and does NOT do.
No scope boundaries: Agents would try to do everything. Now every agent has a 00-scope.md rule that explicitly says what it does and does NOT do.
• No archiving: I deleted old files and lost context. Now everything goes to archive/ first.
No archiving: I deleted old files and lost context. Now everything goes to archive/ first.
• Workflows in rules/: Moved to skills/ and token costs dropped noticeably.
Workflows in rules/: Moved to skills/ and token costs dropped noticeably.
• No standard template: Every agent was structured differently. Created a standard template and refactored all agents to follow it. Consistency makes everything easier.
No standard template: Every agent was structured differently. Created a standard template and refactored all agents to follow it. Consistency makes everything easier.
What I'd tell someone starting out
Start with one agent and one CLAUDE.md file. Don't build five agents on day one. Get one working well, understand the rules/ vs skills/ split, then create a second agent when you have a genuinely different domain.
The template structure above is what I'd start with for any new agent.
Anyone else running multiple Claude Code agents? What patterns have you found for keeping them organized?

View File

@@ -0,0 +1,473 @@
大多数 AI 智能体都有"失忆症"——每次新对话,之前聊过的全部清零。
memory-lancedb-pro 是 OpenClaw 的生产级长期记忆插件,把你的智能体变成一个真正的 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、备份、迁移、升级、导入导出——生产可用
社区维护的 安装脚本 一条命令搞定安装、升级和修复:
curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
bash setup-memory.sh
脚本覆盖的完整场景和其他社区工具,详见下方 生态工具。
通过 OpenClaw CLI推荐
openclaw plugins install memory-lancedb-pro@beta
或通过 npm
npm i memory-lancedb-pro@beta
如果用 npm 安装,你还需要在 openclaw.json 的 plugins.load.paths 中添加插件安装目录的 绝对路径。这是最常见的安装问题。
在 openclaw.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 → 避免会话摘要在初期污染检索结果
验证并重启:
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
完成!你的智能体现在拥有长期记忆了。
更多安装路径(已有用户、升级)
已在使用 OpenClaw
- 在 plugins.load.paths 中添加插件的 绝对路径
- 绑定记忆插槽plugins.slots.memory = "memory-lancedb-pro"
- 验证openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats
从 v1.1.0 之前的版本升级?
# 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 了解行为变更和升级说明。
memory-lancedb-pro 是核心插件。社区围绕它构建了配套工具,让安装和日常使用更加顺畅:
CortexReach/toolbox/memory-lancedb-pro-setup
不只是简单的安装器——脚本能智能处理各种常见场景:
你的情况
脚本会做什么
从未安装
全新下载 → 安装依赖 → 选择配置 → 写入 openclaw.json → 重启
通过 git clone 安装,卡在旧版本
自动 git fetch + checkout 到最新 → 重装依赖 → 验证
配置中有无效字段
自动检测并通过 schema 过滤移除不支持的字段
通过 npm 安装
跳过 git 更新,提醒你自行运行 npm update
openclaw CLI 因无效配置崩溃
降级方案:直接从 openclaw.json 文件读取工作目录路径
extensions/ 而非 plugins/
从配置或文件系统自动检测插件位置
已是最新版
仅执行健康检查,不做改动
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。
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
Claude Code 安装:
git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro
OpenClaw 安装:
git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill
架构
┌─────────────────────────────────────────────────────────┐
│ index.ts (入口) │
│ 插件注册 · 配置解析 · 生命周期钩子 │
└────────┬──────────┬──────────┬───────────────┘
│ │ │
┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐
│ store │ │embedder│ │retriever│ │ scopes │
│ .ts │ │ .ts │ │ .ts │ │ .ts │
└────────┘ └────────┘ └────────┘ └─────────────┘
│ │
┌────▼───┐ ┌─────▼──────────┐
│migrate │ │noise-filter.ts │
│ .ts │ │adaptive- │
└────────┘ │retrieval.ts │
└────────────────┘
┌─────────────┐ ┌──────────┐
│ tools.ts │ │ cli.ts │
│ (智能体 API)│ │ (CLI) │
└─────────────┘ └──────────┘
查询 → embedQuery() ─┐
├─→ 混合融合 → 重排序 → 生命周期衰减加权 → 长度归一化 → 过滤
查询 → BM25 全文 ─────┘
向量搜索 — 基于 LanceDB ANN 的语义相似度(余弦距离)
BM25 全文搜索 — 通过 LanceDB FTS 索引进行精确关键词匹配
混合融合 — 以向量分数为基础BM25 命中结果获得加权提升
可配置权重 — vectorWeight、bm25Weight、minScore
内置 Jina、SiliconFlow、Voyage AI 和 Pinecone 适配器
兼容任意 Jina 兼容端点(如 Hugging Face TEI、DashScope
混合打分60% 交叉编码器 + 40% 原始融合分数
优雅降级API 失败时回退到余弦相似度
阶段
效果
混合融合
结合语义召回和精确匹配召回
交叉编码器重排序
提升语义精确命中的排名
生命周期衰减加权
Weibull 时效性 + 访问频率 + 重要性 × 置信度
长度归一化
防止长条目主导结果锚点500 字符)
硬最低分
移除无关结果默认0.35
MMR 多样性
余弦相似度 > 0.85 → 降权
智能提取
- LLM 驱动的 6 类提取:用户画像、偏好、实体、事件、案例、模式
- L0/L1/L2 分层存储L0一句话索引→ L1结构化摘要→ L2完整叙述
- 两阶段去重向量相似度预过滤≥0.7)→ LLM 语义决策CREATE/MERGE/SKIP
- 类别感知合并profile 始终合并events/cases 仅追加
Weibull 衰减引擎
- 综合分数 = 时效性 + 频率 + 内在价值
- 三级晋升:外围 ↔ 工作 ↔ 核心,阈值可配置
- 访问强化:频繁被召回的记忆衰减更慢(类似间隔重复机制)
- 重要性调制半衰期:重要记忆衰减更慢
作用域
- 内置作用域global、agent:、custom:、project:、user:
- 通过 scopes.agentAccess 实现智能体级别的访问控制
- 默认:每个智能体访问 global + 自己的 agent: 作用域
自动捕捉
- 自动捕捉agent_end从对话中提取偏好/事实/决策/实体,去重后每轮最多存储 3 条
- 自动回忆before_agent_start注入 上下文(最多 3 条)
- 过滤低质量内容:智能体拒绝回复、元问题、打招呼
- 跳过检索:打招呼、斜杠命令、简单确认、表情符号
- 强制检索:记忆关键词("记得"、"之前"、"上次"
- 中文感知阈值中文6 字符 vs 英文15 字符)
CLI 命令
# 列出记忆
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 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 登录
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
Embedding 服务商
兼容 任意 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
取决于模型
重排序服务商
交叉编码器重排序通过 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
故障排除
在 LanceDB 0.26+ 上,某些数值列可能以 BigInt 形式返回。升级到 memory-lancedb-pro >= 1.0.14——插件现在会在运算前使用 Number(...) 进行类型转换。
AI 智能体铁律
将以下内容复制到你的 AGENTS.md让智能体自动遵守这些规则。
## 规则 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
字段
类型
说明
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
状态Beta——通过 npm i memory-lancedb-pro@beta 安装。使用 latest 的稳定版用户不受影响。
功能
说明
智能提取
LLM 驱动的 6 类提取,支持 L0/L1/L2 元数据。禁用时回退到正则模式。
生命周期评分
Weibull 衰减集成到检索中——高频和高重要性记忆排名更高。
层级管理
三级系统(核心 → 工作 → 外围),自动晋升/降级。
反馈GitHub Issues · 回退npm i memory-lancedb-pro@latest

View File

@@ -0,0 +1,94 @@
# Smart Trip Quote 客户讲解提纲
> 2026-03-25 | 为明天客户演示准备
---
## 1. 项目介绍
**Smart Trip Quote智能旅行报价系统** 是一个利用 AI 大语言模型LLM技术帮助旅行定制师快速分析和处理客户旅行需求的 SaaS 平台。
### 核心价值
- **智能化**: 用户只需用自然语言描述需求,系统自动提取结构化信息
- **高效**: 减少手动录入,报价周期从小时缩短到分钟级
- **多提供商支持**: 支持 OpenAI、Gemini、DeepSeek 等主流 LLM
### 技术栈
- 后端: Django + Django REST Framework
- 前端: Vue.js 3 + Vite
- 数据库: MariaDB
- AI: OpenAI/Gemini/DeepSeek API
- 部署: Docker + Nginx
---
## 2. 具体功能Demo 流程)
### 2.1 需求提交(核心功能)
- 用户输入自然语言(如:"我想明年3月去日本东京5天预算5000元"
- LLM 自动解析:目的地、天数、人数、预算、偏好等
- 返回结构化数据,保存到数据库
> **Demo**: 在前端界面输入一句话,看系统如何自动提取信息
### 2.2 行程管理
- 根据需求生成旅行行程Itinerary
- 每日行程安排Daily Schedule
- 景点、酒店、餐厅信息管理
> **Demo**: 在管理后台查看已生成的行程
### 2.3 定价策略
- 景区定价策略配置
- 行程报价生成
- 支持 webhook 回调通知
> **Demo**: 查看定价规则配置界面
### 2.4 导出功能
- PDF 导出行程
- Word 文档导出
> **Demo**: 演示导出功能
### 2.5 管理后台
- 需求管理(审核、编辑)
- 行程管理
- 景点/酒店/餐厅管理
- 定价规则管理
- LLM 提示词管理
---
## 3. 进一步需求分析和讨论
### 3.1 产品路线图(待讨论)
- [ ] 多语言支持
- [ ] 更多 LLM 提供商集成
- [ ] 移动端适配
- [ ] 团队协作功能
- [ ] 支付集成
- [ ] 数据分析与报表
### 3.2 客户可能关心的问题
- 数据安全与隐私
- 系统稳定性SLA
- 定制化需求
- 定价模式SaaS 订阅 vs 按量付费)
- 集成能力CRM、其他系统
### 3.3 技术讨论点
- 是否需要私有化部署?
- 是否有 API 集成需求?
- 数据迁移方案?
---
## 📎 快速参考
| 功能 | 路径 |
|------|------|
| 前端界面 | `apps/web/` |
| API 接口 | `/api/process/` |
| 管理后台 | `/admin/` |
| LLM 配置 | `config/llm_config.json` |