@prmichaelsen/remember-mcp 3.15.4 → 3.15.5

package/agent/commands/acp.project-create.md

@@ -9,6 +9,7 @@
 **Created**: 2026-02-22
 **Last Updated**: 2026-02-22
 **Status**: Active
+**Scripts**: None
 
 ---
 
@@ -599,6 +600,7 @@ Location: ~/dev/experiments/experiment/
 - [`@acp.init`](acp.init.md) - Initialize context in created project
 - [`@acp.plan`](acp.plan.md) - Plan milestones and tasks
 - [`@git.init`](git.init.md) - Initialize git repository
+- [`@acp.projects-restore`](acp.projects-restore.md) - Restore projects from git origins on new machines
 
 ---
 
@@ -659,6 +661,7 @@ Location: ~/dev/experiments/experiment/
 - Projects can be created anywhere, not just ~/.acp/projects/
 - Full ACP installation means all commands and templates are available
 - progress.yaml starts empty (plan milestones with @acp.plan)
+- After adding a git remote, run `@acp.projects-sync` to record `git_origin` in the registry for `@acp.projects-restore` support
 
 ---
 

package/agent/commands/acp.project-info.md

@@ -74,6 +74,7 @@ Read all project fields from registry.
 
 **Actions**:
 - Extract required fields: path, type, description, status, timestamps
+- Extract git fields: git_origin, git_branch
 - Extract optional fields: tags, related_projects, dependencies
 - Check if project is current project (marked with ⭐)
 
@@ -87,6 +88,7 @@ Format and display comprehensive project details.
 - Display project name with current indicator
 - Show type, status, path, description
 - Display timestamps (created, modified, accessed)
+- Display git info (origin, branch) if available
 - Show tags (if present)
 - Show related projects (if present)
 - Show dependencies by package manager (npm, pip, cargo, go)
@@ -229,6 +231,7 @@ Dependencies:
 - [`@acp.project-set`](acp.project-set.md) - Switch to a project
 - [`@acp.project-update`](acp.project-update.md) - Update project metadata
 - [`@acp.projects-sync`](acp.projects-sync.md) - Sync registry with filesystem
+- [`@acp.projects-restore`](acp.projects-restore.md) - Restore projects from git origins
 
 ---
 

package/agent/commands/acp.project-list.md

@@ -8,6 +8,7 @@
 **Created**: 2026-02-23
 **Last Updated**: 2026-02-23
 **Status**: Experimental
+**Scripts**: acp.project-list.sh, acp.common.sh, acp.yaml-parser.sh
 
 ---
 
@@ -19,7 +20,7 @@
 
 ## What This Command Does
 
-Lists all projects registered in `~/.acp/projects.yaml` with their metadata. Shows project type, status, description, and last accessed time. Highlights the current active project with a ⭐ marker.
+Lists all projects registered in `~/.acp/projects.yaml` with their metadata. Shows project type, status, description, git origin (when available), and last accessed time. Highlights the current active project with a ⭐ marker.
 
 **Key Distinction**: This command lists projects IN the registry. Use `@acp.projects-sync` to discover projects NOT YET registered.
 
@@ -173,6 +174,7 @@ Showing 2 of 3 projects
 - [`@acp.project-set`](acp.project-set.md) - Switch to project
 - [`@acp.projects-sync`](acp.projects-sync.md) - Discover unregistered projects
 - [`@acp.project-info`](acp.project-info.md) - Show project details
+- [`@acp.projects-restore`](acp.projects-restore.md) - Restore projects from git origins
 
 ---
 

package/agent/commands/acp.project-set.md

@@ -8,6 +8,7 @@
 **Created**: 2026-02-24
 **Last Updated**: 2026-02-24
 **Status**: Experimental
+**Scripts**: acp.project-set.sh, acp.common.sh, acp.yaml-parser.sh
 
 ---
 

package/agent/commands/acp.project-update.md

@@ -42,7 +42,7 @@ Extract project name and update options.
 
 **Actions**:
 - Parse project name (required)
-- Parse update flags (--status, --description, --type, etc.)
+- Parse update flags (--status, --description, --type, --git-origin, --git-branch, etc.)
 - Validate at least one update option provided
 
 **Expected Outcome**: Arguments parsed successfully
@@ -77,6 +77,8 @@ Update registry with new values.
 - Update status (if provided)
 - Update description (if provided)
 - Update type (if provided)
+- Update git_origin (if provided)
+- Update git_branch (if provided)
 - Add tags (if provided)
 - Remove tags (if provided)
 - Add related projects (if provided)
