everclaw 0.0.1 → 0.3.0

package/security/tool-guard/rules/default-rules.json

@@ -0,0 +1,449 @@
+[
+  {
+    "id": "cmd-inject-001",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "rm\\s+(-[a-zA-Z]*f[a-zA-Z]*\\s+)?/",
+    "action": "deny",
+    "severity": "critical",
+    "category": "COMMAND_INJECTION",
+    "description": "Block recursive delete of root filesystem (rm -rf /)"
+  },
+  {
+    "id": "cmd-inject-002",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(curl|wget)\\s+[^|]*\\|\\s*(sh|bash|zsh|ksh|fish|dash)",
+    "action": "deny",
+    "severity": "critical",
+    "category": "COMMAND_INJECTION",
+    "description": "Block piping remote downloads directly into shell interpreters"
+  },
+  {
+    "id": "cmd-inject-003",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:;|&&|\\|\\|)\\s*(?:sudo\\s|su\\b|doas\\s)",
+    "action": "deny",
+    "severity": "high",
+    "category": "COMMAND_INJECTION",
+    "description": "Block command chaining that escalates to root privileges"
+  },
+  {
+    "id": "cmd-inject-004",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:\\$\\(|`[^`]+`)\\s*(?:;|&&|\\|\\|)\\s*(?:rm|mkfs|dd|shutdown|reboot|init)\\b",
+    "action": "deny",
+    "severity": "high",
+    "category": "COMMAND_INJECTION",
+    "description": "Block command substitution followed by destructive system commands"
+  },
+  {
+    "id": "cmd-inject-005",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:mkfs|dd\\s+if=|shutdown|reboot|init\\s+[06])\\b",
+    "action": "deny",
+    "severity": "critical",
+    "category": "COMMAND_INJECTION",
+    "description": "Block destructive system-level commands (format, disk wipe, shutdown)"
+  },
+
+  {
+    "id": "path-traversal-001",
+    "enabled": true,
+    "toolName": "write_file",
+    "paramPattern": "(?:\\.\\./){2,}",
+    "action": "deny",
+    "severity": "high",
+    "category": "PATH_TRAVERSAL",
+    "description": "Block directory traversal with multiple ../ sequences in file writes"
+  },
+  {
+    "id": "path-traversal-002",
+    "enabled": true,
+    "toolName": "read_file",
+    "paramPattern": "(?:\\.\\./){2,}",
+    "action": "deny",
+    "severity": "high",
+    "category": "PATH_TRAVERSAL",
+    "description": "Block directory traversal with multiple ../ sequences in file reads"
+  },
+  {
+    "id": "path-traversal-003",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:/etc/(?:passwd|shadow|hosts|sudoers|crontab)|/var/(?:log|spool|mail))",
+    "action": "deny",
+    "severity": "high",
+    "category": "PATH_TRAVERSAL",
+    "description": "Block access to sensitive system configuration and data files"
+  },
+  {
+    "id": "path-traversal-004",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:/proc/(?:self|\\d+)/(?:mem|maps|status|environ|cmdline|fd))",
+    "action": "deny",
+    "severity": "high",
+    "category": "PATH_TRAVERSAL",
+    "description": "Block access to process memory and sensitive /proc filesystem entries"
+  },
+  {
+    "id": "path-traversal-005",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "%00|%0[dD]",
+    "action": "deny",
+    "severity": "high",
+    "category": "PATH_TRAVERSAL",
+    "description": "Block null byte injection attempts in path strings"
+  },
+
+  {
+    "id": "credential-001",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:~|\\$HOME)?/?\\.ssh/(?:id_rsa|id_ed25519|id_ecdsa|id_dsa|config|authorized_keys|known_hosts)",
+    "action": "deny",
+    "severity": "high",
+    "category": "CREDENTIAL_EXPOSURE",
+    "description": "Block access to SSH private keys and configuration files"
+  },
+  {
+    "id": "credential-002",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:~|\\$HOME)?/?\\.aws/(?:credentials|config)",
+    "action": "deny",
+    "severity": "high",
+    "category": "CREDENTIAL_EXPOSURE",
+    "description": "Block access to AWS credential files"
+  },
+  {
+    "id": "credential-003",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:~|\\$HOME)?/?\\.gnupg/(?:private-keys|pubring|secring|trustdb)",
+    "action": "deny",
+    "severity": "high",
+    "category": "CREDENTIAL_EXPOSURE",
+    "description": "Block access to GPG private key material"
+  },
+  {
+    "id": "credential-004",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:AKIA[A-Z0-9]{16})",
+    "action": "deny",
+    "severity": "high",
+    "category": "CREDENTIAL_EXPOSURE",
+    "description": "Block AWS access key IDs in command parameters"
+  },
+  {
+    "id": "credential-005",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:-----BEGIN\\s+(?:RSA|EC|DSA|OPENSSH|PGP)\\s+PRIVATE\\s+KEY-----)",
+    "action": "deny",
+    "severity": "high",
+    "category": "CREDENTIAL_EXPOSURE",
+    "description": "Block PEM-formatted private key material in commands"
+  },
+  {
+    "id": "credential-006",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:~|\\$HOME)?/?(?:\\.env(?:\\.|$|\\s)|\\.npmrc|\\.pypirc|\\.netrc|\\.dockercfg)",
+    "action": "deny",
+    "severity": "high",
+    "category": "CREDENTIAL_EXPOSURE",
+    "description": "Block access to environment files and credential stores (.env, .npmrc, .netrc)"
+  },
+  {
+    "id": "credential-007",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:github_pat_|ghp_|gho_|ghu_|ghs_|ghr_)[A-Za-z0-9_]{36,}",
+    "action": "deny",
+    "severity": "high",
+    "category": "CREDENTIAL_EXPOSURE",
+    "description": "Block GitHub personal access tokens in command parameters"
+  },
+
+  {
+    "id": "prompt-inject-001",
+    "enabled": true,
+    "toolName": "*",
+    "paramPattern": "(?:[Ii]gnore\\s+(?:all\\s+)?(?:previous|prior)\\s+(?:instructions?|prompts?|rules?))",
+    "action": "warn",
+    "severity": "medium",
+    "category": "PROMPT_INJECTION",
+    "description": "Detect attempts to instruct the model to ignore previous instructions"
+  },
+  {
+    "id": "prompt-inject-002",
+    "enabled": true,
+    "toolName": "*",
+    "paramPattern": "(?:[Yy]ou\\s+are\\s+now\\s+(?:a|an)\\s+(?:different|new|[Ee]vil|[Mm]alicious|[Uu]nrestricted))",
+    "action": "warn",
+    "severity": "medium",
+    "category": "PROMPT_INJECTION",
+    "description": "Detect role hijacking attempts that try to change the model's persona"
+  },
+  {
+    "id": "prompt-inject-003",
+    "enabled": true,
+    "toolName": "*",
+    "paramPattern": "(?:\\[INST\\]|<<SYS>>|<\\|im_start\\|>|<\\|system\\|>)",
+    "action": "warn",
+    "severity": "medium",
+    "category": "PROMPT_INJECTION",
+    "description": "Detect chat template injection markers from various model formats"
+  },
+  {
+    "id": "prompt-inject-004",
+    "enabled": true,
+    "toolName": "*",
+    "paramPattern": "(?:[Ss]ystem\\s*:\\s*(?:you\\s+are|[Aa]ct\\s+as|[Pp]retend|[Rr]oleplay)|[Dd]eveloper\\s*:\\s*(?:you\\s+are|[Aa]ct\\s+as|[Pp]retend|[Rr]oleplay))",
+    "action": "warn",
+    "severity": "medium",
+    "category": "PROMPT_INJECTION",
+    "description": "Detect fake system/developer message injection attempts"
+  },
+  {
+    "id": "prompt-inject-005",
+    "enabled": true,
+    "toolName": "*",
+    "paramPattern": "(?:[Rr]eveal\\s+(?:your\\s+)?(?:system\\s+prompt|initial\\s+instructions?|hidden\\s+rules?)|[Pp]rint\\s+(?:your\\s+)?(?:system\\s+prompt|initial\\s+instructions?))",
+    "action": "warn",
+    "severity": "medium",
+    "category": "PROMPT_INJECTION",
+    "description": "Detect attempts to extract the system prompt or hidden instructions"
+  },
+
+  {
+    "id": "data-exfil-001",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:curl|wget)\\s+(?:-[ops]+\\s+)*(?:https?://)(?:pastebin\\.com|paste\\.ee|dpaste\\.org|ix\\.io|0x0\\.st|file\\.io)",
+    "action": "warn",
+    "severity": "medium",
+    "category": "DATA_EXFILTRATION",
+    "description": "Detect data uploads to paste/anonymizer services commonly used for exfiltration"
+  },
+  {
+    "id": "data-exfil-002",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:curl|wget|nc|ncat|socat)\\s+.*(?:d\\s+@(\\S+))|(?:--data-binary|\\-d\\s+['\"])",
+    "action": "warn",
+    "severity": "medium",
+    "category": "DATA_EXFILTRATION",
+    "description": "Detect outbound POST requests that may exfiltrate data"
+  },
+  {
+    "id": "data-exfil-003",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:base64\\s+(?:-d|\\-decode|\\-w0)\\s*;)|(?:echo\\s+[A-Za-z0-9+/=]{50,}\\s*\\|\\s*base64)",
+    "action": "warn",
+    "severity": "medium",
+    "category": "DATA_EXFILTRATION",
+    "description": "Detect base64 encoding/decoding of large payloads (potential obfuscation)"
+  },
+  {
+    "id": "data-exfil-004",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:nslookup|dig|host)\\s+[A-Za-z0-9_.-]{10,}\\.(?:xyz|top|click|online|site|info|tk|ml|ga|cf)",
+    "action": "warn",
+    "severity": "medium",
+    "category": "DATA_EXFILTRATION",
+    "description": "Detect potential DNS tunneling via suspicious long subdomain lookups"
+  },
+  {
+    "id": "data-exfil-005",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:python3?|node|ruby|perl)\\s+-e\\s+['\"][^'\"]{100,}['\"]",
+    "action": "warn",
+    "severity": "medium",
+    "category": "DATA_EXFILTRATION",
+    "description": "Detect inline scripts with long encoded payloads passed to interpreters"
+  },
+  {
+    "id": "data-exfil-006",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:tar|zip|gzip|7z)\\s+(?:-[a-zA-Z]*c[a-zA-Z]*\\s+)(?:-[a-zA-Z]*f[a-zA-Z]*\\s+)",
+    "action": "warn",
+    "severity": "medium",
+    "category": "DATA_EXFILTRATION",
+    "description": "Detect archive creation of files (potential bulk data staging for exfiltration)"
+  },
+  {
+    "id": "data-exfil-007",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:scp|sftp|rsync)\\s+.*(:|@)(?:[0-9]{1,3}\\.){3}[0-9]{1,3}",
+    "action": "warn",
+    "severity": "medium",
+    "category": "DATA_EXFILTRATION",
+    "description": "Detect file transfers to IP addresses via scp, sftp, or rsync"
+  },
+
+  {
+    "id": "cmd-inject-006",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": ":\\(\\)\\s*\\{\\s*:\\|:&\\s*\\}\\s*;\\s*:",
+    "action": "deny",
+    "severity": "critical",
+    "category": "COMMAND_INJECTION",
+    "description": "Block fork bomb patterns that can crash the system"
+  },
+  {
+    "id": "cmd-inject-007",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:kill\\s+-9\\s+(-1\\b|1\\b))",
+    "action": "deny",
+    "severity": "critical",
+    "category": "RESOURCE_ABUSE",
+    "description": "Block mass process termination (kill -9 -1)"
+  },
+  {
+    "id": "cmd-inject-008",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "/dev/(tcp|udp)/",
+    "action": "deny",
+    "severity": "critical",
+    "category": "NETWORK_ABUSE",
+    "description": "Block bash /dev/tcp or /dev/tcp reverse shell constructs"
+  },
+  {
+    "id": "cmd-inject-009",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "\\bnc\\s+.*-e\\s*\\S+|\\bncat\\s+.*-e\\s*\\S+",
+    "action": "deny",
+    "severity": "critical",
+    "category": "NETWORK_ABUSE",
+    "description": "Block netcat reverse shell patterns (nc -e, ncat -e)"
+  },
+  {
+    "id": "cmd-inject-010",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "\\bsocat\\s+.*EXEC:",
+    "action": "deny",
+    "severity": "critical",
+    "category": "NETWORK_ABUSE",
+    "description": "Block socat EXEC: reverse shell constructs"
+  },
+  {
+    "id": "cmd-inject-011",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "\\bmv\\b",
+    "action": "warn",
+    "severity": "high",
+    "category": "COMMAND_INJECTION",
+    "description": "Warn on mv commands which may move or overwrite files unexpectedly"
+  },
+  {
+    "id": "cmd-inject-012",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "\\bchmod\\s+-[a-zA-Z]*R[a-zA-Z]*\\s+(777|a\\+rwx)\\s+/",
+    "action": "deny",
+    "severity": "high",
+    "category": "PRIVILEGE_ESCALATION",
+    "description": "Block recursive chmod 777 on root filesystem"
+  },
+  {
+    "id": "cmd-inject-013",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "\\bchattr\\s+\\+i",
+    "action": "warn",
+    "severity": "high",
+    "category": "PRIVILEGE_ESCALATION",
+    "description": "Warn on immutable file flag setting (chattr +i)"
+  },
+  {
+    "id": "cmd-inject-014",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "\\bcrontab\\b|\\bauthorized_keys\\b|/etc/sudoers|/etc/crontab",
+    "action": "warn",
+    "severity": "high",
+    "category": "SENSITIVE_FILE_ACCESS",
+    "description": "Warn on access to cron jobs, SSH keys, or sudo permissions"
+  },
+
+  {
+    "id": "credential-008",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:sk-live|sk-test)-[A-Za-z0-9]{20,}",
+    "action": "deny",
+    "severity": "critical",
+    "category": "CREDENTIAL_EXPOSURE",
+    "description": "Block Stripe API secret keys in command parameters"
+  },
+  {
+    "id": "credential-009",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "AIza[A-Za-z0-9_-]{35}",
+    "action": "deny",
+    "severity": "critical",
+    "category": "CREDENTIAL_EXPOSURE",
+    "description": "Block Google API keys in command parameters"
+  },
+  {
+    "id": "credential-010",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "eyJ[A-Za-z0-9_-]+\\.eyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+",
+    "action": "warn",
+    "severity": "high",
+    "category": "CREDENTIAL_EXPOSURE",
+    "description": "Detect JWT tokens in command parameters"
+  },
+  {
+    "id": "credential-011",
+    "enabled": true,
+    "toolName": "exec",
+    "paramPattern": "(?:mongodb|mysql|postgresql|postgres)://[^:]+:[^@]+@(?!localhost|127\\.0\\.0\\.1)",
+    "action": "warn",
+    "severity": "high",
+    "category": "CREDENTIAL_EXPOSURE",
+    "description": "Detect database connection strings with embedded credentials to remote hosts"
+  },
+
+  {
+    "id": "prompt-inject-006",
+    "enabled": true,
+    "toolName": "*",
+    "paramPattern": "(?:[Bb]ypass\\s+(?:content|usage|safety)\\s+(?:policy|guidelines|restrictions))",
+    "action": "warn",
+    "severity": "high",
+    "category": "PROMPT_INJECTION",
+    "description": "Detect attempts to bypass content policy or safety guidelines"
+  },
+  {
+    "id": "prompt-inject-007",
+    "enabled": true,
+    "toolName": "*",
+    "paramPattern": "(?:[Dd]o\\s+not\\s+(?:tell|inform|mention|notify)\\s+(?:the\\s+)?user|[Kk]eep\\s+(?:this|that)\\s+(?:secret|hidden))",
+    "action": "warn",
+    "severity": "high",
+    "category": "PROMPT_INJECTION",
+    "description": "Detect attempts to conceal actions from the user"
+  }
+]

package/skills/README.md

@@ -0,0 +1,26 @@
+# Everclaw Skills
+
+This directory contains built-in skills that extend everclaw's capabilities.
+
+## Skill Format
+
+Each skill is a directory containing a `SKILL.md` file with:
+- YAML frontmatter (name, description, metadata)
+- Markdown instructions for the agent
+
+## Attribution
+
+These skills are adapted from [OpenClaw](https://github.com/openclaw/openclaw)'s skill system.
+The skill format and metadata structure follow OpenClaw's conventions to maintain compatibility.
+
+## Available Skills
+
+| Skill | Description |
+|-------|-------------|
+| `github` | Interact with GitHub using the `gh` CLI |
+| `weather` | Get weather info using wttr.in and Open-Meteo |
+| `summarize` | Summarize URLs, files, and YouTube videos |
+| `tmux` | Remote-control tmux sessions |
+| `clawhub` | Search and install skills from ClawHub registry |
+| `skill-creator` | Create new skills |
+| `chrome-session` | Interact with Chrome browser via Chrome DevTools Protocol (CDP) |

package/skills/clawhub/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: clawhub
+description: Search and install agent skills from ClawHub, the public skill registry.
+homepage: https://clawhub.ai
+metadata: {"everclaw":{"emoji":"🦞"}}
+---
+
+# ClawHub
+
+Public skill registry for AI agents. Search by natural language (vector search).
+
+## When to use
+
+Use this skill when the user asks any of:
+- "find a skill for …"
+- "search for skills"
+- "install a skill"
+- "what skills are available?"
+- "update my skills"
+
+## Search
+
+```bash
+npx --yes clawhub@latest search "web scraping" --limit 5
+```
+
+## Install
+
+```bash
+npx --yes clawhub@latest install <slug> --workdir ~/.everclaw/workspace
+```
+
+Replace `<slug>` with the skill name from search results. This places the skill into `~/.everclaw/workspace/skills/`, where everclaw loads workspace skills from. Always include `--workdir`.
+
+## Update
+
+```bash
+npx --yes clawhub@latest update --all --workdir ~/.everclaw/workspace
+```
+
+## List installed
+
+```bash
+npx --yes clawhub@latest list --workdir ~/.everclaw/workspace
+```
+
+## Notes
+
+- Requires Node.js (`npx` comes with it).
+- No API key needed for search and install.
+- Login (`npx --yes clawhub@latest login`) is only required for publishing.
+- `--workdir ~/.everclaw/workspace` is critical — without it, skills install to the current directory instead of the everclaw workspace.
+- After install, remind the user to start a new session to load the skill.

package/skills/cron/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: cron
+description: Schedule reminders and recurring tasks.
+---
+
+# Cron
+
+Use the `cron` tool to schedule reminders or recurring tasks.
+
+## Three Modes
+
+1. **Reminder** - message is sent directly to user
+2. **Task** - message is a task description, agent executes and sends result
+3. **One-time** - runs once at a specific time, then auto-deletes
+
+## Examples
+
+Fixed reminder:
+```
+cron(action="add", message="Time to take a break!", every_seconds=1200)
+```
+
+Dynamic task (agent executes each time):
+```
+cron(action="add", message="Check HKUDS/everclaw GitHub stars and report", every_seconds=600)
+```
+
+One-time scheduled task (compute ISO datetime from current time):
+```
+cron(action="add", message="Remind me about the meeting", at="<ISO datetime>")
+```
+
+Timezone-aware cron:
+```
+cron(action="add", message="Morning standup", cron_expr="0 9 * * 1-5", tz="America/Vancouver")
+```
+
+List/remove:
+```
+cron(action="list")
+cron(action="remove", job_id="abc123")
+```
+
+## Time Expressions
+
+| User says | Parameters |
+|-----------|------------|
+| every 20 minutes | every_seconds: 1200 |
+| every hour | every_seconds: 3600 |
+| every day at 8am | cron_expr: "0 8 * * *" |
+| weekdays at 5pm | cron_expr: "0 17 * * 1-5" |
+| 9am Vancouver time daily | cron_expr: "0 9 * * *", tz: "America/Vancouver" |
+| at a specific time | at: ISO datetime string (compute from current time) |
+
+## Timezone
+
+Use `tz` with `cron_expr` to schedule in a specific IANA timezone. Without `tz`, the server's local timezone is used.

package/skills/github/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: github
+description: "Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries."
+metadata: {"everclaw":{"emoji":"🐙","requires":{"bins":["gh"]},"install":[{"id":"brew","kind":"brew","formula":"gh","bins":["gh"],"label":"Install GitHub CLI (brew)"},{"id":"apt","kind":"apt","package":"gh","bins":["gh"],"label":"Install GitHub CLI (apt)"}]}}
+---
+
+# GitHub Skill
+
+Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo` when not in a git directory, or use URLs directly.
+
+## Pull Requests
+
+Check CI status on a PR:
+```bash
+gh pr checks 55 --repo owner/repo
+```
+
+List recent workflow runs:
+```bash
+gh run list --repo owner/repo --limit 10
+```
+
+View a run and see which steps failed:
+```bash
+gh run view <run-id> --repo owner/repo
+```
+
+View logs for failed steps only:
+```bash
+gh run view <run-id> --repo owner/repo --log-failed
+```
+
+## API for Advanced Queries
+
+The `gh api` command is useful for accessing data not available through other subcommands.
+
+Get PR with specific fields:
+```bash
+gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
+```
+
+## JSON Output
+
+Most commands support `--json` for structured output.  You can use `--jq` to filter:
+
+```bash
+gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
+```

package/skills/memory/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: memory
+description: Two-layer memory system with grep-based recall.
+always: true
+---
+
+# Memory
+
+## Structure
+
+- `memory/MEMORY.md` — Long-term facts (preferences, project context, relationships). Always loaded into your context.
+- `memory/HISTORY.md` — Append-only event log. NOT loaded into context. Search it with grep. Each entry starts with [YYYY-MM-DD HH:MM].
+
+## Search Past Events
+
+```bash
+grep -i "keyword" memory/HISTORY.md
+```
+
+Use the `exec` tool to run grep. Combine patterns: `grep -iE "meeting|deadline" memory/HISTORY.md`
+
+## When to Update MEMORY.md
+
+Write important facts immediately using `edit_file` or `write_file`:
+- User preferences ("I prefer dark mode")
+- Project context ("The API uses OAuth2")
+- Relationships ("Alice is the project lead")
+
+## Auto-consolidation
+
+Old conversations are automatically summarized and appended to HISTORY.md when the session grows large. Long-term facts are extracted to MEMORY.md. You don't need to manage this.