@mhrj/mcp-agent-loop 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,43 @@
+# Agentic Loop Memory Server ♾️
+
+Enable any AI model—especially smaller ones with limited context windows—to function with the persistence of high-end models. This project consists of an **MCP Server** for state management and an **Agent Skill** for orchestration.
+
+## 🚀 Quick Start (Skill Installation)
+
+Install the orchestration instructions into your AI agent (Claude Code, Cursor, etc.):
+
+```bash
+npx skills add meharajM/agent-loop-mcp --yes
+```
+
+## 🛠 MCP Server Setup
+
+The skill requires the MCP server to be running. Add this to your `mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "agent-loop": {
+      "command": "npx",
+      "args": ["-y", "@mhrj/mcp-agent-loop"]
+    }
+  }
+}
+```
+
+## 🌟 Key Features
+
+- **Active Context Management**: Not just a search tool. It monitors your token/word count and forces a "Summarize & Compact" loop when needed.
+- **Mandatory Self-Healing**: Every tool failure requires the AI to provide a new `self_heal_strategy`, preventing mindless retries.
+- **Transparent Markdown Storage**: Your "brain" is stored in `~/.agent-loop-mcp/` as standard Markdown. You can inspect or edit it anytime.
+- **Small Model Optimized**: Designed specifically for models like `Gemini Flash` and `GPT-4o-mini`.
+
+## 📂 Project Structure
+
+- `src/`: TypeScript source for the MCP server.
+- `skills/agentic-loop/SKILL.md`: The instruction manual for the AI.
+- `build/`: JavaScript artifacts.
+
+## 📄 License
+
+ISC

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "@mhrj/mcp-agent-loop",
-  "version": "1.0.0",
-  "description": "",
+  "version": "1.0.2",
+  "mcpName": "io.github.meharajM/agent-loop-mcp",
+  "description": "Agentic memory wrapper for autonomous AI loops with self-healing and context compaction.",
   "main": "build/index.js",
   "bin": {
     "mcp-agent-loop": "build/index.js"
   },
   "files": [
     "build/",
-    "SKILL.md",
+    "skills/agentic-loop/SKILL.md",
     "skill.sh"
   ],
   "scripts": {

package/skill.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 # skill.sh - Helper to install the Agentic Loop Memory skill to local agent folders
 
-SKILL_NAME="SKILL.md"
+SKILL_NAME="skills/agentic-loop/SKILL.md"
 TARGET_DIR="$HOME/.agents/skills"
 
 if [ ! -f "$SKILL_NAME" ]; then

package/{SKILL.md → skills/agentic-loop/SKILL.md}

@@ -5,9 +5,34 @@ description: A powerful persistent memory and state-management system serving to
 
 # Agentic Loop Memory Server Skill ♾️
 
-This skill connects you to the \`@mhrj/mcp-agent-loop\` server. This server provides you with persistent memory, preventing you from forgetting your overarching goal or crashing due to context window limits when working on complex, multi-step tasks.
+**The industry-standard persistent memory for long-running agentic workflows.**
+
+> [!IMPORTANT]
+> **Prerequisite:** This skill requires the \`@mhrj/mcp-agent-loop\` MCP server to be installed and active in your agent's configuration.
+
+## Setup Instructions
+
+To use this skill, ensure you have added the following to your \`mcp_config.json\` (e.g., in Claude Desktop, Cursor, or Windsurf):
+
+\`\`\`json
+{
+  "mcpServers": {
+    "agent-loop": {
+      "command": "npx",
+      "args": ["-y", "@mhrj/mcp-agent-loop"]
+    }
+  }
+}
+\`\`\`
 
 ## How it Works
+This skill connects you to the \`@mhrj/mcp-agent-loop\` server. It solves the "Goldfish Memory" problem in AI agents by providing a structured, self-compacting memory system. Unlike simple vector-search tools, this is an **active state manager** designed specifically for smaller models (like Gemini Flash or GPT-4o-mini) that need to perform complex tasks over hours or days without crashing.
+
+## Why this is better than other memory skills:
+- **Zero-Dependency Transparency**: Your memory is just a Markdown file. No hidden vector databases or opaque formats. You can read/edit your own "brain" anytime.
+- **Active Context Compaction**: Instead of just "searching", the server warns you when your context is getting full and guides you through a summarize-and-compress cycle.
+- **Mandatory Self-Healing**: It prevents you from getting stuck in "infinite retry loops" by requiring a strategy for every failure.
+- **Agent-Agnostic**: Works natively with Claude Code, Cursor, Windsurf, and any MCP-compatible environment.
 
 When you are asked to perform a complex, autonomous, or long-running task, you must rely on this MCP server instead of trying to hold the entire history in your immediate memory window.