@prmichaelsen/remember-mcp 2.8.0 → 3.12.0

package/agent/tasks/milestone-14-memory-collection-v2/task-173-documentation-examples.md

@@ -0,0 +1,258 @@
+# Task 173: Documentation and Examples
+
+**Milestone**: Milestone 14 - Memory Collection Pattern v2
+**Estimated Time**: 4-6 hours
+**Dependencies**: All previous tasks
+**Status**: Not Started
+
+---
+
+## Objective
+
+Create comprehensive documentation for Memory Collection Pattern v2, including API documentation, migration guide, architecture documentation, and usage examples.
+
+---
+
+## Steps
+
+### 1. Create API Documentation
+
+**File**: `docs/api/v2-tools.md`
+
+**Actions**:
+- Document all updated tools (publish, retract, revise, search, create, update)
+- Include input schemas
+- Include output formats
+- Include error codes
+- Provide code examples for each tool
+
+**Expected Content**:
+```markdown
+# Memory Collection Pattern v2 - API Documentation
+
+## remember_publish
+
+Publish a memory to multiple spaces and/or groups.
+
+**Input Schema**:
+```typescript
+{
+  memory_id: string,
+  spaces?: string[],
+  groups?: string[],
+  user_id?: string
+}
+```
+
+**Example**:
+```typescript
+remember_publish({
+  memory_id: "my-recipe",
+  spaces: ["cooking", "recipes"],
+  groups: ["{foodie-group}"]
+})
+```
+
+[... continue for all tools ...]
+```
+
+### 2. Create Migration Guide
+
+**File**: `docs/migration/v2-migration-guide.md`
+
+**Actions**:
+- Explain what changed in v2
+- Provide step-by-step migration instructions
+- Include dry-run example
+- Include rollback instructions
+- Document breaking changes
+- Provide troubleshooting tips
+
+**Expected Content**:
+```markdown
+# Migration Guide: v1 → v2
+
+## What Changed
+
+Memory Collection Pattern v2 introduces:
+- Dot notation collections (Memory.users, Memory.spaces, Memory.groups)
+- Composite IDs ({userId}.{memoryId})
+- Tracking arrays (space_ids, group_ids)
+- Multi-space/group publication
+- Revision support
+
+## Migration Steps
+
+### 1. Backup Your Data
+```bash
+npm run migrate:backup
+```
+
+### 2. Run Dry-Run
+```bash
+npm run migrate:dry-run
+```
+
+### 3. Review Preview
+[... detailed instructions ...]
+```
+
+### 3. Create Architecture Documentation
+
+**File**: `docs/architecture/v2-architecture.md`
+
+**Actions**:
+- Explain three-tier collection structure
+- Document composite ID format
+- Explain tracking arrays
+- Document dual publication pattern
+- Include diagrams
+
+**Expected Content**:
+```markdown
+# Memory Collection Pattern v2 - Architecture
+
+## Collection Structure
+
+### Memory.users.{userId}
+Private user memories with simple IDs.
+
+### Memory.spaces.public
+All public space memories with composite IDs.
+
+### Memory.groups.{groupId}
+Group memories with composite IDs.
+
+[... detailed architecture ...]
+```
+
+### 4. Create Usage Examples
+
+**File**: `docs/examples/v2-usage-examples.md`
+
+**Actions**:
+- Provide real-world usage scenarios
+- Include code examples
+- Show common patterns
+- Demonstrate best practices
+
+**Expected Content**:
+```markdown
+# Usage Examples
+
+## Example 1: Publishing a Recipe to Multiple Spaces
+
+```typescript
+// Create recipe
+const recipe = await remember_create_memory({
+  content: "My famous pasta recipe...",
+  content_type: "recipe"
+})
+
+// Publish to cooking and recipes spaces
+await remember_publish({
+  memory_id: recipe.id,
+  spaces: ["cooking", "recipes"]
+})
+
+// Later, update the recipe
+await remember_update_memory({
+  id: recipe.id,
+  content: "Updated recipe with new ingredient..."
+})
+
+// Sync changes to all published locations
+await remember_revise({
+  memory_id: recipe.id
+})
+```
+
+[... more examples ...]
+```
+
+### 5. Update README
+
+**File**: `README.md`
+
+**Actions**:
+- Update version to v2
+- Update feature list
+- Update quick start guide
+- Add migration notice
+- Update examples
+
+### 6. Create CHANGELOG Entry
+
+**File**: `CHANGELOG.md`
+
+**Actions**:
+- Document v2.0.0 release
+- List all breaking changes
+- List all new features
+- List all improvements
+- Include migration instructions link
+
+**Expected Content**:
+```markdown
+# Changelog
+
+## [2.0.0] - 2026-XX-XX
+
+### Breaking Changes
+- Memory collections now use dot notation (Memory.users, Memory.spaces, Memory.groups)
+- Published memories now use composite IDs ({userId}.{memoryId})
+- remember_publish now accepts arrays for spaces and groups
+- remember_search_space now filters by space_ids array
+
+### Added
+- remember_revise tool for syncing published memories
+- Multi-space publication support
+- Multi-group publication support
+- Revision history tracking
+- Orphaned memory support
+
+### Migration
+See [Migration Guide](docs/migration/v2-migration-guide.md)
+```
+
+---
+
+## Verification
+
+- [ ] API documentation complete and accurate
+- [ ] Migration guide clear and comprehensive
+- [ ] Architecture documentation explains design
+- [ ] Usage examples cover common scenarios
+- [ ] README updated
+- [ ] CHANGELOG entry created
+- [ ] All documentation reviewed for accuracy
+- [ ] Code examples tested and working
+
+---
+
+## Expected Output
+
+### Files Created
+- `docs/api/v2-tools.md` (~300 lines)
+- `docs/migration/v2-migration-guide.md` (~200 lines)
+- `docs/architecture/v2-architecture.md` (~250 lines)
+- `docs/examples/v2-usage-examples.md` (~200 lines)
+
+### Files Modified
+- `README.md` (updated for v2)
+- `CHANGELOG.md` (v2.0.0 entry added)
+
+---
+
+## Notes
+
+- Documentation should be clear and beginner-friendly
+- Examples should be practical and realistic
+- Migration guide critical for smooth transition
+- Consider creating video tutorial (future)
+- Keep documentation in sync with code changes
+
+---
+
+**Status**: Not Started
+**Next Milestone**: [Milestone 20: Memory Feed API Implementation](../../milestones/milestone-20-memory-feed-api.md)

