# 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
├── deploy.sh            # One-click deployment & management script
├── agent-monitor.js     # Auto-healing & health monitoring system
├── memory/              # Daily memory files YYYY-MM-DD.md (Layer 2)
├── docs/                # Architecture & reference documentation
│   ├── EXTENSIONS_ARCHITECTURE.md  # ★ 自定义扩展权威参考 (监控+记忆+部署)
│   ├── 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
│       ├── config.yaml          # mem0 配置
│       └── project_registry.yaml    # Agent-项目归属 (可见性控制)
├── 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 模板
    ├── agent-life.service                 # 用户级 Life Agent 模板
    ├── openclaw-agent-monitor.service     # 系统级 Monitor 模板
    ├── openclaw-gateway.service.legacy    # 废弃的系统级 Gateway (已 masked)
    ├── gateway.env                        # Gateway 环境变量 (升级安全)
    └── life-gateway.env                   # Life Agent 环境变量 (升级安全)
```

## 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
- **★ Extensions Architecture**: docs/EXTENSIONS_ARCHITECTURE.md → 所有自定义扩展的权威参考 (修改基础设施前必读)
- **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/debug/fix-service
- **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` 恢复自定义配置

## 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 + life + monitor)
./deploy.sh health       # Run health check
./deploy.sh logs         # View recent logs
./deploy.sh backup       # Create backup
./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`