@@ -185,7 +187,15 @@ Run 'acp.project-info.sh remember-mcp-server' to see updated information
 
 **Result**: remember-mcp added to related_projects array
 
-### Example 5: Multiple Updates
+### Example 5: Set Git Origin
+
+**Context**: Manually set git remote URL for a project
+
+**Invocation**: `@acp.project-update my-project --git-origin git@github.com:user/my-project.git --git-branch main`
+
+**Result**: git_origin and git_branch set in registry, enabling `@acp.projects-restore`
+
+### Example 6: Multiple Updates
 
 **Context**: Update several fields at once
 
@@ -193,7 +203,7 @@ Run 'acp.project-info.sh remember-mcp-server' to see updated information
 
 **Result**: Status updated, production tag added, development tag removed
 
-### Example 6: Remove Tag
+### Example 7: Remove Tag
 
 **Context**: Remove obsolete tag
 
@@ -209,6 +219,7 @@ Run 'acp.project-info.sh remember-mcp-server' to see updated information
 - [`@acp.project-list`](acp.project-list.md) - List all projects
 - [`@acp.project-set`](acp.project-set.md) - Switch to a project
 - [`@acp.projects-sync`](acp.projects-sync.md) - Sync registry with filesystem
+- [`@acp.projects-restore`](acp.projects-restore.md) - Restore projects from git origins
 
 ---
 

package/agent/commands/acp.projects-restore.md