package/agent/tasks/milestone-15-moderation-space-config/task-174-add-moderation-schema-fields.md

@@ -0,0 +1,57 @@
+# Task 174: Add Moderation Schema Fields
+
+**Milestone**: M15 - Moderation & Space Config
+**Estimated Hours**: 2-3
+**Dependencies**: None (builds on v3.9.0 foundations)
+**Status**: Not Started
+
+---
+
+## Objective
+
+Add moderation-related fields to the Weaviate published memory schema and the `can_moderate` permission to the GroupPermissions type.
+
+---
+
+## Steps
+
+### 1. Add schema fields to `src/schema/v2-collections.ts`
+
+Add to `PUBLISHED_MEMORY_PROPERTIES`:
+
+```typescript
+// Moderation
+{ name: 'moderation_status', dataType: configure.dataType.TEXT },
+{ name: 'moderated_by', dataType: configure.dataType.TEXT },
+{ name: 'moderated_at', dataType: configure.dataType.DATE },
+```
+
+Note: `moderation_flags` already exists in `COMMON_MEMORY_PROPERTIES` as TEXT_ARRAY.
+
+### 2. Add `can_moderate` to GroupPermissions in `src/types/auth.ts`
+
+```typescript
+export interface GroupPermissions {
+  // ... existing fields ...
+  can_moderate: boolean;
+}
+```
+
+### 3. Update StubCredentialsProvider if needed
+
+Ensure the stub doesn't break with the new permission field (it returns empty memberships, so no change needed).
+
+### 4. Add tests
+
+- Verify `getPublishedCollectionProperties()` includes the new fields
+- Verify GroupPermissions type includes `can_moderate`
+
+---
+
+## Verification
+
+- [ ] `moderation_status`, `moderated_by`, `moderated_at` in PUBLISHED_MEMORY_PROPERTIES
+- [ ] `can_moderate` in GroupPermissions interface
+- [ ] `npm run typecheck` passes
+- [ ] `npm test` passes
+- [ ] Existing tests unaffected

package/agent/tasks/milestone-15-moderation-space-config/task-175-create-space-config-service.md

