agent-mind 1.0.0

package/template/.am-tools/health-check.sh

@@ -0,0 +1,165 @@
+#!/bin/bash
+
+##############################################################################
+# health-check.sh
+# Checks Agent Mind system health and reports issues
+#
+# Usage: bash .agent-mind/.am-tools/health-check.sh
+#
+# Exit codes:
+#   0 = Healthy (no issues)
+#   1 = Issues found
+##############################################################################
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Find .agent-mind root by walking up from script location
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AGENT_MIND_ROOT="$(cd "$(dirname "$SCRIPT_DIR")" && pwd)"
+
+# Thresholds
+BOOT_MD_MAX_LINES=150
+PROTOCOLS_MAX_LINES=200
+PATTERNS_MAX_LINES=200
+
+# Status tracking
+HEALTH_STATUS=0
+ISSUES_FOUND=0
+
+echo -e "${BLUE}========================================${NC}"
+echo -e "${BLUE}Agent Mind Health Check${NC}"
+echo -e "${BLUE}========================================${NC}"
+echo ""
+
+# Helper function to report status
+report_check() {
+  local check_name="$1"
+  local status="$2"
+  local message="$3"
+
+  case $status in
+    pass)
+      echo -e "${GREEN}✓ $check_name${NC}: $message"
+      ;;
+    warn)
+      echo -e "${YELLOW}⚠ $check_name${NC}: $message"
+      ISSUES_FOUND=$((ISSUES_FOUND + 1))
+      ;;
+    fail)
+      echo -e "${RED}✗ $check_name${NC}: $message"
+      HEALTH_STATUS=1
+      ISSUES_FOUND=$((ISSUES_FOUND + 1))
+      ;;
+  esac
+}
+
+# 1. Check line counts
+echo "📊 Line Counts:"
+echo ""
+
+# BOOT.md
+if [[ -f "$AGENT_MIND_ROOT/BOOT.md" ]]; then
+  boot_lines=$(wc -l < "$AGENT_MIND_ROOT/BOOT.md")
+  if (( boot_lines < BOOT_MD_MAX_LINES )); then
+    report_check "BOOT.md" "pass" "$boot_lines lines (< $BOOT_MD_MAX_LINES)"
+  else
+    report_check "BOOT.md" "warn" "$boot_lines lines (exceeds $BOOT_MD_MAX_LINES limit)"
+  fi
+else
+  report_check "BOOT.md" "fail" "File not found"
+fi
+
+# Protocol files
+echo ""
+if [[ -d "$AGENT_MIND_ROOT/protocols" ]]; then
+  for protocol_file in "$AGENT_MIND_ROOT/protocols"/*.md; do
+    if [[ -f "$protocol_file" ]]; then
+      proto_name=$(basename "$protocol_file")
+      proto_lines=$(wc -l < "$protocol_file")
+      if (( proto_lines < PROTOCOLS_MAX_LINES )); then
+        report_check "protocol: $proto_name" "pass" "$proto_lines lines (< $PROTOCOLS_MAX_LINES)"
+      else
+        report_check "protocol: $proto_name" "warn" "$proto_lines lines (exceeds $PROTOCOLS_MAX_LINES limit)"
+      fi
+    fi
+  done
+else
+  report_check "protocols/" "fail" "Directory not found"
+fi
+
+# Knowledge domain patterns
+echo ""
+if [[ -d "$AGENT_MIND_ROOT/knowledge" ]]; then
+  for domain_dir in "$AGENT_MIND_ROOT/knowledge"/*; do
+    if [[ -d "$domain_dir" ]]; then
+      domain_name=$(basename "$domain_dir")
+      patterns_file="$domain_dir/patterns.md"
+      if [[ -f "$patterns_file" ]]; then
+        patterns_lines=$(wc -l < "$patterns_file")
+        if (( patterns_lines < PATTERNS_MAX_LINES )); then
+          report_check "knowledge: $domain_name" "pass" "$patterns_lines lines (< $PATTERNS_MAX_LINES)"
+        else
+          report_check "knowledge: $domain_name" "warn" "$patterns_lines lines (exceeds $PATTERNS_MAX_LINES limit)"
+        fi
+      fi
+    fi
+  done
+fi
+
+# 2. Check for [UNVERIFIED] tags
+echo ""
+echo "🔍 Verification Status:"
+echo ""
+
+unverified_count=0
+if [[ -d "$AGENT_MIND_ROOT/knowledge" ]]; then
+  unverified_count=$(grep -r "\[UNVERIFIED\]" "$AGENT_MIND_ROOT/knowledge" 2>/dev/null | wc -l || true)
+fi
+
+if (( unverified_count == 0 )); then
+  report_check "Unverified tags" "pass" "No [UNVERIFIED] tags found"
+else
+  report_check "Unverified tags" "warn" "Found $unverified_count [UNVERIFIED] tags"
+fi
+
+# 3. Count episodes and insights
+echo ""
+echo "📈 Content Summary:"
+echo ""
+
+episodes_count=0
+if [[ -d "$AGENT_MIND_ROOT/history/episodes" ]]; then
+  episodes_count=$(find "$AGENT_MIND_ROOT/history/episodes" -name "*.md" -not -name "_index.md" | wc -l || true)
+fi
+report_check "Episodes recorded" "pass" "$episodes_count episode(s)"
+
+insights_count=0
+if [[ -d "$AGENT_MIND_ROOT/knowledge" ]]; then
+  insights_count=$(find "$AGENT_MIND_ROOT/knowledge" -name "*.md" -not -name "patterns.md" -not -name "_index.md" | wc -l || true)
+fi
+report_check "Knowledge insights" "pass" "$insights_count insight(s)"
+
+reflections_count=0
+if [[ -d "$AGENT_MIND_ROOT/history/reflections" ]]; then
+  reflections_count=$(find "$AGENT_MIND_ROOT/history/reflections" -name "*.md" -not -name "_index.md" | wc -l || true)
+fi
+report_check "Reflections recorded" "pass" "$reflections_count reflection(s)"
+
+# Summary
+echo ""
+echo -e "${BLUE}========================================${NC}"
+if (( HEALTH_STATUS == 0 && ISSUES_FOUND == 0 )); then
+  echo -e "${GREEN}✓ Agent Mind is healthy${NC}"
+else
+  echo -e "${YELLOW}⚠ Found $ISSUES_FOUND issue(s)${NC}"
+fi
+echo -e "${BLUE}========================================${NC}"
+
+exit $HEALTH_STATUS

package/template/.am-tools/validate.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+
+##############################################################################
+# validate.sh
+# Validates Agent Mind structure and required files
+#
+# Usage: bash .agent-mind/.am-tools/validate.sh
+#
+# Exit codes:
+#   0 = All checks passed
+#   1 = One or more checks failed
+##############################################################################
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Find .agent-mind root by walking up from script location
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+AGENT_MIND_ROOT="$(cd "$(dirname "$SCRIPT_DIR")" && pwd)"
+
+# Status tracking
+VALIDATION_STATUS=0
+PASSED_CHECKS=0
+FAILED_CHECKS=0
+
+echo -e "${BLUE}========================================${NC}"
+echo -e "${BLUE}Agent Mind Structure Validation${NC}"
+echo -e "${BLUE}========================================${NC}"
+echo ""
+
+# Helper function to report validation result
+check_item() {
+  local item_name="$1"
+  local item_path="$2"
+  local item_type="$3" # "dir" or "file"
+
+  if [[ "$item_type" == "dir" ]]; then
+    if [[ -d "$item_path" ]]; then
+      echo -e "${GREEN}✓ Directory exists: $item_name${NC}"
+      PASSED_CHECKS=$((PASSED_CHECKS + 1))
+    else
+      echo -e "${RED}✗ Directory missing: $item_name${NC}"
+      VALIDATION_STATUS=1
+      FAILED_CHECKS=$((FAILED_CHECKS + 1))
+    fi
+  elif [[ "$item_type" == "file" ]]; then
+    if [[ -f "$item_path" ]]; then
+      echo -e "${GREEN}✓ File exists: $item_name${NC}"
+      PASSED_CHECKS=$((PASSED_CHECKS + 1))
+    else
+      echo -e "${RED}✗ File missing: $item_name${NC}"
+      VALIDATION_STATUS=1
+      FAILED_CHECKS=$((FAILED_CHECKS + 1))
+    fi
+  fi
+}
+
+# 1. Check required directories
+echo "📁 Required Directories:"
+echo ""
+
+check_item "protocols/" "$AGENT_MIND_ROOT/protocols" "dir"
+check_item "knowledge/" "$AGENT_MIND_ROOT/knowledge" "dir"
+check_item "workspace/" "$AGENT_MIND_ROOT/workspace" "dir"
+check_item "history/" "$AGENT_MIND_ROOT/history" "dir"
+check_item "history/episodes/" "$AGENT_MIND_ROOT/history/episodes" "dir"
+check_item "history/reflections/" "$AGENT_MIND_ROOT/history/reflections" "dir"
+check_item "adapters/" "$AGENT_MIND_ROOT/adapters" "dir"
+
+# 2. Check required files at root
+echo ""
+echo "📄 Required Root Files:"
+echo ""
+
+check_item "BOOT.md" "$AGENT_MIND_ROOT/BOOT.md" "file"
+check_item "config.md" "$AGENT_MIND_ROOT/config.md" "file"
+check_item "VERSION.md" "$AGENT_MIND_ROOT/VERSION.md" "file"
+
+# 3. Check protocol files
+echo ""
+echo "📋 Protocol Files:"
+echo ""
+
+# Define expected protocols (can be customized)
+required_protocols=("reflexion.md" "memory.md" "tools.md")
+for protocol in "${required_protocols[@]}"; do
+  protocol_file="$AGENT_MIND_ROOT/protocols/$protocol"
+  if [[ -f "$protocol_file" ]]; then
+    echo -e "${GREEN}✓ Protocol exists: $protocol${NC}"
+    PASSED_CHECKS=$((PASSED_CHECKS + 1))
+  else
+    # Protocols might be optional depending on setup
+    echo -e "${YELLOW}⚠ Protocol not found (optional): $protocol${NC}"
+  fi
+done
+
+# 4. Validate BOOT.md references
+echo ""
+echo "🔗 BOOT.md References:"
+echo ""
+
+if [[ -f "$AGENT_MIND_ROOT/BOOT.md" ]]; then
+  # Extract file paths from BOOT.md (look for markdown links and file references)
+  # This is a basic check for relative paths
+  boot_refs=$(grep -oE '\./[^"\s\)]+|\.\/\.\.[^"\s\)]+' "$AGENT_MIND_ROOT/BOOT.md" 2>/dev/null || true)
+
+  if [[ -z "$boot_refs" ]]; then
+    echo -e "${GREEN}✓ BOOT.md reference check: OK (no external references or all valid)${NC}"
+    PASSED_CHECKS=$((PASSED_CHECKS + 1))
+  else
+    # Check each reference exists
+    ref_valid=true
+    while IFS= read -r ref; do
+      # Normalize path (remove leading ./)
+      normalized_ref="${ref#./}"
+      full_path="$AGENT_MIND_ROOT/$normalized_ref"
+
+      if [[ ! -e "$full_path" ]]; then
+        echo -e "${RED}✗ Invalid reference in BOOT.md: $ref${NC}"
+        ref_valid=false
+        VALIDATION_STATUS=1
+        FAILED_CHECKS=$((FAILED_CHECKS + 1))
+      fi
+    done <<< "$boot_refs"
+
+    if [[ "$ref_valid" == true ]]; then
+      echo -e "${GREEN}✓ BOOT.md references are valid${NC}"
+      PASSED_CHECKS=$((PASSED_CHECKS + 1))
+    fi
+  fi
+else
+  echo -e "${RED}✗ Cannot validate BOOT.md (file not found)${NC}"
+  VALIDATION_STATUS=1
+  FAILED_CHECKS=$((FAILED_CHECKS + 1))
+fi
+
+# 5. Check config.md structure
+echo ""
+echo "⚙️  Configuration:"
+echo ""
+
+if [[ -f "$AGENT_MIND_ROOT/config.md" ]]; then
+  # Check for at least some basic structure
+  if grep -q "^#" "$AGENT_MIND_ROOT/config.md"; then
+    echo -e "${GREEN}✓ config.md has valid markdown structure${NC}"
+    PASSED_CHECKS=$((PASSED_CHECKS + 1))
+  else
+    echo -e "${YELLOW}⚠ config.md might not have valid structure${NC}"
+  fi
+else
+  echo -e "${RED}✗ config.md not found${NC}"
+  VALIDATION_STATUS=1
+  FAILED_CHECKS=$((FAILED_CHECKS + 1))
+fi
+
+# Summary
+echo ""
+echo -e "${BLUE}========================================${NC}"
+echo -e "Passed: ${GREEN}$PASSED_CHECKS${NC} | Failed: ${RED}$FAILED_CHECKS${NC}"
+
+if (( VALIDATION_STATUS == 0 )); then
+  echo -e "${GREEN}✓ All validation checks passed${NC}"
+else
+  echo -e "${RED}✗ Validation failed - see errors above${NC}"
+fi
+echo -e "${BLUE}========================================${NC}"
+
+exit $VALIDATION_STATUS

package/template/BOOT.md

@@ -0,0 +1,71 @@
+# Agent Mind — Boot Protocol
+
+You have access to a cognitive memory system in `.agent-mind/`. It helps you think better, remember what matters, and improve over time. Read this file first, every session. Non-negotiable.
+
+## Session Start
+
+1. Read this file (you're doing it now)
+2. Read `.agent-mind/config.md` for project context
+3. Check `.agent-mind/workspace/` — if files exist, a task is in progress. Resume it.
+4. Scan `.agent-mind/knowledge/insights.md` for accumulated learnings
+5. You're now ready to work
+
+## When You Receive a Task
+
+Follow `.agent-mind/protocols/workflow.md`. The short version:
+
+1. **Understand** — What is actually being asked? What's the real goal?
+2. **Load context** — Check `knowledge/domains/` and `knowledge/stack/` for relevant knowledge. Check `knowledge/insights.md`. Check `history/episodes/_index.md` for related past work.
+3. **Think critically** — What could go wrong? Check failure libraries in matched domains. Identify unknowns. Write BLOCKING unknowns to `workspace/questions.md` and HALT.
+4. **Work** — Only after unknowns are resolved. Log decisions to `workspace/decisions.md`.
+5. **Capture** — Follow `protocols/compaction.md`. Summarize, extract insights, clear workspace.
+
+## Rules That Never Bend
+
+1. **Never implement before clarity.** If you don't understand what you're building, stop and ask.
+2. **BLOCKING unknowns = HALT.** Write them to `workspace/questions.md`. Ask the human. Do not guess on things that matter.
+3. **Capture after every task.** Follow `protocols/compaction.md` to consolidate learning.
+4. **Never delete history.** Files in `history/` are append-only. Never delete, only add.
+5. **Gate your writes.** Before writing to `knowledge/`, check `protocols/quality-gate.md`. Not everything deserves to be remembered. Bad memories poison the system.
+6. **Stay concise.** Keep this file and all `protocols/` files under 200 lines.
+
+## Memory System
+
+Your memory has three temperatures:
+
+**Hot (always loaded):** This file, `config.md`, files in `protocols/`. Your operating system. Loaded every session.
+
+**Warm (loaded by relevance):** `knowledge/domains/`, `knowledge/stack/`, `knowledge/insights.md`. Load these based on what the current task needs. Don't load everything — load what's relevant.
+
+**Cold (searched on demand):** `history/episodes/`, `history/reflections/`. Search when you need historical context, past decisions, or failure analysis.
+
+## Self-Maintenance
+
+You are not autonomous. You think, then propose. The human decides.
+
+**Trigger:** At session start, check `history/maintenance-log.md`. If the last entry is more than 2 weeks old (or no entries exist and `history/episodes/_index.md` has 5+ entries), suggest to the human: "Memory maintenance is due. Want me to run a health check?"
+
+When running maintenance, follow `protocols/maintenance.md` to:
+- Check memory health (stale insights? growing too large? contradictions?)
+- Flag memories you're uncertain about
+- Propose cleanup actions to the human
+- Report on what's working and what's not
+
+If you notice something wrong with your memory during normal work — a pattern that led you astray, an insight that contradicts evidence — flag it immediately. Don't wait for scheduled maintenance.
+
+## Adapters
+
+If you are Claude Code, also read `.agent-mind/adapters/claude.md`.
+If you are Codex / OpenAI Agents, also read `.agent-mind/adapters/codex.md`.
+If you are Gemini CLI, also read `.agent-mind/adapters/gemini.md`.
+If you are Cursor, also read `.agent-mind/adapters/cursor.md`.
+
+These contain tool-specific integration instructions.
+
+## Extending This System
+
+- **New domain knowledge?** Create a folder in `knowledge/domains/[name]/` with `patterns.md` and `failures/_index.md`. See `knowledge/domains/_template/` for the format.
+- **New tech stack knowledge?** Create `knowledge/stack/[tech].md`. See `knowledge/stack/_template.md`.
+- **Custom protocols?** Add `.md` files to `protocols/`. Reference them from this file or from workflow.md.
+
+The structure is the product. Extend it by creating markdown files.

package/template/README.md

@@ -0,0 +1,109 @@
+# Agent Mind
+
+A standalone cognitive memory system for LLM agents. Drop this folder into any project. Any LLM tool (Claude Code, Codex, Gemini CLI, Cursor, or others) can use it to think better, remember what matters, and improve over time.
+
+## What This Is
+
+A folder of markdown files that gives any LLM agent:
+
+- **Structured thinking** — a workflow protocol that ensures understanding before implementation
+- **Persistent memory** — knowledge that survives across sessions, organized by domain
+- **Learning from experience** — every completed task feeds back into domain knowledge
+- **Failure prevention** — known failure patterns are checked before new work begins
+- **Self-maintenance** — protocols for checking memory health and preventing degradation
+- **Tool agnosticism** — works with any LLM tool that can read files
+
+No databases. No embeddings. No external services. Just `.md` files that any LLM can read.
+
+## Quick Start
+
+1. Copy the `.agent-mind/` folder into your project root
+2. Edit `config.md` with your project details
+3. Set up your LLM tool's integration (see `adapters/` for your tool)
+4. Start working — the agent follows the protocols in `BOOT.md`
+
+## How It Works
+
+The agent reads `BOOT.md` at the start of every session. BOOT.md tells it how to:
+- Load relevant knowledge before starting work
+- Think critically (check failure patterns, identify unknowns)
+- Capture learning after every task
+- Maintain memory health over time
+
+### Memory Architecture
+
+Three tiers, mapped to cognitive science:
+
+| Tier | Directory | Temperature | When Loaded |
+|------|-----------|-------------|-------------|
+| Working memory | `workspace/` | Hot | During active task, cleared after |
+| Semantic memory | `knowledge/` | Warm | When domain/tech matches current task |
+| Episodic memory | `history/` | Cold | Searched on demand for past context |
+| Procedural memory | `protocols/` | Hot | Operating instructions, always available |
+
+### The Learning Loop
+
+1. **Work** → agent follows workflow protocol
+2. **Capture** → compaction protocol extracts insights from completed tasks
+3. **Accumulate** → insights stored with vote counts, patterns stored by domain
+4. **Apply** → next task loads relevant knowledge, including from past work
+5. **Maintain** → periodic health checks prune bad memories, promote good ones
+
+This is backed by research: ExpeL (cross-task learning), Reflexion (failure analysis), SimpleMem (quality-gated writes), MemGPT (tiered memory management).
+
+## Directory Structure
+
+```
+.agent-mind/
+├── BOOT.md              ← Agent entry point (read first, every session)
+├── config.md            ← Project settings
+├── README.md            ← This file (for humans)
+│
+├── protocols/           ← HOW the agent operates (procedural memory)
+│   ├── workflow.md      ← Thinking & working process
+│   ├── memory-ops.md    ← Memory read/write rules
+│   ├── compaction.md    ← Post-task learning capture
+│   ├── maintenance.md   ← Memory health & cleanup
+│   └── quality-gate.md  ← What deserves to be remembered
+│
+├── knowledge/           ← WHAT the agent knows (semantic memory)
+│   ├── domains/         ← Domain expertise (patterns + failures)
+│   ├── stack/           ← Technology-specific knowledge
+│   └── insights.md      ← Cross-domain learnings with vote counts
+│
+├── workspace/           ← Current task (working memory, cleared after)
+│
+├── history/             ← What has happened (episodic memory)
+│   ├── episodes/        ← Task summaries + index
+│   ├── reflections/     ← Failure analysis
+│   └── maintenance-log.md
+│
+└── adapters/            ← Tool-specific integration
+    ├── claude.md        ← Claude Code setup
+    ├── codex.md         ← OpenAI Codex setup
+    ├── gemini.md        ← Gemini CLI setup
+    └── cursor.md        ← Cursor setup
+```
+
+## Design Principles
+
+1. **Everything is markdown.** If it can't be a `.md` file, it doesn't belong here.
+2. **The structure is the product.** Extend by creating folders and files. No code needed.
+3. **Quality over quantity.** Not everything gets remembered. Bad memories poison the system.
+4. **Human drives, agent maintains.** The agent proposes; the human decides.
+5. **Nothing is deleted, only moved.** History is append-only. Cold storage preserves everything.
+6. **Non-disruptive.** Drop in, remove later. No changes to your project files.
+
+## Research Foundation
+
+Built on findings from:
+- **Letta/MemGPT:** Filesystem-based memory achieves 74% on LoCoMo (beating Mem0's 68.5% graph DB)
+- **Claude Code:** Files under 200 lines achieve >92% instruction adherence
+- **ExpeL:** Cross-task insight extraction with vote-based promotion (+31% on ALFWorld)
+- **Reflexion:** Self-critique after failure (+22% on AlfWorld, +20% on HotPotQA)
+- **SimpleMem:** Quality-gated writes prevent self-degradation (26.4% improvement over Mem0)
+- **Xiong et al.:** Naive "remember everything" causes sustained performance decline
+
+## License
+
+MIT — use it, modify it, share it.

package/template/VERSION.md

@@ -0,0 +1,57 @@
+# Agent Mind — Version & Manifest
+
+## Installation Info
+- **Installed version:** {{VERSION}}
+- **Installed date:** {{DATE}}
+- **npm package:** agent-mind
+
+---
+
+## Core Files (Managed by Upgrade)
+
+These files are replaced when you upgrade the agent-mind package. They should not be edited locally — any customizations will be lost.
+
+- `BOOT.md` — Agent entry point and session start protocol
+- `protocols/workflow.md` — 5-phase thinking process
+- `protocols/memory-ops.md` — Memory read/write rules and file limits
+- `protocols/compaction.md` — Post-task consolidation protocol
+- `protocols/quality-gate.md` — Memory quality filter
+- `protocols/maintenance.md` — Self-maintenance protocol
+- `.agent-mind/.am-tools/guide.md` — Tool documentation
+- `adapters/claude.md` — Claude Code integration
+- `adapters/codex.md` — OpenAI Codex integration
+- `adapters/gemini.md` — Gemini CLI integration
+- `adapters/cursor.md` — Cursor integration
+- `VERSION.md` — This file
+
+---
+
+## User Files (Never Touched on Upgrade)
+
+These files are yours. The upgrade process will never modify them, even if major updates happen. You control these entirely.
+
+- `config.md` — Project configuration and context
+- `README.md` — Project-specific agent mind setup notes (if you create one)
+- `knowledge/domains/*/patterns.md` — Domain-specific patterns you've learned
+- `knowledge/domains/*/failures/` — Failure libraries you've built
+- `knowledge/stack/` — Stack-specific knowledge
+- `knowledge/insights.md` — Cross-domain learnings
+- `workspace/` — Working memory (ephemeral, cleared after compaction)
+- `history/episodes/` — Episodic memory (task records)
+- `history/episodes/_index.md` — Episode index
+- `history/reflections/` — Failure reflections
+- `history/reflections/_index.md` — Reflections index
+- `history/maintenance-log.md` — Maintenance audit trail
+
+---
+
+## Upgrade Behavior
+
+When you run `npx agent-mind upgrade` or receive a new version:
+
+1. Core files are replaced with the new version
+2. User files are never touched
+3. A backup of your previous core files is created in `.agent-mind/_backups/[version]/` (optional, kept for reference)
+4. If you have customized any core files, consider moving those customizations to `config.md` or creating a custom protocol file
+
+If you need to extend the system, create new files in `protocols/` (custom protocols) rather than editing existing ones.

package/template/adapters/claude.md

@@ -0,0 +1,56 @@
+# Claude Code Integration
+
+## Setup
+
+Add this block to your project's `CLAUDE.md`:
+
+```markdown
+## Agent Mind Memory System
+This project uses Agent Mind for structured memory management.
+At the start of every session, read `.agent-mind/BOOT.md` and follow its protocols.
+Use `.agent-mind/workspace/` as working memory for the current task.
+After completing a task, follow `.agent-mind/protocols/compaction.md`.
+When asked about memory health, follow `.agent-mind/protocols/maintenance.md`.
+```
+
+## How It Works
+
+- Claude Code reads `CLAUDE.md` at session start — that's its native instruction file
+- The snippet above makes Claude Code aware of the `.agent-mind/` system
+- Claude Code can read arbitrary files, so all `.agent-mind/` content is accessible
+- Keep the CLAUDE.md snippet under 10 lines — it just points to BOOT.md for details
+
+## Coexistence With Claude's Native Memory
+
+Claude Code has its own memory systems:
+- `~/.claude/CLAUDE.md` — user-level preferences
+- `.claude/rules/*.md` — glob-matched rules
+- `~/.claude/projects/[hash]/memory/` — auto-memory
+
+Agent Mind complements these:
+- Claude's auto-memory: session-level, unstructured, tool-specific
+- Agent Mind: project-level, structured (episodic/semantic/procedural), tool-agnostic
+
+They don't conflict. Use both. Claude's auto-memory handles session continuity. Agent Mind handles structured learning and cross-tool knowledge.
+
+## Claude-Specific Tips
+
+- Claude Code follows instructions in CLAUDE.md ~92% of the time for files under 200 lines
+- All Agent Mind protocol files are kept under 200 lines for this reason
+- Claude responds well to clear, imperative instructions ("read X", "write to Y", "HALT if Z")
+- The BOOT.md and protocol files are written in this style deliberately
+- Claude's `/compact` command resets context but re-reads CLAUDE.md from disk — Agent Mind survives compaction
+
+## Recommended CLAUDE.md Structure
+
+```markdown
+# Project Instructions
+
+## Agent Mind
+[snippet above]
+
+## Project-Specific Rules
+[your existing CLAUDE.md rules]
+```
+
+Put the Agent Mind block early in CLAUDE.md so it gets high attention from the model.

package/template/adapters/codex.md

@@ -0,0 +1,33 @@
+# OpenAI Codex / Agents Integration
+
+## Setup
+
+Add this block to your project's `AGENTS.md`:
+
+```markdown
+## Agent Mind Memory System
+This project uses Agent Mind for structured memory management.
+At the start of every session, read `.agent-mind/BOOT.md` and follow its protocols.
+Use `.agent-mind/workspace/` as working memory for the current task.
+After completing a task, follow `.agent-mind/protocols/compaction.md`.
+When asked about memory health, follow `.agent-mind/protocols/maintenance.md`.
+```
+
+## How It Works
+
+- Codex CLI reads `AGENTS.md` at session start — that's its native instruction file
+- The snippet makes Codex aware of the `.agent-mind/` system
+- Codex can read files from the filesystem, so all `.agent-mind/` content is accessible
+
+## Coexistence
+
+- Codex has its own context management via AGENTS.md
+- Agent Mind adds structured memory on top — they complement each other
+- Agent Mind's `knowledge/` persists across Codex sessions
+- Codex's native context resets each session; Agent Mind's doesn't
+
+## Codex-Specific Tips
+
+- Codex in `--full-auto` mode may skip some protocol steps. Consider running without `--full-auto` for tasks that benefit from the full thinking workflow
+- For code execution tasks, the workflow's Phase 3 (Think Critically) is especially valuable — Codex tends to jump straight to implementation
+- Keep AGENTS.md snippets concise. Codex's instruction adherence improves with shorter, clearer instructions