@swarmclawai/swarmclaw 1.2.5 → 1.2.8

package/README.md

@@ -190,6 +190,29 @@ The building blocks are the same: **agents, tools, memory, delegation, schedules
 
 ## Release Notes
 
+### v1.2.8 Highlights
+
+- **Linux/WSL compatibility**: subprocess spawning now uses `$SHELL` instead of hardcoded `/bin/zsh`, fixing `ENOENT` errors on Linux and WSL systems.
+- **nvm compatibility**: stripped `npm_config_prefix` from subprocess environment, fixing node PATH resolution for nvm users.
+- **Dev-mode daemon fix**: prevented duplicate daemon spawn failure when daemon runs in-process during development.
+- **Gateway sheet stability**: fixed infinite render loop when opening a gateway profile with a disconnected gateway.
+- **Auto-provision gateway on deploy**: "Deploy on this host" now automatically creates a gateway profile and credential, so agents can connect immediately without a manual save step.
+- **Credential cleanup on gateway delete**: deleting a gateway profile now cleans up its associated credential when no other gateway or agent references it.
+
+### v1.2.7 Highlights
+
+- **Tool primitives**: consolidated 50+ narrow tools into 6 action-based primitives — `execute`, `files`, `memory`, `platform`, `skills`, and `credential-env` — with skill teach files so agents learn usage patterns on demand.
+- **Type system decomposition**: split the monolithic 3500-line types file into 16 focused domain modules (`agent.ts`, `session.ts`, `message.ts`, `run.ts`, etc.) with full backward-compatible re-exports.
+- **Lightweight direct chat**: message classifier detects simple conversational turns and fast-paths them with minimal prompt assembly and reduced thinking budget.
+- **Prompt mode resolution**: root sessions receive full system prompts while delegated and lightweight turns get streamlined minimal prompts.
+- **Execute tool config UI**: inspector panel now has separate configuration sections for the execute tool (sandbox/host backend, network, timeout) and browser sandbox.
+- **Chat store pagination**: proper `messageStartIndex` tracking, improved queued-message deduplication, and active-turn transcript merging.
+- **Per-session WebSocket notifications**: message mutations now broadcast to session-specific topics for more targeted UI updates.
+- **Tool capability policy refactoring**: consolidated matching logic with extension ID canonicalization for reliable policy resolution.
+- **Validation schemas**: new `AgentExecuteConfigSchema` for Zod-based execute config validation.
+- **Bug fix — custom provider resolution**: fixed "Unknown provider" error when using custom providers in chat execution.
+- **Lint baseline maintained** at 364 violations (no regressions).
+
 ### v1.2.5 Highlights
 
 - **Working memory hierarchy**: agents maintain structured working state (facts, plans, decisions, blockers, evidence) that persists across turns and survives context compaction.
@@ -236,22 +259,6 @@ The building blocks are the same: **agents, tools, memory, delegation, schedules
 - **SKILL.md v2.0.0**: comprehensive CLI documentation covering 40+ command groups with examples and usage patterns.
 - **New dev scripts**: added `type-check`, `test`, and `format` scripts to `package.json` for streamlined development workflows.
 
-### v1.1.9 Highlights
-
-- **Docker build stability**: limit Next.js page data workers to 1 in build mode to prevent `SQLITE_BUSY` contention.
-- **Async file I/O in providers**: Anthropic and OpenAI providers now use `fs.promises` for non-blocking attachment reads.
-- **Anthropic request timeout**: 60s timeout on Anthropic API requests prevents indefinite hangs.
-- **Graceful crash handling**: instrumentation now catches EPIPE and suppresses expected LangGraph unhandled rejections.
-- **Log tail optimization**: `/api/logs` reads only the last 256 KB instead of loading the entire log file.
-- **Thread session fast path**: `ensureAgentThreadSession` uses single-row lookup instead of full table scan when `threadSessionId` is set.
-- **Memory graph performance**: force-directed simulation writes to DOM imperatively instead of re-rendering React state per frame; stops when kinetic energy settles.
-- **Reduced polling frequency**: chat area WS polling intervals relaxed (messages/runs 2s to 10s, browser 5s to 30s) to lower server load.
-- **Chat list indexing**: connector lookup indexed by `agentId` for O(1) instead of O(n) per session filter.
-- **Sidebar skill badges**: skill draft count displayed as a badge on the Skills nav item.
-- **Route loading states**: added `loading.tsx` skeleton pages for activity, home, logs, memory, and tasks routes.
-- **Command palette cleanup**: fixed missing `setOpen` dependencies and removed unused props.
-- **Playwright proxy hardening**: improved stdio pipe handling for dev server restarts.
-- **Scheduler and run ledger fixes**: improved scheduler reliability and run ledger state tracking.
 
 ## What SwarmClaw Focuses On
 
