agent-mind 1.0.0

package/src/utils/template.js

@@ -0,0 +1,103 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Get the path to the template directory
+ * Resolves from the package root
+ */
+function getTemplatePath() {
+  // From src/utils/template.js, go up to package root, then to template/
+  return path.join(__dirname, '../../template');
+}
+
+/**
+ * Copy template directory to target location, preserving structure
+ * @param {string} targetDir - Destination directory path
+ */
+function copyTemplate(targetDir) {
+  const templatePath = getTemplatePath();
+
+  if (!fs.existsSync(templatePath)) {
+    throw new Error(`Template directory not found at ${templatePath}`);
+  }
+
+  // Create target directory
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+
+  // Recursively copy all files
+  function copyDir(src, dest) {
+    const items = fs.readdirSync(src);
+
+    items.forEach(item => {
+      const srcPath = path.join(src, item);
+      const destPath = path.join(dest, item);
+      const stat = fs.statSync(srcPath);
+
+      if (stat.isDirectory()) {
+        if (!fs.existsSync(destPath)) {
+          fs.mkdirSync(destPath, { recursive: true });
+        }
+        copyDir(srcPath, destPath);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    });
+  }
+
+  copyDir(templatePath, targetDir);
+}
+
+/**
+ * Replace template variables in a file
+ * Supports {{VAR}} format
+ * @param {string} filePath - Path to file
+ * @param {Object} variables - Key-value pairs for replacement
+ */
+function replaceVars(filePath, variables) {
+  let content = fs.readFileSync(filePath, 'utf8');
+
+  // Replace each variable
+  Object.entries(variables).forEach(([key, value]) => {
+    const placeholder = `{{${key}}}`;
+    const regex = new RegExp(placeholder, 'g');
+    content = content.replace(regex, String(value));
+  });
+
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+/**
+ * Replace variables in all files in a directory (recursively)
+ * @param {string} dirPath - Directory path
+ * @param {Object} variables - Key-value pairs for replacement
+ */
+function replaceVarsInDir(dirPath, variables) {
+  const items = fs.readdirSync(dirPath);
+
+  items.forEach(item => {
+    const fullPath = path.join(dirPath, item);
+    const stat = fs.statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      replaceVarsInDir(fullPath, variables);
+    } else if (stat.isFile()) {
+      // Only process text files
+      if (!['.png', '.jpg', '.jpeg', '.gif', '.zip', '.tar'].some(ext => item.endsWith(ext))) {
+        try {
+          replaceVars(fullPath, variables);
+        } catch (error) {
+          // Silently skip binary files
+        }
+      }
+    }
+  });
+}
+
+module.exports = {
+  getTemplatePath,
+  copyTemplate,
+  replaceVars,
+  replaceVarsInDir
+};

package/src/utils/version.js

@@ -0,0 +1,71 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Get the package version from package.json
+ */
+function getPackageVersion() {
+  const packageJsonPath = path.join(__dirname, '../../package.json');
+  try {
+    const content = fs.readFileSync(packageJsonPath, 'utf8');
+    const pkg = JSON.parse(content);
+    return pkg.version;
+  } catch (error) {
+    throw new Error(`Failed to read package version: ${error.message}`);
+  }
+}
+
+/**
+ * Get the current Agent Mind version from .agent-mind/VERSION.md
+ * @param {string} [agentMindDir='.agent-mind'] - Path to agent-mind directory
+ */
+function getCurrentVersion(agentMindDir = '.agent-mind') {
+  const versionPath = path.join(agentMindDir, 'VERSION.md');
+
+  if (!fs.existsSync(versionPath)) {
+    throw new Error(`Agent Mind not initialized. Run "agent-mind init" first.`);
+  }
+
+  try {
+    const content = fs.readFileSync(versionPath, 'utf8');
+    // Parse version from lines like:
+    // - "- **Installed version:** 1.0.0"
+    // - "- **Installed version:** {{VERSION}}"
+    let match = content.match(/Installed version:\*\*\s*{{VERSION}}/);
+    if (match) {
+      // Template hasn't been initialized yet - shouldn't reach here in normal flow
+      throw new Error('Agent Mind template not initialized - run "agent-mind init"');
+    }
+    // Match semver pattern: X.Y.Z (the markdown may have ** before/after)
+    match = content.match(/Installed version:\*\*\s*([0-9]+\.[0-9]+\.[0-9]+)/);
+    if (match) {
+      return match[1];
+    }
+    throw new Error('Version format not recognized in VERSION.md');
+  } catch (error) {
+    if (error.message.includes('Agent Mind template not initialized')) {
+      throw error;
+    }
+    throw new Error(`Failed to read Agent Mind version: ${error.message}`);
+  }
+}
+
+/**
+ * Check if upgrade is needed
+ * @param {string} [agentMindDir='.agent-mind'] - Path to agent-mind directory
+ */
+function needsUpgrade(agentMindDir = '.agent-mind') {
+  try {
+    const current = getCurrentVersion(agentMindDir);
+    const pkg = getPackageVersion();
+    return current !== pkg;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  getPackageVersion,
+  getCurrentVersion,
+  needsUpgrade
+};

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

@@ -0,0 +1,171 @@
+#!/bin/bash
+
+##############################################################################
+# compact.sh
+# Mechanical compaction tool for Agent Mind episodes and reflections
+#
+# Usage: bash .agent-mind/.am-tools/compact.sh \
+#   --task "slug" \
+#   --outcome "completed|failed|abandoned" \
+#   --domain "domain" \
+#   --summary "one line" \
+#   [--clear-workspace]
+##############################################################################
+
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+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)"
+
+# Parse command-line arguments
+TASK_SLUG=""
+OUTCOME=""
+DOMAIN=""
+SUMMARY=""
+CLEAR_WORKSPACE=false
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --task)
+      TASK_SLUG="$2"
+      shift 2
+      ;;
+    --outcome)
+      OUTCOME="$2"
+      shift 2
+      ;;
+    --domain)
+      DOMAIN="$2"
+      shift 2
+      ;;
+    --summary)
+      SUMMARY="$2"
+      shift 2
+      ;;
+    --clear-workspace)
+      CLEAR_WORKSPACE=true
+      shift
+      ;;
+    *)
+      echo -e "${RED}Unknown option: $1${NC}"
+      exit 1
+      ;;
+  esac
+done
+
+# Validate required arguments
+if [[ -z "$TASK_SLUG" || -z "$OUTCOME" || -z "$DOMAIN" || -z "$SUMMARY" ]]; then
+  echo -e "${RED}Error: Missing required arguments${NC}"
+  echo "Usage: bash .agent-mind/.am-tools/compact.sh \\"
+  echo "  --task \"slug\" \\"
+  echo "  --outcome \"completed|failed|abandoned\" \\"
+  echo "  --domain \"domain\" \\"
+  echo "  --summary \"one line\" \\"
+  echo "  [--clear-workspace]"
+  exit 1
+fi
+
+# Validate outcome value
+if [[ ! "$OUTCOME" =~ ^(completed|failed|abandoned)$ ]]; then
+  echo -e "${RED}Error: outcome must be 'completed', 'failed', or 'abandoned'${NC}"
+  exit 1
+fi
+
+# Get current date and time
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+YEAR_MONTH=$(date -u +"%Y-%m")
+
+# Create history/episodes directory if needed
+EPISODES_DIR="$AGENT_MIND_ROOT/history/episodes/$YEAR_MONTH"
+mkdir -p "$EPISODES_DIR"
+
+# Create episode file
+EPISODE_FILE="$EPISODES_DIR/${TASK_SLUG}.md"
+cat > "$EPISODE_FILE" << EOF
+# Episode: $TASK_SLUG
+
+**Domain**: $DOMAIN
+**Outcome**: $OUTCOME
+**Date**: $NOW
+
+## Summary
+$SUMMARY
+
+---
+_Auto-created by compact.sh_
+EOF
+
+echo -e "${GREEN}✓ Created episode: $EPISODE_FILE${NC}"
+
+# Append one-liner to _index.md
+INDEX_FILE="$AGENT_MIND_ROOT/history/episodes/_index.md"
+if [[ ! -f "$INDEX_FILE" ]]; then
+  echo "# Episodes Index" > "$INDEX_FILE"
+  echo "" >> "$INDEX_FILE"
+fi
+echo "- \`$YEAR_MONTH/$TASK_SLUG.md\` [$OUTCOME] $SUMMARY" >> "$INDEX_FILE"
+echo -e "${GREEN}✓ Updated episodes index${NC}"
+
+# If outcome is "failed", create reflection
+if [[ "$OUTCOME" == "failed" ]]; then
+  REFLECTIONS_DIR="$AGENT_MIND_ROOT/history/reflections"
+  mkdir -p "$REFLECTIONS_DIR"
+
+  REFLECTION_FILE="$REFLECTIONS_DIR/${TASK_SLUG}-reflection.md"
+  cat > "$REFLECTION_FILE" << EOF
+# Reflection: $TASK_SLUG (Failed)
+
+**Domain**: $DOMAIN
+**Original Summary**: $SUMMARY
+**Date**: $NOW
+
+## What Went Wrong
+[To be filled in by agent or human]
+
+## Lessons Learned
+[To be filled in by agent or human]
+
+## Next Steps
+[To be filled in by agent or human]
+
+---
+_Auto-created by compact.sh for failed episode_
+EOF
+
+  echo -e "${GREEN}✓ Created reflection: $REFLECTION_FILE${NC}"
+
+  # Append to reflections _index.md
+  REFLECTIONS_INDEX="$AGENT_MIND_ROOT/history/reflections/_index.md"
+  if [[ ! -f "$REFLECTIONS_INDEX" ]]; then
+    echo "# Reflections Index" > "$REFLECTIONS_INDEX"
+    echo "" >> "$REFLECTIONS_INDEX"
+  fi
+  echo "- \`${TASK_SLUG}-reflection.md\` (from \`$YEAR_MONTH/$TASK_SLUG.md\`)" >> "$REFLECTIONS_INDEX"
+  echo -e "${GREEN}✓ Updated reflections index${NC}"
+fi
+
+# Clear workspace if requested
+if [[ "$CLEAR_WORKSPACE" == true ]]; then
+  WORKSPACE_DIR="$AGENT_MIND_ROOT/workspace"
+  if [[ -d "$WORKSPACE_DIR" ]]; then
+    # Find and remove files, but keep the directory structure
+    find "$WORKSPACE_DIR" -type f -exec rm -f {} +
+    echo -e "${GREEN}✓ Cleared workspace files${NC}"
+  fi
+fi
+
+echo ""
+echo -e "${GREEN}✓ Compaction complete${NC}"
+echo "  Episode: $EPISODE_FILE"
+echo "  Domain: $DOMAIN"
+echo "  Outcome: $OUTCOME"
+if [[ "$CLEAR_WORKSPACE" == true ]]; then
+  echo "  Workspace: cleared"
+fi

