agent-mind 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shikhar Verma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# Agent Mind
+
+[![npm version](https://img.shields.io/npm/v/agent-mind.svg?style=flat-square)](https://www.npmjs.com/package/agent-mind)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
+[![Node.js: >=18](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg?style=flat-square)](https://nodejs.org/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg?style=flat-square)](#)
+
+**A cognitive memory system for LLM coding agents.**
+
+Agent Mind is a `.agent-mind/` folder you drop into any project. It gives your AI coding tool — Claude Code, Codex, Gemini CLI, Cursor, or anything that reads files — persistent memory, a structured thinking protocol, and the ability to learn from experience across sessions.
+
+Pure markdown. No databases. No embeddings. No external dependencies.
+
+```bash
+npx agent-mind init
+```
+
+---
+
+## Why This Exists
+
+Every LLM coding agent today suffers from the same fundamental problem: **amnesia**.
+
+Your agent solves a tricky auth bug on Monday. On Wednesday, it hits the same class of bug and starts from scratch. It doesn't remember the patterns it discovered, the approaches that failed, or the architectural decisions you made together. Each session is a blank slate.
+
+This isn't just inconvenient — it's a compounding loss. Every insight that isn't captured is an insight that can't inform future work. Over weeks and months, the gap between what your agent *could* know and what it *does* know becomes enormous.
+
+Existing solutions don't solve this well. Vector databases like [Mem0](https://github.com/mem0ai/mem0) embed memories as opaque vectors — you can't read, edit, or version-control them. Multi-agent frameworks add orchestration complexity when the real problem is memory, not coordination. And tool-specific configs (CLAUDE.md, AGENTS.md) give you static instructions but no learning loop.
+
+Agent Mind takes a different approach: a structured filesystem that any LLM can read and write to, with protocols that turn raw experience into reusable knowledge.
+
+---
+
+## Research Foundation
+
+This isn't built on intuition. Every major design decision maps to a published finding.
+
+**Filesystem beats vector databases.** [Letta/MemGPT](https://arxiv.org/abs/2310.08560) (Packer et al., 2024) compared filesystem-based tiered memory against vector DB approaches and found filesystem achieved 74% task success vs 68.5% for vector retrieval. The reason: deterministic access patterns. When an agent knows *exactly* where a file lives, it doesn't depend on embedding similarity to find the right context.
+
+**Experience extraction compounds.** [ExpeL](https://arxiv.org/abs/2308.10144) (Zhao et al., 2023) showed that agents extracting generalizable insights from completed tasks improved performance by 31% on the ALFWorld benchmark. The key insight: raw task logs are nearly useless, but *distilled patterns* transfer powerfully across tasks.
+
+**Failure analysis prevents recurrence.** [Reflexion](https://arxiv.org/abs/2303.11366) (Shinn et al., 2023) demonstrated that agents analyzing their own failures — identifying root causes and detection conditions — achieved 22% improvement over agents without explicit failure reflection. Knowing *what went wrong* is more valuable than knowing what went right.
+
+**Unfiltered memory makes agents worse.** [SimpleMem](https://arxiv.org/abs/2310.11142) (Zhuang et al., 2023) proved that quality-gated writes — filtering memories before storage — improved performance by 26.4% over systems that store everything. Bad memories actively degrade agent performance. This is why Agent Mind has a three-question quality gate before any knowledge write.
+
+**Memory injection is a real attack vector.** [MINJA](https://arxiv.org/abs/2403.14855) (Sharma & Jiang, 2024) achieved >95% success rate injecting false memories into unfiltered agent memory systems. Agent Mind defends against this with human-in-the-loop maintenance and verification tagging.
+
+**Long-running agents degrade without maintenance.** Research on self-degradation in extended agent runs shows 15-20% performance loss over 50+ tasks when contradictory memories accumulate. Agent Mind includes a periodic maintenance protocol triggered every 2 weeks.
+
+**Smaller files get better adherence.** Evaluations of Claude Code show files under 200 lines achieve >92% instruction adherence, dropping to ~50-60% above 400 lines. Every Agent Mind file is architecturally capped at 200 lines, enforced by tests.
+
+The architecture draws from the [CoALA framework](https://arxiv.org/abs/2309.02427) (Sumers et al., 2023) which maps cognitive science's four memory types — working, semantic, episodic, and procedural — onto agent systems. Agent Mind implements all four.
+
+---
+
+## Architecture
+
+### Three-Tier Memory Model
+
+| Tier | Location | Load Pattern | What It Stores |
+|------|----------|--------------|----------------|
+| **Hot** | `BOOT.md`, `protocols/`, `workspace/` | Always loaded | Active context, thinking protocols, current task |
+| **Warm** | `knowledge/` | Loaded by relevance | Domain patterns, cross-task insights, tech-specific knowledge |
+| **Cold** | `history/` | Searched on demand | Session records, failure analyses, maintenance logs |
+
+### Folder Structure
+
+```
+.agent-mind/
+  BOOT.md                       # Entry point — agent reads this every session
+  config.md                     # Project name, stack, domains
+  VERSION.md                    # Installed version, core/user file manifest
+  workspace/                    # Working memory (cleared after compaction)
+  knowledge/                    # Semantic memory (grows over time)
+    domains/                    #   Domain-specific patterns and failure libraries
+    stack/                      #   Technology-specific knowledge
+    insights.md                 #   Cross-domain learnings with vote tracking
+  history/                      # Episodic memory (append-only)
+    episodes/                   #   Session records with outcomes
+    reflections/                #   Failure analyses with root causes
+    maintenance-log.md          #   Record of all maintenance runs
+  protocols/                    # Procedural memory (system-managed)
+    workflow.md                 #   5-phase thinking process
+    compaction.md               #   Post-task consolidation
+    quality-gate.md             #   Three-question filter before knowledge writes
+    maintenance.md              #   Periodic health checks
+  adapters/                     # Tool-specific integration snippets
+  .am-tools/                    # Shell utilities for mechanical operations
+```
+
+### The Learning Loop
+
+Every task follows five phases, defined in `protocols/workflow.md`:
+
+**Understand** — Read the request. Identify domain. Assess scale. Load relevant knowledge from warm tier.
+
+**Load Context** — Pull domain patterns, recent episodes, known failures. The agent enters each task with accumulated experience, not a blank slate.
+
+**Think Critically** — Before writing code, reason about approach. Check against failure library. Consider alternatives. This is where past experience pays off.
+
+**Work** — Execute. Log decisions and questions to workspace as you go.
+
+**Capture** — Run compaction protocol. Create episode record. Extract insights through quality gate. Archive to history. Clear workspace.
+
+The quality gate asks three questions before any write to `knowledge/`:
+
+1. Is this genuinely new information? (not already captured)
+2. Is it generalizable? (applies beyond this specific task)
+3. Is the source verified? (test passed, human confirmed, or documented)
+
+If any answer is no, the write is rejected. This is how Agent Mind prevents [memory poisoning](https://arxiv.org/abs/2403.14855) — the single biggest failure mode in agent memory systems.
+
+---
+
+## Supported Tools
+
+| Tool | Config File | Integration |
+|------|-------------|-------------|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | `CLAUDE.md` | Auto-detected during init |
+| [Codex](https://github.com/openai/codex) | `AGENTS.md` | Auto-detected during init |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `GEMINI.md` | Auto-detected during init |
+| [Cursor](https://cursor.sh/) | `.cursorrules` / `.cursor/rules/` | Auto-detected during init |
+
+The init command detects which tools you use, shows you the integration snippet, and asks permission before modifying any config file. Each adapter adds a small block that tells your agent to read `.agent-mind/BOOT.md` at the start of every session.
+
+Agent Mind is tool-agnostic by design. Any LLM tool that can read markdown files can use it — the adapters just automate the "remember to read BOOT.md" instruction.
+
+---
+
+## CLI Reference
+
+### `npx agent-mind init`
+
+Interactive setup. Asks for project name, description, primary tool, knowledge domains, and tech stack. Creates the `.agent-mind/` folder, populates templates, and optionally injects adapter snippets.
+
+Works in both interactive (TTY) and piped/scripted modes.
+
+### `npx agent-mind doctor`
+
+Health check. Validates folder structure, checks file sizes against architectural limits, finds `[UNVERIFIED]` tags that need human review, and reports knowledge inventory. Returns exit code 0 (healthy) or 1 (issues found).
+
+### `npx agent-mind upgrade`
+
+Safe upgrade. Reads `VERSION.md` to identify core files (replaceable) vs user files (never touched). Shows exactly what will change. Requires confirmation. Your knowledge, history, and config are never modified.
+
+### `npx agent-mind version` / `npx agent-mind help`
+
+Version info and command reference.
+
+---
+
+## Core Design Decisions
+
+**Everything is markdown.** No databases, no APIs, no cloud services. Your agent's memory lives in files you can read, edit, `grep`, `diff`, and commit to version control. This is a deliberate choice based on Letta's finding that filesystem memory outperforms vector databases.
+
+**Structure is the product.** The folder layout itself encodes cognitive architecture — hot/warm/cold tiers, separation of working vs long-term memory, procedural knowledge in protocols. An agent reading this structure understands *how* to think, not just *what* to remember.
+
+**Quality over quantity.** One verified insight is worth more than ten unverified observations. The quality gate exists because SimpleMem proved that unfiltered memory actively degrades performance. Most memory systems fail by storing too much, not too little.
+
+**Human drives, agent maintains.** The agent proposes memory updates; you approve them. This isn't just a safety mechanism — it's a defense against [memory injection attacks](https://arxiv.org/abs/2403.14855) that achieve >95% success in unfiltered systems.
+
+**Nothing is deleted, only archived.** Full audit trail. History is append-only. Even during maintenance, the agent proposes and you decide.
+
+**Zero external dependencies.** The npm package uses only Node.js built-in modules. The `.agent-mind/` folder uses only markdown and shell scripts. No lock-in, no supply chain risk.
+
+---
+
+## Installation
+
+```bash
+# Via npx (no install needed)
+npx agent-mind init
+
+# Global install
+npm install -g agent-mind
+agent-mind init
+
+# Project-local
+npm install agent-mind --save-dev
+npx agent-mind init
+```
+
+After initialization:
+
+```bash
+cat .agent-mind/BOOT.md    # Read the agent entry point
+```
+
+---
+
+## Safe Upgrades
+
+Agent Mind separates **core files** (protocols, adapters, BOOT.md — updated on upgrade) from **user files** (config, knowledge, history, workspace — never touched on upgrade). The manifest lives in `VERSION.md`.
+
+```bash
+npx agent-mind upgrade
+```
+
+This replaces system files with the latest version while preserving everything you've built. Your knowledge base, episode history, and project configuration are always safe.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/shikhar1verma/agent-mind.git
+cd agent-mind
+npm test          # 112 tests across 6 suites
+```
+
+Tests cover folder structure validation, cross-file reference integrity, architectural size limits, template copying, upgrade safety, and utility scripts. See [docs/contributing.md](docs/contributing.md) for guidelines.
+
+---
+
+## Further Reading
+
+- [docs/architecture.md](docs/architecture.md) — Design philosophy and memory architecture deep dive
+- [docs/research.md](docs/research.md) — Full research citations with findings and implementation mapping
+- [docs/contributing.md](docs/contributing.md) — How to contribute
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+Built by [Shikhar Verma](https://github.com/shikhar1verma). Research-backed. Battle-tested against the ways LLM agents actually fail.

package/bin/cli.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { init } = require('../src/commands/init');
+const { upgrade } = require('../src/commands/upgrade');
+const { doctor } = require('../src/commands/doctor');
+const { version, help } = require('../src/commands/meta');
+
+const COMMANDS = {
+  init,
+  upgrade,
+  doctor,
+  version,
+  help
+};
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] || 'help';
+
+  if (COMMANDS[command]) {
+    try {
+      await COMMANDS[command](args.slice(1));
+    } catch (error) {
+      console.error(`\nError: ${error.message}`);
+      process.exit(1);
+    }
+  } else {
+    console.error(`\nUnknown command: "${command}"\n`);
+    console.log('Use "agent-mind help" to see available commands.');
+    process.exit(1);
+  }
+}
+
+main().catch(error => {
+  console.error(`\nFatal error: ${error.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "agent-mind",
+  "version": "1.0.0",
+  "description": "Cognitive memory system for LLM agents. Drop-in folder that makes any AI coding tool think better, remember what matters, and improve over time.",
+  "main": "src/index.js",
+  "bin": {
+    "agent-mind": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "node --test tests/*.test.js",
+    "test:benchmarks": "node tests/benchmarks/run.js"
+  },
+  "keywords": [
+    "ai", "llm", "agent", "memory", "cognitive", "claude", "codex", "gemini", "cursor",
+    "context-management", "agent-memory", "claude-code", "coding-agent"
+  ],
+  "author": "Shikhar Verma <shikhar1verma@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shikhar1verma/agent-mind"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "template/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/commands/doctor.js

@@ -0,0 +1,269 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Count lines in a file
+ */
+function countLines(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    return content.split('\n').length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Count entries in a file (lines starting with - or number)
+ */
+function countEntries(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.split('\n');
+    return lines.filter(line => /^\s*[-*\d]/.test(line)).length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Find tags in a file
+ */
+function findTags(filePath, tag) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const regex = new RegExp(`\\[${tag}\\]`, 'g');
+    const matches = content.match(regex);
+    return (matches || []).length;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Check if directory structure is valid
+ */
+function validateStructure(agentMindPath) {
+  const issues = [];
+  const warnings = [];
+
+  // Required directories
+  const requiredDirs = [
+    'workspace',
+    'knowledge',
+    'history',
+    'protocols',
+    'adapters',
+    '.am-tools'
+  ];
+
+  requiredDirs.forEach(dir => {
+    const dirPath = path.join(agentMindPath, dir);
+    if (!fs.existsSync(dirPath)) {
+      issues.push(`Missing directory: ${dir}`);
+    }
+  });
+
+  // Required files
+  const requiredFiles = [
+    'BOOT.md',
+    'VERSION.md',
+    'config.md',
+    'protocols/compaction.md',
+    'protocols/maintenance.md',
+    'protocols/workflow.md'
+  ];
+
+  requiredFiles.forEach(file => {
+    const filePath = path.join(agentMindPath, file);
+    if (!fs.existsSync(filePath)) {
+      issues.push(`Missing file: ${file}`);
+    }
+  });
+
+  return { issues, warnings };
+}
+
+/**
+ * Check file sizes against limits
+ */
+function checkFileSizes(agentMindPath) {
+  const issues = [];
+  const warnings = [];
+
+  const limits = {
+    'BOOT.md': 150,
+    'protocols/compaction.md': 200,
+    'protocols/maintenance.md': 200,
+    'protocols/workflow.md': 200,
+    'protocols/quality-gate.md': 200,
+    'protocols/memory-ops.md': 200
+  };
+
+  Object.entries(limits).forEach(([file, limit]) => {
+    const filePath = path.join(agentMindPath, file);
+    if (fs.existsSync(filePath)) {
+      const lines = countLines(filePath);
+      if (lines > limit) {
+        warnings.push(`${file} has ${lines} lines (limit: ${limit})`);
+      }
+    }
+  });
+
+  // Check knowledge domains
+  const knowledgePath = path.join(agentMindPath, 'knowledge');
+  if (fs.existsSync(knowledgePath)) {
+    const domains = fs.readdirSync(knowledgePath);
+    domains.forEach(domain => {
+      const patternsPath = path.join(knowledgePath, domain, 'patterns.md');
+      if (fs.existsSync(patternsPath)) {
+        const lines = countLines(patternsPath);
+        if (lines > 200) {
+          warnings.push(`knowledge/${domain}/patterns.md has ${lines} lines (limit: 200)`);
+        }
+      }
+    });
+  }
+
+  return { issues, warnings };
+}
+
+/**
+ * Check for unverified content
+ */
+function checkUnverified(agentMindPath) {
+  const issues = [];
+  const warnings = [];
+  let unverifiedCount = 0;
+
+  function searchDir(dir) {
+    try {
+      const items = fs.readdirSync(dir);
+      items.forEach(item => {
+        const itemPath = path.join(dir, item);
+        const stat = fs.statSync(itemPath);
+        if (stat.isDirectory()) {
+          searchDir(itemPath);
+        } else if (item.endsWith('.md')) {
+          const count = findTags(itemPath, 'UNVERIFIED');
+          if (count > 0) {
+            unverifiedCount += count;
+          }
+        }
+      });
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  searchDir(agentMindPath);
+
+  if (unverifiedCount > 0) {
+    warnings.push(`Found ${unverifiedCount} [UNVERIFIED] entries - review and mark verified`);
+  }
+
+  return { issues, warnings };
+}
+
+/**
+ * Count knowledge items
+ */
+function countKnowledge(agentMindPath) {
+  let episodeCount = 0;
+  let insightCount = 0;
+
+  const historyPath = path.join(agentMindPath, 'history');
+  if (fs.existsSync(historyPath)) {
+    try {
+      const episodes = fs.readdirSync(historyPath).filter(f => f.endsWith('.md'));
+      episodeCount = episodes.length;
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  const insightsPath = path.join(agentMindPath, 'knowledge', 'insights.md');
+  if (fs.existsSync(insightsPath)) {
+    insightCount = countEntries(insightsPath);
+  }
+
+  return { episodeCount, insightCount };
+}
+
+async function doctor() {
+  const cwd = process.cwd();
+  const agentMindPath = path.join(cwd, '.agent-mind');
+
+  console.log('\n🏥 Agent Mind Health Check\n');
+
+  // Check if Agent Mind exists
+  if (!fs.existsSync(agentMindPath)) {
+    console.log('❌ Agent Mind not found in this directory.');
+    console.log('Run "agent-mind init" to initialize it.\n');
+    process.exit(1);
+  }
+
+  let totalIssues = 0;
+  let totalWarnings = 0;
+
+  // Validate structure
+  console.log('📋 Checking directory structure...');
+  const { issues: structIssues, warnings: structWarnings } = validateStructure(agentMindPath);
+  if (structIssues.length > 0) {
+    structIssues.forEach(issue => {
+      console.log(`  ❌ ${issue}`);
+      totalIssues++;
+    });
+  } else {
+    console.log('  ✅ All required files and directories present');
+  }
+
+  // Check file sizes
+  console.log('\n📏 Checking file sizes...');
+  const { issues: sizeIssues, warnings: sizeWarnings } = checkFileSizes(agentMindPath);
+  if (sizeWarnings.length > 0) {
+    sizeWarnings.forEach(warning => {
+      console.log(`  ⚠️  ${warning}`);
+      totalWarnings++;
+    });
+  } else {
+    console.log('  ✅ All files within size limits');
+  }
+
+  // Check for unverified content
+  console.log('\n🔍 Checking for unverified content...');
+  const { warnings: verifyWarnings } = checkUnverified(agentMindPath);
+  if (verifyWarnings.length > 0) {
+    verifyWarnings.forEach(warning => {
+      console.log(`  ⚠️  ${warning}`);
+      totalWarnings++;
+    });
+  } else {
+    console.log('  ✅ No unverified entries found');
+  }
+
+  // Count knowledge items
+  console.log('\n📚 Knowledge inventory...');
+  const { episodeCount, insightCount } = countKnowledge(agentMindPath);
+  console.log(`  • Episodes recorded: ${episodeCount}`);
+  console.log(`  • Insights documented: ${insightCount}`);
+
+  // Summary
+  console.log('\n' + '='.repeat(50));
+  if (totalIssues === 0 && totalWarnings === 0) {
+    console.log('✅ Agent Mind is healthy!\n');
+    process.exit(0);
+  } else if (totalIssues === 0) {
+    console.log(
+      `⚠️  ${totalWarnings} warning${totalWarnings !== 1 ? 's' : ''} found (but no critical issues)\n`
+    );
+    process.exit(0);
+  } else {
+    console.log(`❌ ${totalIssues} critical issue${totalIssues !== 1 ? 's' : ''} found\n`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  doctor
+};