@prmichaelsen/remember-mcp 2.2.1 → 2.3.1

package/AGENT.md

@@ -1,9 +1,9 @@
 # Agent Context Protocol (ACP)
 
-**Also Known As**: The Agent Directory Pattern  
-**Version**: 1.0.3
-**Created**: 2026-02-11  
-**Status**: Production Pattern  
+**Also Known As**: The Agent Directory Pattern
+**Version**: 1.2.0
+**Created**: 2026-02-11
+**Status**: Production Pattern
 
 ---
 
@@ -81,6 +81,14 @@ ACP solves these by:
 project-root/
 ├── AGENT.md                        # This file - ACP documentation
 ├── agent/                          # Agent directory (ACP structure)
+│   ├── commands/                   # Command system
+│   │   ├── .gitkeep
+│   │   ├── command.template.md     # Command template
+│   │   ├── acp.init.md             # @acp-init
+│   │   ├── acp.proceed.md          # @acp-proceed
+│   │   ├── acp.status.md           # @acp-status
+│   │   └── ...                     # More commands
+│   │
 │   ├── design/                     # Design documents
 │   │   ├── .gitkeep
 │   │   ├── requirements.md         # Core requirements
@@ -551,6 +559,91 @@ The Agent Pattern represents a **paradigm shift** in how we approach AI-assisted
 
 ---
 
+## ACP Commands
+
+ACP supports a command system for common workflows. Commands are file-based triggers that provide standardized, discoverable interfaces for ACP operations.
+
+### What are ACP Commands?
+
+Commands are markdown files in [`agent/commands/`](agent/commands/) that contain step-by-step instructions for AI agents. Instead of typing long prompts like "AGENT.md: Initialize", you can reference command files like `@acp.init` to trigger specific workflows.
+
+**Benefits**:
+- **Discoverable**: Browse [`agent/commands/`](agent/commands/) to see all available commands
+- **Consistent**: All commands follow the same structure
+- **Extensible**: Create custom commands for your project
+- **Self-Documenting**: Each command file contains complete documentation
+- **Autocomplete-Friendly**: Type `@acp.` to see all ACP commands
+
+### Core Commands
+
+Core ACP commands use the `acp.` prefix and are available in [`agent/commands/`](agent/commands/):
+
+- **[`@acp.init`](agent/commands/acp.init.md)** - Initialize agent context (replaces "AGENT.md: Initialize")
+- **[`@acp.proceed`](agent/commands/acp.proceed.md)** - Continue with next task (replaces "AGENT.md: Proceed")
+- **[`@acp.status`](agent/commands/acp.status.md)** - Display project status
+- **[`@acp.version-check`](agent/commands/acp.version-check.md)** - Show current ACP version
+- **[`@acp.version-check-for-updates`](agent/commands/acp.version-check-for-updates.md)** - Check for ACP updates
+- **[`@acp.version-update`](agent/commands/acp.version-update.md)** - Update ACP to latest version
+
+### Command Invocation
+
+Commands are invoked using the `@` syntax with dot notation:
+
+```
+@acp.init                    → agent/commands/acp.init.md
+@acp.proceed                 → agent/commands/acp.proceed.md
+@acp.status                  → agent/commands/acp.status.md
+@deploy.production           → agent/commands/deploy.production.md
+```
+
+**Format**: `@{namespace}.{action}` resolves to `agent/commands/{namespace}.{action}.md`
+
+### Creating Custom Commands
+
+To create custom commands for your project:
+
+1. **Choose a namespace** (e.g., `deploy`, `test`, `custom`)
+   - ⚠️ The `acp` namespace is reserved for core commands
+   - Use descriptive, single-word namespaces
+
+2. **Copy the command template**:
+   ```bash
+   cp agent/commands/command.template.md agent/commands/{namespace}.{action}.md
+   ```
+
+3. **Fill in the template sections**:
+   - Purpose and description
+   - Prerequisites
+   - Step-by-step instructions
+   - Verification checklist
+   - Examples and troubleshooting
+
+4. **Invoke your command**: `@{namespace}.{action}`
+
+**Example**: Creating a deployment command:
+```bash
+# Create the command file
+cp agent/commands/command.template.md agent/commands/deploy.production.md
+
+# Edit the file with your deployment steps
+# ...
+
+# Invoke it
+@deploy.production
+```
+
+### Command Template
+
+See [`agent/commands/command.template.md`](agent/commands/command.template.md) for the complete command template with all sections and examples.
+
+### Installing Third-Party Commands
+
+Use `@acp.install` to install command packages from git repositories (available in future release).
+
+**Security Note**: Third-party commands can instruct agents to modify files and execute scripts. Always review command files before installation.
+
+---
+
 ## Sample Prompts for Using ACP
 
 ### Initialize Prompt