package/template/.am-tools/guide.md

@@ -0,0 +1,274 @@
+# Agent Mind Tools — Guide
+
+These scripts are **optional utilities** for handling mechanical memory operations. You can do everything manually by editing files directly, or use these scripts to speed up common operations.
+
+**When to use them:** After following `protocols/compaction.md` and `protocols/maintenance.md`, when you need quick file operations.
+
+**Important:** These tools are helpers, not replacements for the thinking protocols. Always follow the protocol logic first, then use tools to execute the mechanical parts.
+
+---
+
+## Tool: `am-compact`
+
+**Purpose:** Create an episode summary file after a completed task.
+
+**When:** After Phase 5 of `protocols/workflow.md`, to create the episode file structure.
+
+**Usage:**
+```bash
+./am-compact [task-slug] [domain] [outcome] [summary]
+```
+
+**Parameters:**
+- `task-slug` — kebab-case identifier for the task (e.g., `auth-token-validation`)
+- `domain` — domain name(s) touched, comma-separated (e.g., `auth,security`)
+- `outcome` — one of: `completed`, `failed`, `abandoned`
+- `summary` — one-line summary (quoted if spaces)
+
+**Example:**
+```bash
+./am-compact "auth-token-validation" "auth,security" completed "Implemented JWT expiry validation with clock skew buffer"
+```
+
+**What it does:**
+1. Creates `history/episodes/YYYY-MM/[task-slug].md` with template structure
+2. Appends a line to `history/episodes/_index.md`
+3. Opens the episode file for you to fill in details (key insight, assumptions made, etc.)
+
+**Manual alternative:** Create the file directly in `history/episodes/YYYY-MM/[task-slug].md` following the format in `protocols/compaction.md`.
+
+---
+
+## Tool: `am-reflect`
+
+**Purpose:** Create a reflection file for a failed task.
+
+**When:** After a task fails and you're following Path B of `protocols/compaction.md`.
+
+**Usage:**
+```bash
+./am-reflect [task-slug] [domain] [what-went-wrong]
+```
+
+**Parameters:**
+- `task-slug` — same identifier used in the episode
+- `domain` — domain where failure occurred
+- `what-went-wrong` — one-line summary of the failure
+
+**Example:**
+```bash
+./am-reflect "auth-token-validation" "auth" "Clock skew buffer off by 1ms, caused false rejections in high-latency environments"
+```
+
+**What it does:**
+1. Creates `history/reflections/YYYY-MM-DD-[slug].md` with reflection structure
+2. Appends entry to `history/reflections/_index.md`
+3. Opens the file for you to fill in root cause analysis and detection conditions
+
+**Manual alternative:** Create the file directly following the format in `protocols/compaction.md`.
+
+---
+
+## Tool: `am-insight`
+
+**Purpose:** Manage cross-domain insights in `knowledge/insights.md`.
+
+**When:** During Phase 3 of compaction when you've identified a generalizable learning.
+
+**Usage:**
+```bash
+./am-insight add [title] [insight] [domains]
+./am-insight upvote [insight-number]
+./am-insight downvote [insight-number]
+./am-insight remove [insight-number]
+```
+
+**Examples:**
+```bash
+./am-insight add "JWT Validation" "Always validate JWT expiry with a clock skew buffer of 30-60 seconds" "auth,security"
+./am-insight upvote 3
+./am-insight downvote 5
+```
+
+**What it does:**
+- `add`: Creates a new insight entry with `votes: 1`
+- `upvote`: Increments the vote count for an insight (confirms it)
+- `downvote`: Decrements the vote count (contradicts it)
+- `remove`: Deletes an insight with votes < -2
+
+**Format it uses:**
+```markdown
+### [Title]
+- **Insight:** [the learning]
+- **Domains:** [domains]
+- **Votes:** [number]
+- **Added:** YYYY-MM-DD | **Last touched:** YYYY-MM-DD
+- **Evidence:** [tasks confirming/contradicting]
+```
+
+**Manual alternative:** Edit `knowledge/insights.md` directly.
+
+---
+
+## Tool: `am-pattern`
+
+**Purpose:** Add a pattern to a domain's patterns.md file.
+
+**When:** During Phase 3 of compaction, when you've identified a reusable approach.
+
+**Usage:**
+```bash
+./am-pattern [domain] [pattern-name] [when] [what] [why]
+```
+
+**Parameters:**
+- `domain` — target domain (will create if doesn't exist)
+- `pattern-name` — short name for the pattern
+- `when` — conditions when this pattern applies
+- `what` — the approach/technique
+- `why` — reasoning
+
+**Example:**
+```bash
+./am-pattern "auth" "jwt-clock-skew" \
+  "Validating JWT expiry in distributed systems" \
+  "Add 30-60s clock skew buffer to expiry check" \
+  "Handles clock drift between services without rejecting valid tokens"
+```
+
+**What it does:**
+1. Opens or creates `knowledge/domains/[domain]/patterns.md`
+2. Appends the pattern with today's date and originating task slug
+3. Keeps the file under 200 lines (suggests archiving old patterns if needed)
+
+**Manual alternative:** Edit `knowledge/domains/[domain]/patterns.md` directly.
+
+---
+
+## Tool: `am-failure`
+
+**Purpose:** Log a failure pattern to a domain's failure library.
+
+**When:** During Path B of compaction, after analyzing what went wrong.
+
+**Usage:**
+```bash
+./am-failure [domain] [slug] [trigger-condition] [summary]
+```
+
+**Parameters:**
+- `domain` — affected domain
+- `slug` — short slug for this failure
+- `trigger-condition` — what conditions trigger this failure
+- `summary` — one-line summary of the failure
+
+**Example:**
+```bash
+./am-failure "auth" "jwt-clock-skew-too-small" \
+  "JWT expiry validation with clock skew < 30 seconds in high-latency networks" \
+  "False token rejections due to insufficient clock skew buffer"
+```
+
+**What it does:**
+1. Appends entry to `knowledge/domains/[domain]/failures/_index.md`
+2. Creates `knowledge/domains/[domain]/failures/[slug].md` with detail template
+3. Opens the detail file for you to add conditions and prevention steps
+
+**Index format:**
+```
+YYYY-MM-DD | slug | trigger condition | one-line summary
+```
+
+**Manual alternative:** Edit the failure index and create detail files manually.
+
+---
+
+## Tool: `am-health`
+
+**Purpose:** Quick memory health check (size audit only).
+
+**When:** Quick sanity check between full maintenance runs, or before a big task.
+
+**Usage:**
+```bash
+./am-health
+```
+
+**What it does:**
+1. Scans all core memory files against size limits (from `protocols/memory-ops.md`)
+2. Reports any files over limits with line counts
+3. Lists files last modified more than 30 days ago
+4. Shows episode/reflection/insight counts
+
+**Output example:**
+```
+Memory Health Check — 2026-03-22
+
+Size Audit:
+  BOOT.md: 120 / 150 lines — OK
+  protocols/workflow.md: 82 / 200 lines — OK
+  knowledge/insights.md: 5 entries / 100 max — OK
+
+Stale Files (30+ days):
+  None
+
+Summary:
+  Episodes: 12 total
+  Reflections: 2 total
+  Insights: 5 total
+```
+
+**Manual alternative:** Run `wc -l` on files and check timestamps manually.
+
+---
+
+## Tool: `am-maintain`
+
+**Purpose:** Run the full maintenance protocol and generate a report.
+
+**When:** After the human requests a health check, or every 2 weeks.
+
+**Usage:**
+```bash
+./am-maintain
+```
+
+**What it does:**
+1. Runs all steps from `protocols/maintenance.md`:
+   - Size check (all files vs limits)
+   - Stale memory check (zero-vote insights, unverified entries, unused patterns)
+   - Contradiction check (failed tasks vs loaded patterns, negative votes, conflicts)
+   - Growth review (episodes, knowledge, insights movement)
+2. Generates report (see template in maintenance.md)
+3. Saves report to `history/maintenance-reports/YYYY-MM-DD.md`
+4. Outputs recommendations (but does NOT execute changes)
+
+**Your job:** Review the report, decide which recommendations to act on, tell the agent which ones to execute.
+
+**Manual alternative:** Follow `protocols/maintenance.md` manually and create the report yourself.
+
+---
+
+## Important Notes
+
+1. **These tools are optional.** Every operation can be done manually by editing files. Use them if they speed you up.
+
+2. **Tools follow protocols.** They automate the mechanics of the protocols, not the thinking. You still need to understand what you're capturing and why.
+
+3. **They create well-formed files.** All tools create markdown with consistent formatting, making it easier for agents to parse and maintain.
+
+4. **No destructive operations.** Tools never delete files from `history/` or `knowledge/` — they append only. Maintenance (which proposes deletions) is manual review + human decision.
+
+5. **Look at the generated files.** After running a tool, open the created file and verify it's what you expected. These are learning records — get them right.
+
+---
+
+## Troubleshooting
+
+**Tool not found:** Make sure `.agent-mind/.am-tools/` is in your PATH, or call with `./am-tools/[tool-name]`.
+
+**File already exists:** Tools append to existing files rather than overwriting. This prevents data loss.
+
+**Large files:** If a tool warns that a file is over limit, follow the maintenance protocol to archive old entries.
+
+**Custom tools:** You can create your own tools in `.agent-mind/.am-tools/`. Keep them as bash scripts following the same conventions.