@@ -0,0 +1,64 @@
+# Task 175: Create SpaceConfig Service
+
+**Milestone**: M15 - Moderation & Space Config
+**Estimated Hours**: 3-4
+**Dependencies**: None
+**Status**: Not Started
+
+---
+
+## Objective
+
+Create a Firestore-backed service for per-space/group behavioral configuration with sensible defaults.
+
+---
+
+## Steps
+
+### 1. Create `src/services/space-config.service.ts`
+
+```typescript
+export interface SpaceConfig {
+  require_moderation: boolean;
+  default_write_mode: WriteMode;
+}
+
+const DEFAULT_CONFIG: SpaceConfig = {
+  require_moderation: false,
+  default_write_mode: 'owner_only',
+};
+
+export async function getSpaceConfig(
+  id: string,
+  type: 'space' | 'group'
+): Promise<SpaceConfig>;
+
+export async function setSpaceConfig(
+  id: string,
+  type: 'space' | 'group',
+  config: Partial<SpaceConfig>
+): Promise<void>;
+```
+
+- Firestore path: `spaces/{spaceId}/config/settings` or `groups/{groupId}/config/settings`
+- Default fallback when no document exists
+- Partial updates via `setSpaceConfig`
+
+### 2. Create `src/services/space-config.service.spec.ts`
+
+Tests:
+- `getSpaceConfig` returns defaults when no Firestore doc exists
+- `getSpaceConfig` returns merged config when doc exists (partial override)
+- `setSpaceConfig` writes to correct Firestore path
+- Correct Firestore paths for spaces vs groups
+
+---
+
+## Verification
+
+- [ ] `getSpaceConfig()` returns defaults when no config exists
+- [ ] `getSpaceConfig()` merges partial config with defaults
+- [ ] `setSpaceConfig()` writes to Firestore
+- [ ] Space vs group paths are correct
+- [ ] `npm run typecheck` passes
+- [ ] `npm test` passes

package/agent/tasks/milestone-15-moderation-space-config/task-176-wire-moderation-publish-flow.md

@@ -0,0 +1,45 @@
+# Task 176: Wire Moderation into Publish Flow
+
+**Milestone**: M15 - Moderation & Space Config
+**Estimated Hours**: 3-4
+**Dependencies**: Task 174, Task 175
+**Status**: Not Started
+
+---
+
+## Objective
+
+Update the publish confirmation flow to set `moderation_status` on published memories based on space/group config.
+
+---
+
+## Steps
+
+### 1. Update `executePublishMemory()` in `src/tools/confirm.ts`
+
+In the publish execution handler:
+
+1. For each target space/group, read config via `getSpaceConfig()`
+2. If `require_moderation: true` -> set `moderation_status: 'pending'`
+3. If `require_moderation: false` (or no config) -> set `moderation_status: 'approved'`
+4. Set `moderated_by: null`, `moderated_at: null` (will be set by moderator later)
+
+### 2. Update the published memory properties written to Weaviate
+
+Ensure `moderation_status` is included in the properties object when creating the published copy.
+
+### 3. Update existing publish tests
+
+- Test publish to unmoderated space -> `moderation_status: 'approved'`
+- Test publish to moderated space -> `moderation_status: 'pending'`
+- Test publish to group with config -> correct status
+
+---
+
+## Verification
+
+- [ ] Unmoderated spaces: published memories get `moderation_status: 'approved'`
+- [ ] Moderated spaces: published memories get `moderation_status: 'pending'`
+- [ ] Default (no config): treated as unmoderated
+- [ ] `npm run typecheck` passes
+- [ ] `npm test` passes

package/agent/tasks/milestone-15-moderation-space-config/task-177-add-moderation-search-filters.md