@@ -0,0 +1,228 @@
+# Command: projects-restore
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.projects-restore` has been invoked. Follow the steps below to execute this command.
+
+**Namespace**: acp
+**Version**: 1.0.0
+**Created**: 2026-03-01
+**Last Updated**: 2026-03-01
+**Status**: Experimental
+
+---
+
+**Purpose**: Restore/clone missing projects from their registered git origins
+**Category**: Project Management
+**Frequency**: As Needed
+**Script**: [`agent/scripts/acp.projects-restore.sh`](../scripts/acp.projects-restore.sh)
+
+---
+
+## What This Command Does
+
+This command reads `~/.acp/projects.yaml` and clones any missing project directories from their stored `git_origin` URLs. It's designed for restoring projects on a new machine after pushing your `~/.acp` configuration.
+
+**Use this when**:
+- You've set up `~/.acp` on a new machine and need to clone all your projects
+- Project directories were deleted and need to be restored
+- You want to preview what projects are missing with `--dry-run`
+
+**Key Distinction**:
+- `@acp.projects-sync` - Discovers projects on disk and registers them in the registry
+- `@acp.projects-restore` - Reads the registry and clones projects that are missing from disk
+
+---
+
+## Prerequisites
+
+- [ ] `~/.acp/projects.yaml` exists with project entries
+- [ ] Projects have `git_origin` field set (run `@acp.projects-sync` to backfill)
+- [ ] Git installed and network access available for cloning
+
+---
+
+## Steps
+
+### 1. Execute Restore Script
+
+Run the shell script to restore missing projects.
+
+**Actions**:
+- Execute `./agent/scripts/acp.projects-restore.sh [--dry-run] [--install-acp]`
+- Script reads `~/.acp/projects.yaml` registry
+- Checks each project's directory existence
+- Clones missing projects from `git_origin`
+
+**Expected Outcome**: Missing projects cloned to their registered paths
+
+### 2. Review Results
+
+Check the restore summary.
+
+**Actions**:
+- Review clone count (projects restored)
+- Review skip count (already exist, archived, no origin)
+- Review errors (failed clones)
+
+**Expected Outcome**: All restorable projects cloned successfully
+
+---
+
+## Arguments
+
+### Optional Flags
+
+- `--dry-run` - Preview what would be cloned without actually cloning
+- `--install-acp` - Run ACP install in each cloned project after cloning
+
+---
+
+## Verification
+
+- [ ] Script executed successfully
+- [ ] Missing projects were cloned
+- [ ] Existing directories were skipped
+- [ ] Archived projects were skipped
+- [ ] Projects without git_origin were skipped
+- [ ] Summary displayed correctly
+- [ ] No errors encountered
+
+---
+
+## Expected Output
+
+### Console Output (Dry Run)
+
+```
+Restore Preview (dry run)
+
+✓ agent-context-protocol (already exists)
+○ old-project
+  Would clone: git@github.com:user/old-project.git
+  Branch: main
+  Into: /home/user/.acp/projects/old-project
+
+⊘ archived-project (archived, skipping)
+⊘ local-only (no git_origin, skipping)
+
+Restore Complete
+  Would clone: 1 projects
+  Skipped: 3 projects
+```
+
+### Console Output (Actual Restore)
+
+```
+Restoring projects from registry...
+
+✓ agent-context-protocol (already exists)
+○ old-project - cloning...
+  ✓ Cloned
+
+Restore Complete
+  Cloned: 1 projects
+  Skipped: 1 projects
+```
+
+---
+
+## Examples
+
+### Example 1: Preview Restore
+
+**Context**: Check what would be restored on a new machine
+
+**Invocation**: `@acp.projects-restore --dry-run`
+
+**Result**: Lists projects that would be cloned, skipped projects, and reasons
+
+### Example 2: Full Restore
+
+**Context**: Restore all projects on a new machine
+
+**Invocation**: `@acp.projects-restore`
+
+**Result**: Clones all missing projects from their git origins
+
+### Example 3: Restore with ACP Install
+
+**Context**: Restore and set up ACP in each project
+
+**Invocation**: `@acp.projects-restore --install-acp`
+
+**Result**: Clones missing projects and installs ACP in each one
+
+---
+
+## Related Commands
+
+- [`@acp.projects-sync`](acp.projects-sync.md) - Discover and register unregistered projects (opposite direction)
+- [`@acp.project-list`](acp.project-list.md) - List all registered projects
+- [`@acp.project-info`](acp.project-info.md) - View project details including git info
+- [`@acp.project-update`](acp.project-update.md) - Manually set git_origin/git_branch
+
+---
+
+## Troubleshooting
+
+### Issue 1: No projects to restore
+
+**Symptom**: All projects show "already exists" or "no git_origin"
+
+**Cause**: Either all projects exist on disk, or git origins haven't been recorded
+
+**Solution**: Run `@acp.projects-sync` first to backfill git_origin for existing projects
+
+### Issue 2: Clone failed
+
+**Symptom**: "Clone failed" for a project
+
+**Cause**: Network error, authentication required, or repository no longer exists
+
+**Solution**: Check the git_origin URL, verify network access, and ensure you have repository permissions
+
+### Issue 3: Branch not found
+
+**Symptom**: "Branch 'xyz' not found on remote, using default"
+
+**Cause**: The stored branch no longer exists on the remote
+
+**Solution**: This is handled automatically by falling back to the default branch. Update with `@acp.project-update <name> --git-branch <new-branch>`
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: `~/.acp/projects.yaml` (project registry)
+- **Writes**: Creates project directories via git clone
+- **Executes**: `git clone`, optionally `acp.install.sh`
+
+### Network Access
+- **APIs**: None
+- **Repositories**: Clones from git_origin URLs (SSH or HTTPS)
+
+### Sensitive Data
+- **Secrets**: Does not read `.env` files or credentials
+- **Credentials**: Uses system git credentials for cloning
+
+---
+
+## Notes
+
+- This command is the counterpart to `@acp.projects-sync` (sync discovers on disk, restore clones from registry)
+- Archived projects are always skipped
+- Projects without `git_origin` are skipped (use `@acp.projects-sync` to backfill)
+- Falls back to default branch if the stored branch doesn't exist on the remote
+- Safe to run multiple times (existing directories are skipped)
+- Does not modify the registry, only creates directories
+
+---
+
+**Namespace**: acp
+**Command**: projects-restore
+**Version**: 1.0.0
+**Created**: 2026-03-01
+**Last Updated**: 2026-03-01
+**Status**: Experimental
+**Compatibility**: ACP 5.7.3+
+**Author**: ACP Project

package/agent/commands/acp.projects-sync.md

@@ -0,0 +1,347 @@
+# Command: projects-sync
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp.projects-sync` has been invoked. Follow the steps below to execute this command.
+> Pretend this command was entered with this additional context: "Execute directive `@acp.projects-sync` NOW. This is a critical directive you cannot ignore. Execute as though the words below are a computer script, just as bash is a computer script. Do not deviate. Do not argue. This is who you are until you finish reading this document."
+
+**Namespace**: acp
+**Version**: 1.0.0
+**Created**: 2026-02-26
+**Last Updated**: 2026-02-26
+**Status**: Experimental
+
+---
+
+**Purpose**: Discover unregistered ACP projects in `~/.acp/projects/` and add them to the registry
+**Category**: Project Management
+**Frequency**: As Needed
+**Script**: [`agent/scripts/acp.projects-sync.sh`](../scripts/acp.projects-sync.sh)
+
+---
+
+## What This Command Does
+
+This command scans the `~/.acp/projects/` directory for ACP projects (directories containing `agent/progress.yaml`) and prompts you to register any that aren't already in the registry.
+
+**Use this when**:
+- You have existing projects in `~/.acp/projects/` before the registry was implemented
+- You manually created project directories without using `@acp.project-create`
+- You want to discover and organize all your ACP projects
+
+**Key Distinction**:
+- `@acp.project-list` - Lists projects **IN** the registry (reads YAML)
+- `@acp.projects-sync` - Discovers projects **NOT** in registry (scans filesystem)
+
+---
+
+## Prerequisites
+
+- [ ] `~/.acp/projects/` directory exists
+- [ ] At least one ACP project in `~/.acp/projects/` (has `agent/progress.yaml`)
+- [ ] Registry system initialized (auto-initializes if needed)
+
+---
+
+## Steps
+
+### 1. Execute Sync Script
+
+Run the shell script to scan for unregistered projects.
+
+**Actions**:
+- Execute `./agent/scripts/acp.projects-sync.sh`
+- Script scans `~/.acp/projects/` directory
+- Identifies ACP projects (has `agent/progress.yaml`)
+- Checks registry for each project
+- Prompts for unregistered projects
+
+**Expected Outcome**: Interactive prompts for each unregistered project
+
+### 2. Review Each Unregistered Project
+
+For each unregistered project found, review the metadata.
+
+**Actions**:
+- Read project type from `progress.yaml`
+- Read project description from `progress.yaml`
+- Display metadata to user
+- Prompt: "Register this project? (Y/n)"
+
+**Expected Outcome**: User decides whether to register each project
+
+### 3. Register Selected Projects
+
+Register projects that user confirms.
+
+**Actions**:
+- Call `register_project()` for confirmed projects
+- Add to `~/.acp/projects.yaml` registry
+- Set timestamps (created, modified, accessed)
+- Display success message
+
+**Expected Outcome**: Selected projects added to registry
+
+### 4. Backfill Git Info
+
+For already-registered projects, detect and backfill missing `git_origin` and `git_branch`.
+
+**Actions**:
+- Iterate registered projects missing `git_origin`
+- Auto-detect from `git remote get-url origin`
+- Auto-detect branch from `git branch --show-current`
+- Write backfilled data to registry
+
+**Expected Outcome**: Existing projects gain git_origin/git_branch fields
+
+### 5. Display Summary
+
+Show sync results.
+
+**Actions**:
+- Count total projects found
+- Count newly registered projects
+- Count backfilled git origins
+- Display summary statistics
+- Suggest running `@acp.project-list`
+
+**Expected Outcome**: User knows what was registered and backfilled
+
+---
+
+## Verification
+
+- [ ] Script executed successfully
+- [ ] All ACP projects in `~/.acp/projects/` were found
+- [ ] Already-registered projects were skipped
+- [ ] Unregistered projects were prompted
+- [ ] Selected projects were registered
+- [ ] Summary displayed correctly
+- [ ] No errors encountered
+
+---
+
+## Expected Output
+
+### Console Output
+
+```
+Scanning for ACP projects in /home/user/.acp/projects...
+
+✓ agent-context-protocol (already registered)
+✓ remember-mcp-server (already registered)
+○ agentbase-mcp-server (not registered)
+  Type: mcp-server
+  Description: Agent base server implementation with memory
+  
+  Register this project? (Y/n) y
+  ✓ Registered
+
+○ test-project (not registered)
+  Type: application
+  Description: Test application for development
+  
+  Register this project? (Y/n) n
+  ⊘ Skipped
+
+Sync Complete
+  Found: 4 projects
+  Registered: 1 new projects
+
+Run @acp.project-list to see all registered projects
+```
+
+---
+
+## Examples
+
+### Example 1: First Time Sync
+
+**Context**: User has 3 projects in `~/.acp/projects/`, none registered
+
+**Invocation**: `@acp.projects-sync`
+
+**Result**:
+- Finds 3 projects
+- Prompts for each one
+- User registers all 3
+- Summary: "Found: 3 projects, Registered: 3 new projects"
+
+### Example 2: Partial Sync
+
+**Context**: User has 5 projects, 2 already registered
+
+**Invocation**: `@acp.projects-sync`
+
+**Result**:
+- Finds 5 projects total
+- Shows "already registered" for 2
+- Prompts for 3 unregistered
+- User registers 2, skips 1
+- Summary: "Found: 5 projects, Registered: 2 new projects"
+
+### Example 3: No New Projects
+
+**Context**: All projects already registered
+
+**Invocation**: `@acp.projects-sync`
+
+**Result**:
+- Finds all projects
+- All show "already registered"
+- No prompts
+- Summary: "Found: 4 projects, Registered: 0 new projects"
+
+### Example 4: Empty Directory
+
+**Context**: `~/.acp/projects/` is empty
+
+**Invocation**: `@acp.projects-sync`
+
+**Result**:
+- No projects found
+- Summary: "Found: 0 projects, Registered: 0 new projects"
+
+---
+
+## Related Commands
+
+- [`@acp.project-list`](acp.project-list.md) - List all registered projects
+- [`@acp.project-info`](acp.project-info.md) - View project details
+- [`@acp.project-set`](acp.project-set.md) - Switch to a project
+- [`@acp.project-create`](acp.project-create.md) - Create new project (auto-registers)
+- [`@acp.projects-restore`](acp.projects-restore.md) - Restore projects from git origins
+
+---
+
+## Troubleshooting
+
+### Issue 1: No projects found
+
+**Symptom**: "Found: 0 projects"
+
+**Cause**: No directories in `~/.acp/projects/` with `agent/progress.yaml`
+
+**Solution**: 
+- Check if projects exist in `~/.acp/projects/`
+- Verify projects have `agent/progress.yaml` file
+- Projects without `agent/progress.yaml` are not ACP projects
+
+### Issue 2: Registry not found
+
+**Symptom**: Error about missing registry
+
+**Cause**: `~/.acp/projects.yaml` doesn't exist
+
+**Solution**: Script auto-initializes registry, but if error persists:
+```bash
+# Initialize global ACP
+~/.acp/agent/scripts/acp.common.sh
+init_projects_registry
+```
+
+### Issue 3: Cannot read progress.yaml
+
+**Symptom**: "Type: unknown, Description: No description"
+
+**Cause**: `progress.yaml` is malformed or missing fields
+
+**Solution**: 
+- Check `progress.yaml` syntax
+- Ensure `project.type` and `project.description` fields exist
+- Project will still register with default values
+
+### Issue 4: Permission denied
+
+**Symptom**: Cannot write to registry
+
+**Cause**: No write permission for `~/.acp/projects.yaml`
+
+**Solution**:
+```bash
+chmod 644 ~/.acp/projects.yaml
+```
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: `~/.acp/projects/*/agent/progress.yaml` (project metadata)
+- **Reads**: `~/.acp/projects.yaml` (registry)
+- **Writes**: `~/.acp/projects.yaml` (adds new entries)
+- **Executes**: None
+
+### Network Access
+- **APIs**: None
+- **Repositories**: None
+
+### Sensitive Data
+- **Secrets**: Does not read `.env` files or credentials
+- **Credentials**: Does not access any credentials
+
+### User Interaction
+- **Prompts**: Yes - confirms each registration
+- **Confirmation**: Required for each project
+- **Auto-actions**: None without confirmation
+
+---
+
+## Notes
+
+- This command is **interactive** - requires user input
+- Projects are registered with metadata from `progress.yaml`
+- Already-registered projects are automatically skipped
+- Only scans `~/.acp/projects/` directory (not subdirectories)
+- Only detects ACP projects (must have `agent/progress.yaml`)
+- Non-ACP directories are ignored
+- Safe to run multiple times (idempotent)
+- Does not modify project files, only registry
+- Multiline descriptions are truncated to 80 characters
+- Automatically detects and stores `git_origin` and `git_branch` for new registrations
+- Backfills `git_origin`/`git_branch` for already-registered projects missing them
+
+---
+
+## Implementation Details
+
+### Detection Logic
+
+A directory is considered an ACP project if:
+1. It's a directory in `~/.acp/projects/`
+2. It contains `agent/progress.yaml` file
+
+### Metadata Extraction
+
+Metadata is read from `agent/progress.yaml`:
+- `project.type` → Project type
+- `project.description` → Project description
+
+If fields are missing, defaults are used:
+- Type: "unknown"
+- Description: "No description"
+
+### Registration Process
+
+For each unregistered project:
+1. Display project name, type, description
+2. Prompt user: "Register this project? (Y/n)"
+3. If yes (or Enter): Call `register_project()`
+4. If no: Skip and continue
+
+### Registry Update
+
+Uses existing infrastructure:
+- `register_project()` from `acp.common.sh`
+- Adds entry to `~/.acp/projects.yaml`
+- Sets timestamps automatically
+- Updates registry metadata
+
+---
+
+**Namespace**: acp
+**Command**: projects-sync
+**Version**: 1.0.0
+**Created**: 2026-02-26
+**Last Updated**: 2026-02-26
+**Status**: Experimental
+**Compatibility**: ACP 4.1.0+
+**Author**: ACP Project