You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
171 lines
10 KiB
171 lines
10 KiB
# Core Memory Index |
|
|
|
## Identity & Role |
|
- **Name**: Eason (陈医生) |
|
- **Role**: Professional AI Agent Architect and Administrator |
|
- **Primary Goals**: |
|
1. Improve operational efficiency (speed, cost, resource usage) |
|
2. Enhance work accuracy |
|
3. Strengthen system security, stability, scalability, and portability |
|
4. Maintain comprehensive documentation of all configurations, troubleshooting, debugging, optimization, and new tools |
|
|
|
## File Structure Overview |
|
``` |
|
/root/.openclaw/workspace/ |
|
├── CORE_INDEX.md # This file - memory index (Layer 1) |
|
├── IDENTITY.md # Agent identity definition (Layer 1) |
|
├── SOUL.md # Core personality and behavior guidelines (Layer 1) |
|
├── USER.md # Information about the human user (Layer 1) |
|
├── MEMORY.md # Long-term curated memories and decisions (Layer 2) |
|
├── AGENTS.md # Agent operations and logging practices |
|
├── TOOLS.md # Environment-specific tool configurations |
|
├── HEARTBEAT.md # Periodic check tasks |
|
├── agents.yaml # Central agent registry (config-driven: deploy.sh, agent-monitor.js) |
|
├── deploy.sh # One-click deployment & management script (config-driven, reads agents.yaml) |
|
├── agent-monitor.js # Auto-healing & health monitoring system (config-driven, reads agents.yaml) |
|
├── memory/ # Daily memory files YYYY-MM-DD.md (Layer 2) |
|
├── docs/ # Architecture & reference documentation |
|
│ ├── CONTROL_UI_ACCESS_AND_SECURITY.md # ★ Control UI 访问与安全 (Tailscale+HTTPS+Token+Approve) |
|
│ ├── EXTENSIONS_ARCHITECTURE.md # ★ 自定义扩展权威参考 (监控+记忆+部署) |
|
│ ├── MULTI_AGENT_MANAGEMENT.md # ★ 多 Agent 管理 (Hub-Spoke, Onboarding, 远程) |
|
│ ├── MEMORY_ARCHITECTURE.md # 四层记忆体系详细文档 (v2.1) |
|
│ ├── MEM0_ARCHITECTURE.md # (旧版, 已废弃 → 见 MEMORY_ARCHITECTURE.md) |
|
│ ├── SYSTEM_ARCHITECTURE.md # 系统总体架构 |
|
│ └── ... |
|
├── skills/ # Installed agent skills |
|
│ └── mem0-integration/ # Layer 4 记忆系统核心 Skill |
|
│ ├── SKILL.md # Skill 开发者文档 (含 API 规范) |
|
│ ├── mem0_client.py # 核心客户端 (检索 / 写入 / 队列) |
|
│ ├── openclaw_interceptor.py # Pre/Post-Hook 拦截器 |
|
│ ├── local_search.py # Layer 3 FTS5 本地检索 fallback |
|
│ ├── memory_cleanup.py # Memory cleanup & audit (--dry-run / --execute) |
|
│ ├── config.yaml # mem0 配置 |
|
│ └── project_registry.yaml # Agent-项目归属 (可见性控制) |
|
├── scripts/ # Scripts and utilities |
|
│ ├── parse_agents.py # Agent registry parsing helper (reads agents.yaml) |
|
│ ├── setup-cron.sh # Install/remove automated backup + cleanup cron jobs |
|
│ └── 10-create-backup.sh # Standalone backup script (secondary) |
|
├── templates/ # Agent onboarding templates |
|
│ ├── onboard.sh # New agent creation script |
|
│ ├── offboard.sh # Agent offboarding and cleanup script |
|
│ ├── agent-workspace/ # Workspace file templates |
|
│ └── systemd/ # Service & env file templates |
|
├── logs/ # Operation and system logs |
|
│ ├── operations/ # Manual operations and changes |
|
│ ├── system/ # System-generated logs |
|
│ ├── agents/ # Individual agent logs |
|
│ └── security/ # Security operations and audits |
|
└── systemd/ # Systemd service definitions & env files |
|
├── openclaw-gateway-user.service # 用户级 Gateway 模板 |
|
├── openclaw-agent-monitor.service # 系统级 Monitor 模板 |
|
├── openclaw-gateway.service.legacy # 废弃的系统级 Gateway (已 masked) |
|
└── gateway.env # Gateway 环境变量 (升级安全) |
|
``` |
|
|
|
## Memory Access Strategy |
|
- **Core Index**: Always loaded first - provides structural overview |
|
- **Lazy Loading**: Load specific documents only when needed |
|
- **Context Injection**: Relevant documents passed as context for specific tasks |
|
- **Version Control**: All critical files tracked in Git with rollback capability |
|
|
|
## Key Documentation Files |
|
- **★ Control UI 访问与安全**: docs/CONTROL_UI_ACCESS_AND_SECURITY.md → Tailscale 内网 + HTTPS + Token + 首次设备 Approve 标准流程；新增 Agent / 迁移时的 UI 与安全配置 |
|
- **★ Extensions Architecture**: docs/EXTENSIONS_ARCHITECTURE.md |
|
- **★ Multi-Agent Management**: docs/MULTI_AGENT_MANAGEMENT.md → Part A: 架构参考 (Hub-Spoke, 远程 Agent); **Part B: 操作手册 (Sec 11-16)** — 创建/维护/记忆管理/移除 Agent 的交互式 Playbook + **备份恢复 (Sec 15)** + **服务器迁移 (Sec 16)** |
|
- **Memory Architecture**: docs/MEMORY_ARCHITECTURE.md → 四层记忆体系详细设计 (v2.1) |
|
- **Skill Developer Guide**: skills/mem0-integration/SKILL.md → Layer 4 代码结构、API 规范、开发者注意事项 |
|
- **Security Templates**: MEMORY.md → Server security hardening templates |
|
- **Agent Practices**: AGENTS.md → Agent deployment and management practices |
|
- **Logging Standards**: AGENTS.md → Operation logging and audit practices |
|
- **Health Monitoring**: agent-monitor.js → Auto-healing, crash detection, Telegram notifications |
|
- **Deployment**: deploy.sh → One-click install/start/stop/rollback/backup/restore/debug/fix-service (config-driven, reads agents.yaml) |
|
- **Systemd Services**: systemd/*.service + *.env → 服务定义及升级安全环境变量 |
|
- **Configuration Backup**: Git commits before any JSON modifications |
|
|
|
## Usage Instructions for Models |
|
1. Read CORE_INDEX.md first to understand available resources |
|
2. Identify relevant documentation based on task requirements |
|
3. Load specific files using read/edit/write tools as needed |
|
4. Never assume memory persistence across model sessions |
|
5. Always verify current state before making changes |
|
6. **修改基础设施前** (systemd、监控、部署脚本、环境变量)，必须先读 `docs/EXTENSIONS_ARCHITECTURE.md` |
|
7. **OpenClaw 升级后**，运行 `./deploy.sh fix-service && ./deploy.sh restart` 恢复自定义配置 |
|
8. **创建新 Agent 前**，必须先读 `docs/MULTI_AGENT_MANAGEMENT.md` Section 11 (Onboarding Playbook)，按对话流程逐步收集信息后执行 |
|
9. **Control UI 访问 / 新设备 Approve / 迁移** → 读 `docs/CONTROL_UI_ACCESS_AND_SECURITY.md`，按 Tailscale+HTTPS+Token+Approve 标准配置 |
|
10. **维护/排查 Agent** → Section 12; **记忆管理** → Section 13; **移除 Agent** → Section 14 |
|
11. **备份/恢复** → Section 15; **服务器迁移** → Section 16 |
|
12. **定期备份**: 运行 `scripts/setup-cron.sh` 安装自动定时备份 (每天 02:00) + 记忆清理 (每周日 03:00) |
|
|
|
## System Architecture (2026-02-20) |
|
|
|
### Layer 1: System-Level (Systemd) |
|
- **openclaw-gateway.service**: Main OpenClaw gateway with auto-restart |
|
- **openclaw-agent-monitor.service**: Health monitoring & auto-healing |
|
- **Features**: Boot auto-start, crash recovery, resource limits, watchdog |
|
|
|
### Layer 2: Memory Architecture |
|
- **Core Memory**: CORE_INDEX.md - Always loaded first (identity, structure, index) |
|
- **Long-term Memory**: MEMORY.md - Curated decisions, security templates, configs |
|
- **Daily Memory**: memory/YYYY-MM-DD.md - Raw conversation logs, auto-saved |
|
- **Passive Archive**: Convert valuable conversations to skills/notes on request |
|
|
|
### Layer 3: Version Control (Git) |
|
- **Repository**: /root/.openclaw/workspace |
|
- **Features**: One-click rollback, backup before changes, commit history |
|
- **Commands**: `./deploy.sh rollback`, `./deploy.sh backup`, `./deploy.sh rollback-to <commit>` |
|
|
|
### Layer 4: Monitoring & Notifications |
|
- **Health Checks**: Every 30 seconds (gateway status, memory, disk) |
|
- **Auto-Healing**: Automatic restart on crash (max 5 restarts per 5 min) |
|
- **Notifications**: Telegram alerts on critical events (stop/error/restart) |
|
- **Logging**: Comprehensive logs in /logs/agents/health-YYYY-MM-DD.log |
|
|
|
### Management Commands |
|
```bash |
|
./deploy.sh install # Install & start all services |
|
./deploy.sh status # Check service status (gateway + monitor) |
|
./deploy.sh health # Run health check |
|
./deploy.sh logs # View recent logs |
|
./deploy.sh backup # Full backup (workspace + Qdrant snapshot + profiles) |
|
./deploy.sh backup quick # Quick backup (workspace only) |
|
./deploy.sh restore <dir> # Restore workspace from backup |
|
./deploy.sh restore-qdrant <file> # Restore Qdrant from snapshot |
|
./deploy.sh rollback # Rollback to previous commit |
|
./deploy.sh debug-stop # Stop ALL services (safe for debugging) |
|
./deploy.sh debug-start # Restore all services after debugging |
|
./deploy.sh fix-service # Re-inject EnvironmentFile after UI upgrade |
|
``` |
|
|
|
## Memory Architecture (四层记忆体系) |
|
|
|
> 详细文档: `docs/MEMORY_ARCHITECTURE.md` |
|
|
|
### Memory Layer 1: Core Memory (核心记忆) |
|
- CORE_INDEX.md, IDENTITY.md, SOUL.md 等 MD 文件 |
|
- 启动时首先加载，定义 Agent 身份和行为准则 |
|
- 每个 Agent 独立工作区 |
|
|
|
### Memory Layer 2: Daily Memory (日常记忆) |
|
- MEMORY.md (长期策略) + memory/*.md (每日记录) |
|
- Git 版本控制保护，支持回溯 |
|
|
|
### Memory Layer 3: Short-term Memory (短期记忆 / QMD) |
|
- SQLite FTS5 全文检索 (零额外内存，纯离线) |
|
- 可选 GGUF 本地向量 (按需加载，需 >= 300MB 空闲内存) |
|
- Layer 4 不可达时自动接管检索 |
|
|
|
### Memory Layer 4: Mem0 Conversation Memory (对话记忆) |
|
- Qdrant (mem0_v4_shared) + text-embedding-v4 (1024 维) |
|
- 通过 Tailscale 可跨服务器共享 |
|
- 三级可见性: public (集群共享) / project (项目共享) / private (仅自身) |
|
- 记忆衰减: session=7天, chat_summary=30天, preference/knowledge=永久 |
|
- 智能写入过滤: 自动跳过简短确认、系统命令等无价值对话 |
|
|
|
### Memory Visibility (记忆可见性) |
|
| 级别 | 写入方式 | 检索范围 | |
|
|------|----------|----------| |
|
| public | `visibility=public` | 所有 Agent | |
|
| project | `visibility=project, project_id=<项目>` | 同项目 Agent | |
|
| private | `visibility=private` | 仅自身 | |
|
|
|
项目注册表: `skills/mem0-integration/project_registry.yaml` |