@@ -0,0 +1,70 @@
+# Task 177: Add Moderation Filters to Search Tools
+
+**Milestone**: M15 - Moderation & Space Config
+**Estimated Hours**: 4-6
+**Dependencies**: Task 174
+**Status**: Not Started
+
+---
+
+## Objective
+
+Update `remember_search_space` and `remember_query_space` to filter by moderation_status, defaulting to approved/null for regular users and allowing moderators to see all statuses.
+
+---
+
+## Steps
+
+### 1. Update `src/tools/search-space.ts`
+
+Add `moderation_filter` parameter to tool definition:
+- Type: `'approved' | 'pending' | 'rejected' | 'removed' | 'all'`
+- Default: `'approved'`
+
+Build Weaviate filter:
+```typescript
+// Default: approved OR null (backward compat)
+const moderationFilter = Filters.or(
+  collection.filter.byProperty('moderation_status').equal('approved'),
+  collection.filter.byProperty('moderation_status').isNull(true)
+);
+```
+
+For non-approved filters, check `authContext` for `can_moderate` permission on the target group. Return error if not authorized.
+
+### 2. Update `src/tools/query-space.ts`
+
+Same logic as search-space — add `moderation_filter` parameter and permission check.
+
+### 3. Create permission check helper
+
+Create a helper function (possibly in `src/utils/` or inline) that checks if the user has `can_moderate` for a given group:
+
+```typescript
+function canModerate(authContext: AuthContext, groupId: string): boolean {
+  if (!authContext?.credentials) return false;
+  const membership = authContext.credentials.group_memberships
+    .find(m => m.group_id === groupId);
+  return membership?.permissions.can_moderate ?? false;
+}
+```
+
+### 4. Add tests
+
+- Default search returns only approved/null memories
+- `moderation_filter: 'pending'` with moderator returns pending
+- `moderation_filter: 'pending'` without moderator returns error
+- `moderation_filter: 'all'` with moderator returns all statuses
+- Null moderation_status treated as approved
+
+---
+
+## Verification
+
+- [ ] Default search excludes pending/rejected/removed memories
+- [ ] Null moderation_status memories visible in default search
+- [ ] Moderators can filter by any status
+- [ ] Non-moderators blocked from non-approved filters
+- [ ] Tool definitions include moderation_filter parameter
+- [ ] `npm run typecheck` passes
+- [ ] `npm test` passes

package/agent/tasks/milestone-15-moderation-space-config/task-178-create-remember-moderate-tool.md

@@ -0,0 +1,69 @@
+# Task 178: Create remember_moderate Tool
+
+**Milestone**: M15 - Moderation & Space Config
+**Estimated Hours**: 4-6
+**Dependencies**: Task 174, Task 177
+**Status**: Not Started
+
+---
+
+## Objective
+
+Create a new MCP tool (`remember_moderate`) that allows moderators to approve, reject, or remove published memories.
+
+---
+
+## Steps
+
+### 1. Create `src/tools/moderate.ts`
+
+Tool definition:
+```typescript
+export const moderateTool = {
+  name: 'remember_moderate',
+  description: 'Approve, reject, or remove a published memory (requires can_moderate permission)',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      memory_id: { type: 'string', description: 'UUID of published memory' },
+      space_id: { type: 'string', description: 'Space containing the memory (optional)' },
+      group_id: { type: 'string', description: 'Group containing the memory (optional)' },
+      action: { type: 'string', enum: ['approve', 'reject', 'remove'], description: 'Moderation action' },
+      reason: { type: 'string', description: 'Optional reason for the action' },
+    },
+    required: ['memory_id', 'action'],
+  },
+};
+```
+
+Handler:
+1. Check `authContext` for `can_moderate` permission on target group
+2. Look up the memory in the target collection
+3. Update `moderation_status`, `moderated_by` (userId), `moderated_at` (now)
+4. Return confirmation message
+
+### 2. Register in `src/server.ts` and `src/server-factory.ts`
+
+Add import, tool definition to ListTools, and case in switch statement (20th tool).
+
+### 3. Create `src/tools/moderate.spec.ts`
+
+Tests:
+- Approve sets status to `approved`
+- Reject sets status to `rejected`
+- Remove sets status to `removed`
+- Non-moderator gets permission error
+- Missing memory returns error
+- Sets `moderated_by` and `moderated_at` correctly
+
+---
+
+## Verification
+
+- [ ] `remember_moderate` registered in both servers
+- [ ] approve/reject/remove actions work correctly
+- [ ] Permission check enforced via authContext
+- [ ] `moderated_by` and `moderated_at` set on action
+- [ ] Error handling for missing memory, bad permissions
+- [ ] `npm run typecheck` passes
+- [ ] `npm test` passes

package/agent/tasks/milestone-15-moderation-space-config/task-179-documentation-integration-tests.md

