@mndrk/memx 0.3.1 → 0.3.2

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "memx",
+  "description": "Persistent memory for AI agents - git-backed, branch-per-task state management",
+  "version": "0.3.1",
+  "author": "mndrk",
+  "repository": "https://github.com/ramarlina/memx",
+  "mcp": "./.mcp.json"
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "mem": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp.js"]
+    }
+  }
+}

package/README.md

@@ -152,6 +152,21 @@ mem cron export
 
 ## For AI Agents
 
+### Claude Code Plugin
+
+Install as a Claude Code plugin for automatic skill loading and slash commands:
+
+```bash
+claude plugin install github:ramarlina/memx
+```
+
+This adds:
+- **Skill**: Claude learns how to use mem automatically
+- **MCP Server**: Direct tool access
+- **Commands**: `/mem:status`, `/mem:checkpoint`, `/mem:context`
+
+### Manual Setup
+
 Install the skill so LLMs know how to use mem:
 
 ```bash

package/commands/checkpoint.md

@@ -0,0 +1,19 @@
+# /mem:checkpoint - Save Progress
+
+Save a checkpoint with a message describing current progress.
+
+## Usage
+```
+/mem:checkpoint <message>
+```
+
+## Arguments
+- `$ARGUMENTS` - The checkpoint message describing what was accomplished
+
+## Implementation
+
+```bash
+mem checkpoint "$ARGUMENTS"
+```
+
+Confirm the checkpoint was saved.

package/commands/context.md

@@ -0,0 +1,16 @@
+# /mem:context - Load Full Context
+
+Load the complete task context including goal, state, and learnings.
+
+## Usage
+```
+/mem:context
+```
+
+## Implementation
+
+```bash
+mem context
+```
+
+Display the full context to understand the current task state.

package/commands/status.md

@@ -0,0 +1,24 @@
+# /mem:status - Show Memory Status
+
+Show the current task status, progress, and next step.
+
+## Usage
+```
+/mem:status
+```
+
+## Implementation
+
+Run `mem status` to get the current state:
+
+```bash
+mem status
+```
+
+Then run `mem progress` to see completion percentage:
+
+```bash
+mem progress
+```
+
+Report both outputs to the user in a clear summary.

package/index.js

@@ -191,11 +191,19 @@ function findMemDir(startDir = process.cwd()) {
   // Then check central ~/.mem with index
   if (fs.existsSync(CENTRAL_MEM) && fs.existsSync(path.join(CENTRAL_MEM, '.git'))) {
     const index = loadIndex();
-    const taskBranch = index[startDir];
-    if (taskBranch) {
-      return { memDir: CENTRAL_MEM, isLocal: false, taskBranch };
+    // Exact match first
+    if (index[startDir]) {
+      return { memDir: CENTRAL_MEM, isLocal: false, taskBranch: index[startDir] };
     }
-    // Central exists but no mapping for this dir
+    // Check parent directories (for monorepo/subdirectory usage)
+    let checkDir = startDir;
+    while (checkDir !== path.dirname(checkDir)) {
+      checkDir = path.dirname(checkDir);
+      if (index[checkDir]) {
+        return { memDir: CENTRAL_MEM, isLocal: false, taskBranch: index[checkDir] };
+      }
+    }
+    // Central exists but no mapping for this dir or parents
     return { memDir: CENTRAL_MEM, isLocal: false, taskBranch: null, unmapped: true };
   }
   
@@ -1646,8 +1654,13 @@ function cmdCronExport(memDir) {
     return;
   }
 
+  // Detect PATH from current environment for cron (which has minimal PATH)
+  const nodeBin = path.dirname(process.execPath);
+  const pathDirs = [nodeBin, '/usr/local/bin', '/usr/bin', '/bin'];
+  const pathPrefix = `PATH=${pathDirs.join(':')}`;
+
   const command = frontmatter.wake_command || `cd ${memDir} && mem context`;
-  const entry = `${cron} ${command}`;
+  const entry = `${cron} ${pathPrefix} && ${command}`;
 
   // Just output the cron line (can be piped/appended)
   console.log(entry);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mndrk/memx",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Persistent memory for AI agents - git-backed, branch-per-task, CLI interface",
   "main": "index.js",
   "bin": {

package/skills/mem/SKILL.md

@@ -0,0 +1,88 @@
+# mem - Persistent Agent Memory
+
+Use `mem` to maintain state, track progress, and accumulate learnings across sessions. Git-backed, branch-per-task architecture.
+
+## When to Use
+
+- **Long-running tasks** that span multiple sessions
+- **Tracking progress** with explicit checkpoints
+- **Accumulating learnings** that persist beyond context window
+- **Coordinating work** across wake/sleep cycles
+
+## Architecture
+
+```
+~/.mem/
+  goal.md       # Objective + success criteria
+  state.md      # Progress, next step, blockers, wake schedule
+  memory.md     # Task-specific learnings
+  playbook.md   # Global learnings (shared across tasks)
+```
+
+Each task is a git branch. Learnings stay isolated until promoted to playbook.
+
+## Core Commands
+
+### On Wake (Start of Session)
+```bash
+mem context    # Load full state: goal + progress + learnings
+mem status     # Quick summary
+mem next       # See what to work on
+```
+
+### During Work
+```bash
+mem checkpoint "<msg>"    # Save progress point
+mem learn "<insight>"     # Record learning (-g for global)
+mem next "<step>"         # Set next step
+mem stuck "<reason>"      # Mark blocker (use "clear" to remove)
+```
+
+### Task Lifecycle
+```bash
+mem init <name> "<goal>"  # Start new task (creates branch)
+mem criteria add "..."    # Add success criterion
+mem criteria <n>          # Mark criterion #n complete
+mem progress              # Show % complete
+mem done                  # Complete task, merge learnings
+```
+
+### Wake System
+```bash
+mem wake "every 15m"              # Set wake schedule
+mem wake "every 15m" --run "cmd"  # Set schedule + command
+mem cron export                   # Output crontab entry
+mem wake clear                    # Clear schedule
+```
+
+## Typical Session Loop
+
+1. `mem context` — Load state on wake
+2. `mem next` — See what to work on
+3. Do work
+4. `mem checkpoint "..."` — Save progress
+5. `mem learn "..."` — Capture insights
+6. `mem next "..."` — Set next step for future self
+
+## Output Markers (for automated parsing)
+
+When working in an agx-managed loop, use these markers in your output:
+
+```
+[checkpoint: message]   # Parsed → mem checkpoint
+[learn: insight]        # Parsed → mem learn
+[next: step]            # Parsed → mem next
+[criteria: N]           # Parsed → mem criteria N
+[done]                  # Task complete, clear wake
+[blocked: reason]       # Stop, notify human
+[pause]                 # Stop, resume on next wake
+```
+
+## MCP Integration
+
+mem provides an MCP server for direct tool access:
+
+```bash
+mem mcp        # Start MCP server (stdio)
+mem mcp config # Show Claude Desktop config
+```