@@ -350,7 +357,7 @@ Then open `http://localhost:3456`.
 
 - Node.js 22.6+
 - npm 10+ or another supported package manager
-- Docker Desktop is recommended for sandbox/browser execution
+- Docker Desktop is recommended for sandbox browser execution
 - Optional provider CLIs if you want delegated CLI backends such as Claude Code, Codex, OpenCode, or Gemini
 
 ## Security Notes

package/next.config.ts

@@ -75,6 +75,7 @@ const nextConfig: NextConfig = {
     '@slack/bolt', '@slack/web-api', '@slack/socket-mode',
     '@whiskeysockets/baileys',
     'qrcode',
+    'just-bash',
   ],
   allowedDevOrigins: getAllowedDevOrigins(),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmclawai/swarmclaw",
-  "version": "1.2.5",
+  "version": "1.2.8",
   "description": "Self-hosted AI runtime for OpenClaw, delegation, autonomy, runtime skills, crypto wallets, and chat platform connectors.",
   "license": "MIT",
   "publishConfig": {
@@ -113,6 +113,7 @@
     "grammy": "^1.40.0",
     "highlight.js": "^11.11.1",
     "imapflow": "^1.2.11",
+    "just-bash": "^2.14.0",
     "langchain": "^1.2.30",
     "lucide-react": "^0.574.0",
     "mailparser": "^3.9.3",
@@ -136,8 +137,8 @@
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.4.1",
     "tailwindcss": "^4",
-    "tw-animate-css": "^1.4.0",
     "tsx": "^4.20.6",
+    "tw-animate-css": "^1.4.0",
     "typescript": "^5",
     "ws": "^8.19.0",
     "zod": "^4.3.6",

package/scripts/easy-setup.mjs

@@ -130,7 +130,7 @@ function main() {
 
   runOptional('node', ['./scripts/ensure-sandbox-browser-image.mjs'])
   if (!commandExists('docker')) {
-    log('Docker not detected. SwarmClaw will fall back to host execution until Docker Desktop is installed.')
+    log('Docker not detected. SwarmClaw will use the host Playwright runtime until Docker Desktop is installed.')
   }
 
   if (productionMode) {

package/scripts/postinstall.mjs

@@ -86,7 +86,7 @@ if (!process.env.CI) {
     }
 
     if (!commandExists('docker')) {
-      logNote('Docker was not found. Container sandboxes will fall back to host execution until Docker is installed.')
+      logNote('Docker was not found. Browser sandboxing will use the host Playwright runtime until Docker is installed.')
     }
   }
 }

package/skills/swarmclaw.md

@@ -0,0 +1,115 @@
+# SwarmClaw Platform
+
+SwarmClaw is an AI agent runtime and multi-agent orchestration platform. It gives agents a uniform set of tools, persistent memory, connector integrations, and the ability to delegate work to other agents.
+
+## The 6 Primitive Tools
+
+Every agent has access to these core tools. They cover the full range of agent capabilities.
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| **files** | Read, write, edit, list, search files | Any file operation on the workspace filesystem |
+| **execute** | Run bash scripts (sandboxed or host) | Shell commands, curl, data processing, package management |
+| **memory** | Store and retrieve persistent knowledge | Facts, preferences, decisions that should survive across sessions |
+| **platform** | Tasks, communication, delegation, projects | Coordinating with humans and other agents |
+| **browser** | Control a headless browser | Interactive web pages, JavaScript-rendered content |
+| **skills** | Discover and load skill documentation | Learning how to use tools, APIs, or workflows |
+
+### Tool Selection Guide
+
+| Task | Tool |
+|------|------|
+| Edit a source file | `files` (edit action) |
+| Run tests | `execute` |
+| Call a REST API (JSON) | `execute` (curl) |
+| Scrape a dynamic web page | `browser` |
+| Remember a user preference | `memory` |
+| Ask the user a question | `platform` (communicate.ask_human) |
+| Send a Slack message | `platform` (communicate.send_message) |
+| Hand off work to another agent | `platform` (communicate.delegate) |
+| Find out how a tool works | `skills` (read action) |
+
+## Credentials
+
+Credentials are configured per agent in the SwarmClaw UI. They are:
+
+- **Injected as environment variables** into `execute` tool runs (e.g., `$OPENAI_API_KEY`, `$GITHUB_TOKEN`)
+- **Automatically redacted** from all tool output -- secrets never appear in chat history
+- **Named by convention**: `<PROVIDER>_API_KEY` or custom names set in the credential config
+
+You never need to ask the user for API keys directly. If a credential is configured, it's available as an env var. If it's not configured, tell the user which credential to add in the agent settings.
+
+## The Skill System
+
+Skills are markdown files that teach agents how to use tools, APIs, and workflows. They are documentation, not executable code.
+
+### Loading Skills
+
+```json
+{ "tool": "skills", "action": "list" }
+{ "tool": "skills", "action": "read", "name": "tools/files" }
+{ "tool": "skills", "action": "search", "query": "github pr" }
+```
+
+### Skill Locations
+
+- `skills/` -- built-in skills shipped with SwarmClaw
+- `data/skills/` -- user-created skills added at runtime
+
+### When to Load Skills
+
+- Before using a tool you're unfamiliar with
+- When a task involves an API or workflow you haven't used before
+- When the user asks you to do something and you're unsure of the best approach
+
+## Agent Capabilities
+
+### Memory
+
+Agents have persistent memory across sessions:
+
+- **Working memory** (session-scoped): scratch notes, intermediate results
+- **Durable memory** (cross-session): user preferences, project facts, decisions
+- Memories are automatically surfaced in context when relevant
+- Store important learnings proactively -- don't wait to be asked
+
+### Delegation
+
+Agents can delegate work to other agents:
+
+- **delegate**: route a task to a specific agent and wait for the result
+- **spawn**: create a subagent that runs independently (fire-and-forget or session-based)
+- Use `agents.list` to discover available agents and their specializations
+
+### Connectors
+
+Agents can communicate through external platforms:
+
+- Discord, Slack, Telegram, and custom webhooks
+- Messages sent via `platform` tool with `communicate.send_message`
+- Inbound messages from connectors trigger agent sessions automatically
+
+## Workspace Conventions
+
+- The workspace root is the agent's working directory
+- File paths in tool calls are relative to the workspace root
+- `/workspace/...` paths are resolved to the workspace root automatically
+- The `$WORKSPACE` env var points to the workspace root in execute tool runs
+
+## Best Practices
+
+1. **Load skills before unfamiliar operations.** A 30-second skill read prevents minutes of trial and error.
+
+2. **Use the right tool for the job.** Don't use `execute` with `echo > file.txt` when `files` write action is cleaner. Don't use `browser` when `curl` in `execute` suffices.
+
+3. **Store important context in memory.** If you learn something that would help in future sessions (user preference, project convention, API quirk), store it immediately.
+
+4. **Ask rather than guess.** When genuinely uncertain about user intent, use `communicate.ask_human`. A brief clarification is better than wasted work on the wrong approach.
+
+5. **Delegate when appropriate.** If another agent is better suited for a subtask, delegate. Check `agents.list` to know what's available.
+
+6. **Be explicit about what you're doing.** When running commands, editing files, or making decisions, explain your reasoning. Transparency builds trust.
+
+7. **Respect file access boundaries.** Stay within the workspace unless the agent has machine-scope access. Never write to system directories.
+
+8. **Handle errors gracefully.** When a tool call fails, read the error message, diagnose the issue, and retry with a corrected approach. Don't repeat the same failing call.

package/skills/tools/browser.md

@@ -0,0 +1,131 @@
+# Browser Tool
+
+Control a headless browser for interacting with web pages. Navigate, click, type, extract content, and take screenshots.
+
+## Actions
+
+| Action | Description | Key Parameters |
+|--------|-------------|----------------|
+| `navigate` | Go to a URL | `url` |
+| `click` | Click an element | `selector` or `text` |
+| `type` | Type into an input field | `selector`, `text` |
+| `screenshot` | Capture the current page | `fullPage` (optional) |
+| `extract_text` | Get text content from the page | `selector` (optional) |
+| `scroll` | Scroll the page | `direction`, `amount` |
+| `wait` | Wait for an element or condition | `selector`, `timeout` |
+
+## Navigate
+
+```json
+{ "action": "navigate", "url": "https://example.com/dashboard" }
+```
+
+Returns the page title and a summary of visible content.
+
+## Click
+
+```json
+{ "action": "click", "selector": "button.submit" }
+```
+
+Or click by visible text:
+
+```json
+{ "action": "click", "text": "Sign In" }
+```
+
+## Type
+
+```json
+{ "action": "type", "selector": "#search-input", "text": "SwarmClaw documentation" }
+```
+
+## Screenshot
+
+```json
+{ "action": "screenshot" }
+```
+
+Full page:
+
+```json
+{ "action": "screenshot", "fullPage": true }
+```
+
+Returns an image that you can analyze for layout, content, or visual verification.
+
+## Extract Text
+
+```json
+{ "action": "extract_text" }
+```
+
+Extracts all visible text from the page. Use `selector` to target a specific element:
+
+```json
+{ "action": "extract_text", "selector": "main.content" }
+```
+
+## Scroll
+
+```json
+{ "action": "scroll", "direction": "down", "amount": 500 }
+```
+
+## Wait
+
+```json
+{ "action": "wait", "selector": ".results-loaded", "timeout": 10000 }
+```
+
+Waits for an element to appear in the DOM. Useful after navigation or after triggering dynamic content.
+
+## Browser vs Execute (curl)
+
+| Scenario | Tool |
+|----------|------|
+| Static API call, JSON response | **execute** (`curl`) |
+| Page requires JavaScript rendering | **browser** |
+| Form submission with CSRF tokens | **browser** |
+| Downloading a file | **execute** (`curl`) |
+| Scraping dynamic content (React/Vue apps) | **browser** |
+| Simple GET request for HTML | **execute** (`curl`) |
+| Multi-step interaction (login, navigate, click) | **browser** |
+| Checking HTTP headers or status codes | **execute** (`curl`) |
+
+## Multi-Step Example
+
+Login and extract dashboard data:
+
+```json
+{ "action": "navigate", "url": "https://app.example.com/login" }
+```
+
+```json
+{ "action": "type", "selector": "#email", "text": "user@example.com" }
+```
+
+```json
+{ "action": "type", "selector": "#password", "text": "$APP_PASSWORD" }
+```
+
+```json
+{ "action": "click", "text": "Log In" }
+```
+
+```json
+{ "action": "wait", "selector": ".dashboard-loaded" }
+```
+
+```json
+{ "action": "extract_text", "selector": ".metrics-panel" }
+```
+
+## Tips
+
+- Always `wait` after `navigate` or `click` if the next action depends on dynamic content loading.
+- Use `extract_text` instead of `screenshot` when you need the data programmatically.
+- Use `screenshot` when you need to verify visual layout or debug what the page looks like.
+- Credentials referenced as `$ENV_VAR` are injected from the agent's credential configuration.
+- The browser session persists across tool calls within the same agent turn, so cookies and state are maintained.
+- Close the browser when done if you started it just for one task.

package/skills/tools/execute.md

@@ -0,0 +1,98 @@
+# Execute Tool
+
+Run bash scripts in a sandboxed or host environment with credential injection.
+
+## Usage
+
+```json
+{ "code": "curl -s https://api.example.com/data | jq '.results[]'" }
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `code` | string | Yes | The bash script to execute |
+| `persistent` | boolean | No | Use host backend for real filesystem writes (default: false) |
+| `timeout` | number | No | Timeout in seconds (default: 30, max: 300) |
+
+## Backends
+
+### Sandbox (default)
+- Powered by [just-bash](https://github.com/vercel-labs/just-bash)
+- **Reads** workspace files from disk via OverlayFS
+- **Writes** stay in memory (ephemeral)
+- 70+ built-in commands: ls, cat, grep, sed, awk, jq, yq, curl, git, find, sort, etc.
+- Execution limits: 1000 commands, 10000 loop iterations, 50 call depth
+- No npm, no Node.js — use host mode for that
+
+### Host (opt-in)
+- Real bash on the host system
+- Full filesystem access (respects file access policy)
+- npm, git, background processes, persistent writes
+- Inherits system PATH and environment
+
+## Environment Variables
+
+Credentials configured for the agent are injected as environment variables:
+
+| Variable | Source |
+|----------|--------|
+| `$WORKSPACE` | Workspace root directory |
+| `$<PROVIDER>_API_KEY` | Auto-named from credential provider |
+
+Secrets are **automatically redacted** from output.
+
+## Examples
+
+### Data processing
+```bash
+cat data.csv | awk -F',' '{print $2, $3}' | sort -n | head -20
+```
+
+### API call with credential injection
+```bash
+curl -s -H "Authorization: Bearer $OPENAI_API_KEY" \
+  https://api.openai.com/v1/models | jq '.data[].id'
+```
+
+### JSON transformation
+```bash
+curl -s https://api.github.com/repos/vercel/next.js/releases/latest \
+  | jq '{tag: .tag_name, date: .published_at, assets: [.assets[].name]}'
+```
+
+### File inspection (sandbox reads workspace via OverlayFS)
+```bash
+find /workspace/src -name "*.ts" | wc -l
+grep -r "TODO" /workspace/src --include="*.ts" -l
+```
+
+### Persistent write (host mode required)
+```json
+{ "code": "echo 'hello' > output.txt", "persistent": true }
+```
+
+## Limitations (Sandbox Mode)
+
+- No npm/Node.js (use host mode for package management)
+- No background processes
+- Writes are ephemeral (use `files` tool for persistent changes)
+- ~60 unimplemented bash features (PIPESTATUS, some `set -e` edge cases)
+- 64MB memory limit for JavaScript/Python runtimes
+- Use the `files` tool for precise code editing (sed/awk can be unreliable for multi-line edits)
+
+## When to Use Host Mode
+
+- Installing packages (`npm install`, `pip install`)
+- Running test suites (`npm test`, `pytest`)
+- Git operations that need persistence (`git commit`, `git push`)
+- Long-running processes
+- Using npm ecosystem libraries
+
+## Optional Runtimes (Sandbox Only)
+
+When enabled in agent config:
+- **Python**: `python3 -c 'print("hello")'`
+- **JavaScript**: `js-exec 'console.log("hello")'`
+- **SQLite**: `sqlite3 :memory: 'SELECT 1+1'`

package/skills/tools/files.md

@@ -0,0 +1,98 @@
+# Files Tool
+
+Precise file operations on the real filesystem. Read, write, edit, list, and search files within the workspace.
+
+## Actions
+
+| Action | Description | Key Parameters |
+|--------|-------------|----------------|
+| `read` | Read file contents | `path` (required) |
+| `write` | Create or overwrite a file | `path`, `content` (required) |
+| `edit` | Structured string replacement | `path`, `old_string`, `new_string` (required) |
+| `list` | List directory contents | `path` (optional, defaults to workspace root) |
+| `search` | Search file contents with regex | `query` (required), `path` (optional) |
+
+## Read
+
+```json
+{ "action": "read", "path": "src/index.ts" }
+```
+
+Reads the full file content. For large files, use `offset` and `limit` to read specific line ranges:
+
+```json
+{ "action": "read", "path": "src/index.ts", "offset": 50, "limit": 100 }
+```
+
+## Write
+
+```json
+{ "action": "write", "path": "src/config.ts", "content": "export const PORT = 3000\n" }
+```
+
+Creates the file if it doesn't exist. Creates parent directories automatically. Overwrites the entire file.
+
+## Edit (Structured Replacement)
+
+```json
+{
+  "action": "edit",
+  "path": "src/index.ts",
+  "old_string": "const port = 3000",
+  "new_string": "const port = process.env.PORT || 3000"
+}
+```
+
+**Rules:**
+- `old_string` must match exactly one location in the file (including whitespace and indentation)
+- If ambiguous, include more surrounding context to make it unique
+- Preserves the rest of the file unchanged
+- Preferred over `write` for modifying existing files (smaller diff, less error-prone)
+
+## List
+
+```json
+{ "action": "list", "path": "src/components" }
+```
+
+Returns directory entries with file types. Use `depth` to control recursion:
+
+```json
+{ "action": "list", "path": "src", "depth": 2 }
+```
+
+## Search
+
+```json
+{ "action": "search", "query": "TODO|FIXME", "path": "src" }
+```
+
+Searches file contents using regex patterns. Returns matching lines with file paths and line numbers.
+
+```json
+{ "action": "search", "query": "export function", "path": "src/lib", "glob": "*.ts" }
+```
+
+## File Access Policy
+
+- Workspace-scoped agents can only access files within the workspace directory
+- Machine-scoped agents can access the broader filesystem (subject to blocked path rules)
+- Paths like `/workspace/src/...` are automatically resolved to the workspace root
+- Path traversal (`../`) outside allowed scope is blocked
+
+## When to Use Files vs Execute
+
+| Task | Tool |
+|------|------|
+| Read/write/edit specific files | **files** |
+| Search across codebase | **files** (search action) |
+| Complex text processing (awk, sed, jq) | **execute** |
+| Running scripts or commands | **execute** |
+| Batch file operations | **execute** |
+
+## Tips
+
+- Use `edit` for surgical changes to existing files. It's safer than `write` because it only changes the targeted string.
+- Use `search` before `edit` to find the exact string to replace.
+- Use `list` to explore directory structure before reading specific files.
+- File paths are relative to the workspace root by default.

package/skills/tools/memory.md

@@ -0,0 +1,104 @@
+# Memory Tool
+
+Persistent knowledge storage across conversations. Store facts, preferences, context, and decisions so they survive beyond the current session.
+
+## Memory Tiers
+
+| Tier | Scope | Lifetime | Use For |
+|------|-------|----------|---------|
+| **Working** | Current session | Session duration | Scratch notes, intermediate results, task state |
+| **Durable** | Cross-session | Permanent until deleted | User preferences, project facts, learned patterns |
+| **Archive** | Cross-session | Permanent, lower priority | Completed task summaries, historical context |
+
+## Actions
+
+| Action | Description | Key Parameters |
+|--------|-------------|----------------|
+| `store` | Save a new memory | `title`, `value`, `category` |
+| `search` | Find memories by query | `query`, `scope` (optional) |
+| `get` | Retrieve a specific memory | `id` or `key` |
+| `update` | Modify an existing memory | `id`, `value` (and/or `title`, `category`) |
+
+## Store
+
+```json
+{
+  "action": "store",
+  "title": "User prefers dark mode",
+  "value": "The user explicitly asked for dark mode in all UI components. Use dark backgrounds (#1a1a2e) with light text (#e0e0e0).",
+  "category": "preference"
+}
+```
+
+### Categories
+
+| Category | When to Use |
+|----------|------------|
+| `preference` | User likes, dislikes, style choices |
+| `fact` | Verified information about user, project, or domain |
+| `decision` | Architecture decisions, design choices with rationale |
+| `context` | Background info that helps future conversations |
+| `note` | General observations, reminders |
+| `identity` | Agent's learned personality traits, communication style |
+
+## Search
+
+```json
+{ "action": "search", "query": "database schema preferences" }
+```
+
+Returns ranked results with relevance scores. Supports semantic-style matching (expanded query terms).
+
+### Scope Filtering
+
+```json
+{ "action": "search", "query": "API keys", "scope": "agent" }
+```
+
+| Scope | What It Searches |
+|-------|-----------------|
+| `auto` | Smart default: session + agent + global (recommended) |
+| `session` | Current session only |
+| `agent` | Current agent's memories |
+| `project` | Current project's memories |
+| `global` | Shared across all agents |
+| `all` | Everything |
+
+## Update
+
+```json
+{ "action": "update", "id": "mem_abc123", "value": "Updated: user now prefers system theme over dark mode" }
+```
+
+Use `update` when information changes. Avoids creating duplicate memories.
+
+## When to Remember
+
+**Do remember:**
+- User-stated preferences ("I prefer TypeScript", "always use tabs")
+- Corrections ("actually, the API endpoint is /v2/...")
+- Project-specific facts (tech stack, coding conventions, team structure)
+- Important decisions and their rationale
+
+**Do not remember:**
+- Ephemeral task details (file paths being edited right now)
+- Information already in the codebase (README, config files)
+- Trivial conversational context
+- Sensitive data (passwords, tokens, private keys)
+
+## When to Forget
+
+Use `update` to revise outdated memories rather than storing contradictory ones. If a memory is no longer relevant, update its value to reflect the current state.
+
+## Memory in Practice
+
+1. **Start of session**: Relevant memories are automatically injected into context based on the current agent, project, and conversation topic.
+2. **During conversation**: Store new insights as they emerge. Search when you need to recall something.
+3. **End of significant interaction**: Store a summary of decisions made, preferences learned, or context that would help next time.
+
+## Tips
+
+- Write memories in the third person for clarity: "The user prefers..." not "You prefer..."
+- Include enough context in the `value` that the memory is useful standalone
+- Use descriptive `title` fields -- they're used for search ranking
+- Prefer `category: "decision"` for architectural choices so they can be filtered later