@@ -882,7 +975,7 @@ This repository is actively maintained with improvements to the ACP methodology
 ./agent/scripts/update.sh
 
 # Or download and run directly
-curl -fsSL https://raw.githubusercontent.com/prmichaelsen/agent-context-protocol/mainlin./agent/scripts/update.sh | bash
+curl -fsSL https://raw.githubusercontent.com/prmichaelsen/agent-context-protocol/mainline/agent/scripts/update.sh | bash
 ```
 
 The update script will:

package/CHANGELOG.md

@@ -5,6 +5,51 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2026-02-16
+
+### ✨ Added
+
+- **Shared Spaces**: Publish memories to shared discovery spaces
+  - "The Void" - First shared space for discovering thoughts and ideas
+  - Space collections: `Memory_the_void` with snake_case naming
+  - Multi-user discovery with attribution tracking
+
+- **Token-Based Confirmation**: Secure two-phase workflow for sensitive operations
+  - One-time use tokens with 5-minute expiry
+  - Firestore storage: `users/{user_id}/requests`
+  - Generic pattern extensible to other confirmable actions
+
+- **5 New MCP Tools**:
+  - `remember_publish` - Request to publish memory to shared space (generates token)
+  - `remember_confirm` - Confirm and execute pending actions
+  - `remember_deny` - Cancel pending actions
+  - `remember_search_space` - Search shared spaces with hybrid search
+  - `remember_query_space` - Query shared spaces with natural language
+
+- **Confirmation Token Service**: Manages tokens with automatic expiry
+  - UUID v4 tokens
+  - Status tracking (pending, confirmed, denied, expired, retracted)
+  - Firestore TTL integration for automatic cleanup
+
+- **Space Memory Types**: SpaceMemory interface with attribution fields
+  - `space_id`, `author_id`, `ghost_id`, `published_at`, `discovery_count`
+  - Support for pseudonymous publishing (ghost profiles)
+
+### 🔧 Changed
+
+- Tool count increased from 12 to 17
+- Firestore structure: Added `users/{user_id}/requests` for confirmation tokens
+- Collection naming: snake_case for spaces ("The Void" → `the_void` → `Memory_the_void`)
+
+### 🔒 Security
+
+- One-time use tokens prevent replay attacks
+- User ownership verification before publishing
+- Fresh data fetch during confirmation (not from stored payload)
+- 5-minute token expiry prevents stale requests
+
+---
+
 ## [2.0.2] - 2026-02-14
 
 ### ✨ Added

package/README.md

@@ -63,8 +63,10 @@ Multi-tenant memory system MCP server with vector search, relationships, and tru
 
 ## Features
 
-- **12 MCP Tools**: Complete CRUD for memories, relationships, and preferences
+- **17 MCP Tools**: Complete CRUD for memories, relationships, preferences, and shared spaces
 - **Multi-Tenant**: Per-user isolation with secure data boundaries
+- **Shared Spaces**: Publish memories to shared discovery spaces like "The Void"
+- **Token-Based Confirmation**: Secure two-phase workflow for sensitive operations
 - **Vector Search**: Semantic + keyword hybrid search with Weaviate
 - **Knowledge Graph**: N-way relationships with bidirectional tracking
 - **RAG Queries**: Natural language queries with context-aware responses
@@ -146,10 +148,48 @@ await wrapped.start();
 
 ## Architecture
 
-- **Weaviate**: Vector storage for memories, relationships, templates
-- **Firestore**: Permissions, preferences, metadata
+- **Weaviate**: Vector storage for memories, relationships, and shared spaces
+  - Personal collections: `Memory_{user_id}`
+  - Shared collections: `Memory_the_void`, `Memory_public_space`
+- **Firestore**: Permissions, preferences, confirmation tokens
+  - User data: `users/{user_id}/preferences`, `users/{user_id}/requests`
 - **Firebase Auth**: User authentication
 
+## Shared Spaces
+
+Publish memories to shared discovery spaces where other users can find them.
+
+### The Void
+
+"The Void" is a shared space for discovering thoughts and ideas from other users.
+
+### Publishing Workflow
+
+1. **Request Publication**: Generate confirmation token
+```typescript
+remember_publish({ memory_id: "abc123", target: "the_void" })
+// Returns: { success: true, token: "xyz789" }
+```
+
+2. **User Confirms**: Execute the publication
+```typescript
+remember_confirm({ token: "xyz789" })
+// Returns: { success: true, space_memory_id: "new-id" }
+```
+
+3. **Discover**: Search shared spaces
+```typescript
+remember_search_space({ query: "interesting ideas", space: "the_void" })
+```
+
+### Space Tools (5 new)
+
+- `remember_publish` - Request to publish memory (generates token)
+- `remember_confirm` - Confirm any pending action
+- `remember_deny` - Cancel any pending action
+- `remember_search_space` - Search shared spaces
+- `remember_query_space` - Ask questions about shared memories
+
 ## Documentation
 
 See `agent/` directory for:

package/agent/commands/acp.init.md

@@ -0,0 +1,376 @@
+# Command: init
+
+> **🤖 Agent Directive**: If you are reading this file, the command `@acp-init` has been invoked. Follow the steps below to execute this command.
+
+**Namespace**: acp
+**Version**: 1.0.0
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16
+**Status**: Active
+
+---
+
+**Purpose**: Initialize agent context by loading all documentation, reviewing source code, and preparing for work
+**Category**: Workflow
+**Frequency**: Once Per Session
+
+---
+
+## What This Command Does
+
+This command performs a comprehensive initialization of the agent's context for working on an ACP-structured project. It checks for ACP updates, reads all documentation in the `agent/` directory, reviews key source files to understand the current implementation, updates any stale documentation, and refreshes progress tracking.
+
+Use this command at the start of each work session to ensure you have complete project context. It's the most thorough way to get up to speed on a project, understanding both what's documented and what's actually implemented in the code.
+
+Unlike `@acp-status` which only reads progress.yaml, or `@acp-proceed` which focuses on a single task, `@acp-init` provides comprehensive context loading across all project documentation and source code. It's designed to answer: "What is this project? Where does it stand? What needs to be done?"
+
+---
+
+## Prerequisites
+
+- [ ] ACP installed in project (AGENT.md and agent/ directory exist)
+- [ ] Project has source code to review
+- [ ] Git repository initialized (optional, for update checking)
+
+---
+
+## Steps
+
+### 1. Check for ACP Updates
+
+Check if newer version of ACP is available.
+
+**Actions**:
+- Run `./agent/scripts/check-for-updates.sh` if it exists
+- Report if updates are available
+- Show what changed via CHANGELOG
+- Ask if user wants to update (don't auto-update)
+
+**Expected Outcome**: User informed of ACP version status
+
+### 2. Read All Agent Documentation
+
+Load complete context from the agent/ directory.
+
+**Actions**:
+- Read `agent/progress.yaml` for current status
+- Read `agent/design/requirements.md` for project goals
+- Read all design documents in `agent/design/`
+- Read current milestone document
+- Read all task documents (focus on current/upcoming)
+- Read relevant pattern documents in `agent/patterns/`
+- Note any missing or incomplete documentation
+
+**Expected Outcome**: Complete documentation context loaded
+
+### 3. Identify Key Source Files
+
+Determine which source files are most important to review.
+
+**Actions**:
+- Check project type (package.json, requirements.txt, go.mod, etc.)
+- Identify main entry points (src/index.ts, main.py, cmd/main.go, etc.)
+- Note key configuration files (tsconfig.json, .env.example, etc.)
+- Identify core business logic files
+- List test files
+
+**Expected Outcome**: Key source files identified for review
+
+### 4. Review Key Source Files
+
+Read important source files to understand current implementation.
+
+**Actions**:
+- Read main entry point files
+- Review core business logic
+- Check configuration files
+- Note any TODOs or FIXMEs
+- Understand current architecture
+- Compare implementation with design documents
+
+**Expected Outcome**: Current implementation understood
+
+### 5. Identify Documentation Drift
+
+Compare documentation with actual implementation.
+
+**Actions**:
+- Check if design documents match implementation
+- Note any undocumented features in code
+- Identify outdated documentation
+- Flag missing documentation
+- List discrepancies
+
+**Expected Outcome**: Documentation gaps identified
+
+### 6. Update Stale Documentation
+
+Refresh outdated documentation to match current state.
+
+**Actions**:
+- Update design documents if implementation differs
+- Update task documents if steps have changed
+- Add notes about discovered issues
+- Update progress.yaml with current understanding
+- Document any new patterns found in code
+
+**Expected Outcome**: Documentation synchronized with code
+
+### 7. Update Progress Tracking
+
+Refresh progress.yaml with latest status.
+
+**Actions**:
+- Verify current milestone is correct
+- Confirm current task is accurate
+- Update progress percentages if needed
+- Add recent work entry for initialization
+- Update next steps based on current state
+- Note any new blockers discovered
+
+**Expected Outcome**: Progress tracking is current and accurate
+
+### 8. Report Status and Next Steps
+
+Provide comprehensive status report.
+
+**Actions**:
+- Summarize project status
+- Show current milestone and progress
+- Identify current task
+- List recent accomplishments
+- Highlight next steps
+- Note any blockers or concerns
+- Provide recommendations
+
+**Expected Outcome**: User has complete context and knows what to do next
+
+---
+
+## Verification
+
+- [ ] ACP update check completed
+- [ ] All agent/ files read successfully
+- [ ] Key source files identified and reviewed
+- [ ] Documentation drift identified (if any)
+- [ ] Stale documentation updated
+- [ ] progress.yaml updated with current status
+- [ ] Comprehensive status report provided
+- [ ] Next steps clearly identified
+- [ ] No errors encountered during initialization
+
+---
+
+## Expected Output
+
+### Files Modified
+- `agent/progress.yaml` - Updated with current status, recent work entry added
+- Design/task documents - Updated if stale (as needed)
+
+### Console Output
+```
+🚀 Initializing Agent Context
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✓ Checking for ACP updates...
+  Current version: 1.0.3
+  Status: Up to date
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📚 Reading Agent Documentation...
+  ✓ Read agent/progress.yaml
+  ✓ Read agent/design/requirements.md
+  ✓ Read agent/design/acp-commands-design.md
+  ✓ Read agent/milestones/milestone-1-acp-commands.md
+  ✓ Read agent/milestones/milestone-2-acp-commands-advanced.md
+  ✓ Read agent/tasks/task-1-commands-infrastructure.md
+  ✓ Read agent/tasks/task-2-workflow-commands.md
+  ✓ Read agent/tasks/task-3-version-commands.md
+  ✓ Read agent/tasks/task-4-update-documentation.md
+  
+  Total: 9 agent files read
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📂 Reviewing Source Files...
+  ✓ Read AGENT.md (1,055 lines)
+  ✓ Read README.md (200 lines)
+  ✓ Read CHANGELOG.md (50 lines)
+  ✓ Read scripts/install.sh
+  ✓ Read scripts/update.sh
+  ✓ Read agent/commands/command.template.md
+  ✓ Read agent/commands/acp.status.md
+  ✓ Read agent/commands/acp.proceed.md
+  
+  Total: 8 source files reviewed
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🔍 Documentation Analysis...
+  ✓ Design documents match implementation
+  ✓ Task documents are current
+  ⚠️  Task-2 document references old nested structure (acp/init.md)
+  ✓ Progress tracking is accurate
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📝 Updating Documentation...
+  ✓ Updated progress.yaml with initialization entry
+  ℹ️  No other updates needed
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📊 Project Status
+
+Project: agent-context-protocol (v1.0.3)
+Status: in_progress
+Started: 2026-02-16
+
+Current Milestone: M1 - ACP Commands Infrastructure
+Progress: 33% (1/4 tasks completed)
+Status: in_progress
+
+Current Task: task-2 - Implement Core Workflow Commands
+Status: in_progress (2/3 commands complete)
+File: agent/tasks/task-2-workflow-commands.md
+
+Recent Work (2026-02-16):
+  - ✅ Created comprehensive design document
+  - ✅ Implemented @acp-status command
+  - ✅ Implemented @acp-proceed command
+  - 📋 Next: Complete workflow commands (init)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎯 Next Steps:
+  1. Complete task-2: Implement acp.init.md command
+  2. Start task-3: Implement version commands
+  3. Complete milestone-1: All 6 core commands
+
+⚠️  Current Blockers: None
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+✅ Initialization Complete!
+Ready to proceed with task-2 completion.
+```
+
+### Status Update
+- Recent work entry added to progress.yaml
+- Context fully loaded
+- Ready to work
+
+---
+
+## Examples
+
+### Example 1: Starting Fresh Session
+
+**Context**: Beginning work on a project for the first time today
+
+**Invocation**: `@acp-init`
+
+**Result**: Checks for updates, reads all 15 agent files, reviews 10 source files, updates progress tracking, reports you're on milestone 2 task 5, ready to continue
+
+### Example 2: Returning After Break
+
+**Context**: Haven't worked on project in a week
+
+**Invocation**: `@acp-init`
+
+**Result**: Full context reload, discovers 3 new commits since last session, updates documentation to reflect changes, shows current status (milestone 3, 80% complete), identifies next task
+
+### Example 3: New Agent Session
+
+**Context**: Different AI agent picking up the project
+
+**Invocation**: `@acp-init`
+
+**Result**: Complete onboarding - reads all documentation, understands architecture from source code, gets current status, ready to contribute immediately
+
+---
+
+## Related Commands
+
+- [`@acp-proceed`](acp.proceed.md) - Use after init to start working on current task
+- [`@acp-status`](acp.status.md) - Use for quick status check without full initialization
+- [`@acp-sync`](acp.sync.md) - Use to sync documentation after code changes
+- [`@acp-version-check-for-updates`](acp.version-check-for-updates.md) - Part of init process
+
+---
+
+## Troubleshooting
+
+### Issue 1: No agent/ directory found
+
+**Symptom**: Error message "agent/ directory not found"
+
+**Cause**: ACP not installed in this project
+
+**Solution**: Install ACP first using the installation script from the ACP repository
+
+### Issue 2: Update check script not found
+
+**Symptom**: Warning "check-for-updates.sh not found"
+
+**Cause**: Older ACP installation without update scripts
+
+**Solution**: This is non-critical, continue with initialization. Consider updating ACP to latest version.
+
+### Issue 3: No source files found
+
+**Symptom**: Warning "No source files to review"
+
+**Cause**: Project is new or source code is in unexpected location
+
+**Solution**: This is fine for new projects. Specify source file locations if they're in non-standard directories.
+
+### Issue 4: progress.yaml doesn't exist
+
+**Symptom**: Error "Cannot read progress.yaml"
+
+**Cause**: Progress tracking not initialized yet
+
+**Solution**: Create progress.yaml from template: `cp agent/progress.template.yaml agent/progress.yaml`, then run `@acp-init` again
+
+---
+
+## Security Considerations
+
+### File Access
+- **Reads**: All files in `agent/` directory, key source files throughout project, AGENT.md, README.md, CHANGELOG.md
+- **Writes**: `agent/progress.yaml` (updates status), design/task documents (if stale)
+- **Executes**: `./agent/scripts/check-for-updates.sh` (if exists)
+
+### Network Access
+- **APIs**: None directly (update check script may access GitHub)
+- **Repositories**: Update check script accesses GitHub repository
+
+### Sensitive Data
+- **Secrets**: Never reads .env files or credential files
+- **Credentials**: Does not access any credentials
+
+---
+
+## Notes
+
+- This is the most comprehensive ACP command - expect 30-60 seconds for large projects
+- Reads many files to build complete context
+- Updates documentation if drift is detected
+- Safe to run multiple times (idempotent)
+- Replaces the old "AGENT.md: Initialize" prompt
+- Consider running at start of each session for best results
+- Can be run mid-session if you need to refresh context
+
+---
+
+**Namespace**: acp
+**Command**: init
+**Version**: 1.0.0
+**Created**: 2026-02-16
+**Last Updated**: 2026-02-16
+**Status**: Active
+**Compatibility**: ACP 1.0.3+
+**Author**: ACP Project