@@ -0,0 +1,58 @@
+# Task 179: Documentation and Integration Tests
+
+**Milestone**: M15 - Moderation & Space Config
+**Estimated Hours**: 2-3
+**Dependencies**: Tasks 174-178
+**Status**: Not Started
+
+---
+
+## Objective
+
+Update documentation, CHANGELOG, and create integration test scenarios for the moderation system.
+
+---
+
+## Steps
+
+### 1. Update CHANGELOG.md
+
+Add entry for the new version (likely v3.10.0 or v4.0.0 depending on scope):
+- New `remember_moderate` tool
+- Moderation status lifecycle
+- Per-space/group configuration
+- Search filter changes (default to approved)
+
+### 2. Update README.md
+
+- Add moderation workflow section
+- Update tool count (19 -> 20)
+- Add `remember_moderate` to tool listing
+
+### 3. Update design doc status
+
+Set `local.moderation-and-space-config.md` status to `Implemented`.
+
+### 4. Update progress.yaml
+
+- Mark M15 as completed
+- Add recent_work entry
+- Update implementation percentage
+
+### 5. Verify all tests pass
+
+- `npm run typecheck` — no type errors
+- `npm run build` — compiles without errors
+- `npm test` — all tests pass
+
+---
+
+## Verification
+
+- [ ] CHANGELOG.md has new version entry
+- [ ] README.md updated with moderation workflow and tool count
+- [ ] Design doc status set to Implemented
+- [ ] progress.yaml updated
+- [ ] `npm run typecheck` passes
+- [ ] `npm run build` passes
+- [ ] `npm test` passes

package/agent/tasks/milestone-16-ghost-system/task-187-ghost-config-firestore.md

@@ -0,0 +1,41 @@
+# Task 187: GhostConfig Firestore CRUD
+
+**Milestone**: M16 — Ghost System
+**Status**: not_started
+**Dependencies**: Task 180 (GhostConfig types — done)
+
+---
+
+## Objective
+
+Implement Firestore CRUD operations for GhostConfig, enabling users to enable/disable their ghost, set trust levels, and manage blocked users.
+
+## Deliverables
+
+### 1. Create `src/services/ghost-config.service.ts`
+
+- `getGhostConfig(ownerUserId: string): Promise<GhostConfig | null>` — read from Firestore
+- `setGhostConfig(ownerUserId: string, config: Partial<GhostConfig>): Promise<GhostConfig>` — upsert
+- `setUserTrust(ownerUserId: string, targetUserId: string, trustLevel: number): Promise<void>` — set per-user trust
+- `blockUser(ownerUserId: string, targetUserId: string): Promise<void>` — add to blocked_users
+- `unblockUser(ownerUserId: string, targetUserId: string): Promise<void>` — remove from blocked_users
+- `isGhostEnabled(ownerUserId: string): Promise<boolean>` — convenience check
+
+**Firestore path**: `users/{ownerUserId}/ghost_config` (single document)
+
+### 2. Wire into access-control.ts
+
+- Replace `StubGhostConfigProvider` with `FirestoreGhostConfigProvider` that uses the service
+- Keep `StubGhostConfigProvider` for tests
+
+### 3. Tests
+
+- `src/services/ghost-config.service.spec.ts` — unit tests with Firestore mocks
+
+## Acceptance Criteria
+
+- [ ] GhostConfig CRUD operations work against Firestore
+- [ ] Default values applied when config doesn't exist
+- [ ] Per-user trust overrides work
+- [ ] Blocked user management works
+- [ ] Tests pass

package/agent/tasks/milestone-16-ghost-system/task-188-trust-filter-integration.md

@@ -0,0 +1,44 @@
+# Task 188: Trust Filter Integration into Search/Query Tools
+
+**Milestone**: M16 — Ghost System
+**Status**: not_started
+**Dependencies**: Task 187 (GhostConfig Firestore), Task 182 (trust enforcement — done)
+
+---
+
+## Objective
+
+Wire trust enforcement into search and query tools so ghost conversations get trust-filtered results.
+
+## Deliverables
+
+### 1. Add `ghostContext` parameter to search/query handlers
+
+- `search-memory.ts` — accept optional `ghostContext: { ownerUserId, accessorUserId, accessorTrustLevel }`
+- `query-memory.ts` — same ghostContext parameter
+- When ghostContext present: apply `buildTrustFilter` to Weaviate query
+- When ghostContext absent: current self-access behavior (no change)
+
+### 2. Wire into server-factory.ts
+
+- Ghost context passed from agentbase.me via the tool call arguments
+- server-factory resolves ghost config and computes accessor trust level
+- Passes ghostContext to tool handlers
+
+### 3. Format results by trust level
+
+- When ghostContext present, run results through `formatMemoryForPrompt`
+- Self-access (no ghostContext) returns full content as before
+
+### 4. Tests
+
+- Trust-filtered search returns only accessible memories
+- Self-access unchanged
+- Format tiers work correctly
+
+## Acceptance Criteria
+
+- [ ] Ghost searches filter by trust_score <= accessorTrustLevel
+- [ ] Self-access unchanged (no regression)
+- [ ] Results formatted by trust tier
+- [ ] Tests pass