@prmichaelsen/remember-mcp 3.15.7 → 3.16.2

package/agent/tasks/milestone-20-unified-internal-memory-tools/task-213-update-server-factory-internal-context.md

@@ -0,0 +1,117 @@
+# Task 213: Update Server Factory — Replace ghostMode with InternalContext
+
+**Milestone**: M20 — Unified Internal Memory Tools
+**Status**: Not Started
+**Estimated Hours**: 3-5
+**Dependencies**: task-212
+
+---
+
+## Objective
+
+Rewire the server factory and auth context to replace the ad-hoc `ghostMode` pattern with the more stable and extensible `InternalContext` pattern. Ghost identity, type, and source information move into `InternalContext`. Trust and cross-user access context are folded into `InternalContext` as well, eliminating the separate `ghostMode` field.
+
+## Context
+
+Currently `ghostMode` on `AuthContext` bundles ghost identity (`owner_user_id`, `accessor_user_id`) with resolved trust context (`accessor_trust_level`). This was fine for user-only ghosts, but doesn't extend to space/group ghosts and creates a parallel path alongside the new `InternalContext`. Rather than maintaining both, we should absorb `ghostMode` into `InternalContext` and drop the old field.
+
+### Current ghostMode usage (7 files):
+
+| File | Usage |
+|------|-------|
+| `server-factory.ts` | Creates `ghostMode` from `extras.ghost_owner`, resolves trust level |
+| `types/auth.ts` | Defines `GhostModeContext` and `AuthContext.ghostMode` |
+| `search-memory.ts` | `ghostMode.owner_user_id` for cross-user search, `ghostMode.accessor_trust_level` for trust filter |
+| `query-memory.ts` | Same as search-memory |
+| `search-by.ts` | Same pattern, passes ghost context to core services |
+| `create-ghost-memory.ts` | `ghostMode.accessor_user_id` for tagging (will be deleted in task-217) |
+| Tests | Mock ghostMode in test fixtures |
+
+## Design Reference
+
+- [Unified Internal Memory Tools — Section 2: Server Context](../../design/local.unified-internal-memory-tools.md)
+
+## Steps
+
+1. **Expand `InternalContext`** in `src/types/auth.ts` to absorb ghostMode fields:
+   ```typescript
+   export interface InternalContext {
+     type: 'ghost' | 'agent';
+     ghost_type?: 'user' | 'space' | 'group';
+     ghost_space?: string;
+     ghost_group?: string;
+     // Absorbed from GhostModeContext:
+     owner_user_id?: string;       // ghost owner (user ghosts)
+     accessor_user_id: string;     // who is conversing
+     accessor_trust_level?: number; // resolved trust (ghost only)
+   }
+   ```
+
+2. **Remove `ghostMode`** from `AuthContext`:
+   ```typescript
+   export interface AuthContext {
+     accessToken: string | null;
+     credentials: UserCredentials | null;
+     internalContext?: InternalContext;
+     // ghostMode is gone
+   }
+   ```
+
+3. **Remove `GhostModeContext`** interface (or deprecate if referenced externally)
+
+4. **Update `server-factory.ts`**:
+   - Replace `ghostMode` construction with `internalContext` construction
+   - Move trust resolution into `internalContext` building:
+     ```typescript
+     const internalType = extras?.internal_type as string | undefined;
+     let internalContext: InternalContext | undefined;
+
+     if (internalType) {
+       const ghostOwner = extras?.ghost_owner as string | undefined;
+       let accessorTrustLevel: number | undefined;
+
+       if (internalType === 'ghost' && ghostOwner) {
+         const ghostConfig = await getGhostConfig(ghostOwner);
+         accessorTrustLevel = await resolveAccessorTrustLevel(ghostConfig, ghostOwner, userId);
+       }
+
+       internalContext = {
+         type: internalType as 'ghost' | 'agent',
+         ghost_type: extras?.ghost_type as 'user' | 'space' | 'group' | undefined,
+         ghost_space: extras?.ghost_space as string | undefined,
+         ghost_group: extras?.ghost_group as string | undefined,
+         owner_user_id: ghostOwner,
+         accessor_user_id: userId,
+         accessor_trust_level: accessorTrustLevel,
+       };
+     }
+
+     const authContext: AuthContext = { accessToken, credentials, internalContext };
+     ```
+
+5. **Update `search-memory.ts`** — replace `ghostMode` references:
+   - `ghostMode?.owner_user_id` → `internalContext?.owner_user_id`
+   - `ghostMode?.accessor_trust_level` → `internalContext?.accessor_trust_level`
+   - Cross-user search: `searchUserId = internalContext?.owner_user_id ?? userId`
+   - Trust filter: `buildTrustFilter(collection, internalContext.accessor_trust_level)`
+
+6. **Update `query-memory.ts`** — same pattern as search-memory
+
+7. **Update `search-by.ts`** — same pattern, update ghost context passed to core services
+
+8. **Update `e2e-helpers.ts`** — replace `ghostMode` test fixture with `internalContext`
+
+9. **Update test files** — `search-by.spec.ts`, `ghost-tools.spec.ts` mock structures
+
+## Verification
+
+- [ ] `GhostModeContext` removed (or deprecated)
+- [ ] `AuthContext.ghostMode` removed
+- [ ] `AuthContext.internalContext` contains all former ghostMode fields
+- [ ] `server-factory.ts` builds `internalContext` from headers, resolves trust level
+- [ ] `search-memory.ts` uses `internalContext` for cross-user search and trust filtering
+- [ ] `query-memory.ts` uses `internalContext` for cross-user search and trust filtering
+- [ ] `search-by.ts` uses `internalContext` for ghost context
+- [ ] No remaining references to `ghostMode` in src/ (except ghost tools being deleted in task-217)
+- [ ] TypeScript compiles without errors
+- [ ] All existing tests updated and passing

package/agent/tasks/milestone-20-unified-internal-memory-tools/task-214-create-tag-builder-utility.md

@@ -0,0 +1,50 @@
+# Task 214: Create Tag Builder Utility
+
+**Milestone**: M20 — Unified Internal Memory Tools
+**Status**: Not Started
+**Estimated Hours**: 2-3
+**Dependencies**: task-212
+
+---
+
+## Objective
+
+Create a `buildInternalTags` utility that produces the correct tags for ghost/agent memories based on `AuthContext`, implementing the ghost source isolation tag scheme.
+
+## Context
+
+Ghost source isolation requires different tag sets for different ghost types:
+- User ghost (alice): `['ghost', 'ghost_type:user', 'ghost_owner:user:alice']`
+- Space ghost (music-lovers): `['ghost', 'ghost_type:space', 'ghost_owner:space:music-lovers']`
+- Group ghost (band-mates): `['ghost', 'ghost_type:group', 'ghost_owner:group:band-mates']`
+- Agent: `['agent']`
+
+## Design Reference
+
+- [Unified Internal Memory Tools — Section 3: Tag Builder](../design/local.unified-internal-memory-tools.md)
+
+## Steps
+
+1. Create `src/utils/internal-tags.ts` with `buildInternalTags(authContext: AuthContext): string[]`
+
+2. Implement the tag builder per the design spec:
+   - If `internalContext.type === 'agent'`, return `['agent']`
+   - If `internalContext.type === 'ghost'`, return `['ghost']` + type-specific tags
+   - If no `internalContext`, return `[]`
+
+3. For ghost type tags (all fields now on `internalContext`):
+   - `'user'` → `ghost_type:user` + `ghost_owner:user:{internalContext.owner_user_id}`
+   - `'space'` → `ghost_type:space` + `ghost_owner:space:{internalContext.ghost_space}`
+   - `'group'` → `ghost_type:group` + `ghost_owner:group:{internalContext.ghost_group}`
+
+4. Export from utils module
+
+## Verification
+
+- [ ] `buildInternalTags` returns correct tags for each ghost type
+- [ ] `buildInternalTags` returns `['agent']` for agent context
+- [ ] `buildInternalTags` returns `[]` for no internal context
+- [ ] User ghost uses `internalContext.owner_user_id` for owner tag
+- [ ] Space ghost uses `internalContext.ghost_space` for owner tag
+- [ ] Group ghost uses `internalContext.ghost_group` for owner tag
+- [ ] Unit tests cover all tag permutations

package/agent/tasks/milestone-20-unified-internal-memory-tools/task-215-create-unified-internal-memory-tools.md

@@ -0,0 +1,65 @@
+# Task 215: Create Unified Internal Memory Tools
+
+**Milestone**: M20 — Unified Internal Memory Tools
+**Status**: Not Started
+**Estimated Hours**: 6-8
+**Dependencies**: task-212, task-213, task-214
+
+---
+
+## Objective
+
+Create 5 unified `remember_*_internal_memory` tools that replace the 5 standalone ghost tools. Behavior is driven by `AuthContext.internalContext` (populated from HTTP headers).
+
+## Context
+
+The existing ghost tools (`create-ghost-memory.ts`, `update-ghost-memory.ts`, `search-ghost-memory.ts`, `query-ghost-memory.ts`, `search-ghost-memory-by.ts`) hardcode ghost-specific behavior. The unified tools generalize this pattern so both ghost and agent memories use the same tool implementations, with behavior determined by the `InternalContext`.
+
+## Design Reference
+
+- [Unified Internal Memory Tools — Full Implementation section](../design/local.unified-internal-memory-tools.md)
+- Existing ghost tools in `src/tools/` for reference patterns
+
+## Steps
+
+1. Create `src/tools/create-internal-memory.ts`:
+   - Accept same params as `create-ghost-memory` but without ghost-specific hardcoding
+   - Read `internalContext` from `authContext` to determine `content_type` (`'ghost'` or `'agent'`)
+   - Use `buildInternalTags(authContext)` for auto-tags
+   - Error if no `internalContext` present: "Internal context required. X-Internal-Type header must be set."
+   - Write to accessor's collection (same as current ghost behavior)
+
+2. Create `src/tools/update-internal-memory.ts`:
+   - Same pattern: derive content_type and tags from `internalContext`
+   - Error without internal context
+
+3. Create `src/tools/search-internal-memory.ts`:
+   - Auto-scope search to current ghost source via `buildInternalTags` scope tags
+   - Filter by `content_type` matching `internalContext.type`
+   - No override allowed for scope tags
+
+4. Create `src/tools/query-internal-memory.ts`:
+   - Same auto-scoping as search
+   - RAG query within scoped ghost/agent memories
+
+5. Create `src/tools/search-internal-memory-by.ts`:
+   - Same auto-scoping
+   - Support all modes: byTime, byRating, byProperty, byBroad, byRandom, byDensity, byMood, bySignificance
+   - Copy mode definitions from existing `search-ghost-memory-by.ts`
+
+6. Register all 5 tools in `src/server-factory.ts` tool registration
+
+7. Use descriptive tool descriptions that explain the unified behavior:
+   - "Creates an internal memory (ghost observation or agent note) based on the current session context."
+   - Make clear these tools are for platform-internal use only
+
+## Verification
+
+- [ ] All 5 tools created and registered
+- [ ] Tools error when `internalContext` is missing
+- [ ] Ghost mode: creates memories with `content_type: 'ghost'` and source-specific tags
+- [ ] Agent mode: creates memories with `content_type: 'agent'` and `agent` tag
+- [ ] Search tools auto-scope to current ghost source
+- [ ] Search tools filter by correct content_type
+- [ ] All search modes (byTime, byRating, etc.) work for internal memories
+- [ ] TypeScript compiles without errors

package/agent/tasks/milestone-20-unified-internal-memory-tools/task-216-update-default-search-filters.md

@@ -0,0 +1,46 @@
+# Task 216: Update Default Search Filters for Agent Exclusion
+
+**Milestone**: M20 — Unified Internal Memory Tools
+**Status**: Not Started
+**Estimated Hours**: 2-3
+**Dependencies**: task-212
+
+---
+
+## Objective
+
+Update default search/query tools (`remember_search_memory`, `remember_query_memory`, `remember_search_by`) to exclude `agent` content type from results, matching the existing `ghost` exclusion pattern.
+
+## Context
+
+Default user searches already exclude `content_type: 'ghost'` so ghost memories don't appear in normal memory browsing. The same pattern must be applied to `content_type: 'agent'` so agent observations don't pollute user search results.
+
+## Design Reference
+
+- [Unified Internal Memory Tools — Section 5: Content Type](../design/local.unified-internal-memory-tools.md)
+
+## Steps
+
+1. Locate the existing ghost content_type exclusion filter in search tools (likely in `src/tools/search-memory.ts`, `query-memory.ts`, `search-by.ts`)
+
+2. Add `'agent'` to the exclusion list alongside `'ghost'`:
+   ```typescript
+   // Before: filter out ghost
+   types: excludeTypes(['ghost', 'comment', ...])
+   // After: filter out ghost AND agent
+   types: excludeTypes(['ghost', 'agent', 'comment', ...])
+   ```
+
+3. Also check `remember_search_space` and `remember_query_space` — agent memories should not appear in space searches either
+
+4. Verify that the internal memory tools (task-215) do NOT apply this exclusion (they explicitly filter FOR their content type)
+
+## Verification
+
+- [ ] `remember_search_memory` excludes `agent` content type
+- [ ] `remember_query_memory` excludes `agent` content type
+- [ ] `remember_search_by` excludes `agent` content type
+- [ ] Space search tools exclude `agent` content type
+- [ ] Internal memory tools still return `agent`/`ghost` results correctly
+- [ ] Existing ghost exclusion unchanged
+- [ ] Existing tests updated/pass

package/agent/tasks/milestone-20-unified-internal-memory-tools/task-217-delete-standalone-ghost-tools.md

@@ -0,0 +1,46 @@
+# Task 217: Delete Standalone Ghost Tools
+
+**Milestone**: M20 — Unified Internal Memory Tools
+**Status**: Not Started
+**Estimated Hours**: 1-2
+**Dependencies**: task-215
+
+---
+
+## Objective
+
+Delete the 5 standalone ghost memory tools, their test files, and all references in the server registration. Clean break — no aliases or backwards compatibility shims.
+
+## Context
+
+The unified internal memory tools (task-215) replace these entirely. Per design decision, existing ghost memories are acceptable to lose (no backfill). The ghost-config tool is NOT deleted — it's a separate concern.
+
+## Steps
+
+1. Delete tool files:
+   - `src/tools/create-ghost-memory.ts`
+   - `src/tools/update-ghost-memory.ts`
+   - `src/tools/search-ghost-memory.ts`
+   - `src/tools/query-ghost-memory.ts`
+   - `src/tools/search-ghost-memory-by.ts`
+
+2. Delete test files:
+   - `src/tools/ghost-tools.spec.ts`
+
+3. Remove ghost tool registrations from `src/server-factory.ts`:
+   - Remove imports
+   - Remove tool handler registrations
+
+4. Keep `src/tools/ghost-config.ts` and `src/tools/ghost-config.spec.ts` (separate concern)
+
+5. Update `agent/design/complete-tool-set.md` to remove ghost tools and add unified internal tools
+
+## Verification
+
+- [ ] 5 ghost tool files deleted
+- [ ] Ghost tool test file deleted
+- [ ] Ghost tool registrations removed from server-factory
+- [ ] `ghost-config.ts` preserved
+- [ ] No remaining imports of deleted ghost tool files
+- [ ] TypeScript compiles without errors
+- [ ] No dead code referencing deleted tools

package/agent/tasks/milestone-20-unified-internal-memory-tools/task-218-add-tests-unified-internal-tools.md

@@ -0,0 +1,66 @@
+# Task 218: Add Unit and Integration Tests
+
+**Milestone**: M20 — Unified Internal Memory Tools
+**Status**: Not Started
+**Estimated Hours**: 4-6
+**Dependencies**: task-214, task-215, task-216, task-217
+
+---
+
+## Objective
+
+Add comprehensive unit and integration tests for the unified internal memory tool suite, covering tag building, search auto-scoping, context validation, and ghost source isolation.
+
+## Context
+
+Tests must verify the core guarantees of the unified tool architecture: correct tagging per ghost/agent type, auto-scoping that prevents cross-ghost leakage, error behavior without internal context, and agent exclusion from default searches.
+
+## Design Reference
+
+- [Unified Internal Memory Tools — Testing Strategy](../design/local.unified-internal-memory-tools.md)
+
+## Steps
+
+### Unit Tests
+
+1. `src/utils/internal-tags.spec.ts` — Tag builder:
+   - Returns `['agent']` for agent context
+   - Returns correct tags for user ghost (ghost, ghost_type:user, ghost_owner:user:{id})
+   - Returns correct tags for space ghost (ghost, ghost_type:space, ghost_owner:space:{id})
+   - Returns correct tags for group ghost (ghost, ghost_type:group, ghost_owner:group:{id})
+   - Returns `[]` for no internal context
+
+2. `src/tools/internal-tools.spec.ts` — Unified tools:
+   - Create tool errors without internalContext
+   - Create tool sets content_type from internalContext.type
+   - Create tool applies buildInternalTags for auto-tags
+   - Search tool auto-scopes to current ghost source tags
+   - Search tool filters by correct content_type
+   - Update tool only updates matching content_type memories
+   - Query tool auto-scopes like search
+
+3. `src/tools/search-by.spec.ts` — Updated default filter tests:
+   - Verify `agent` content type excluded from default searches
+   - Verify existing `ghost` exclusion unchanged
+
+### Integration Tests (e2e)
+
+4. Ghost source isolation test:
+   - Create memory as alice's ghost → verify ghost_owner:user:alice tag
+   - Create memory as carol's ghost → verify ghost_owner:user:carol tag
+   - Search as alice's ghost → only sees alice's ghost memories
+   - Search as carol's ghost → only sees carol's ghost memories
+
+5. Agent isolation test:
+   - Create agent memory → verify content_type: 'agent' and agent tag
+   - Default search → does not return agent memories
+   - Internal search with agent context → returns agent memories
+
+## Verification
+
+- [ ] Tag builder unit tests pass for all permutations
+- [ ] Tool error behavior tested (no context → error)
+- [ ] Ghost source isolation verified (no cross-ghost leakage)
+- [ ] Agent exclusion from default search verified
+- [ ] All existing tests still pass
+- [ ] Test coverage adequate for new code

package/dist/e2e-helpers.d.ts

@@ -9,7 +9,7 @@ import type { AuthContext } from './types/auth.js';
 export declare function e2eUserId(prefix?: string): string;
 /** Simple AuthContext with no ghost mode */
 export declare function e2eAuthContext(): AuthContext;
-/** AuthContext with ghost mode for cross-user tests */
+/** AuthContext with ghost internal context for cross-user tests */
 export declare function e2eGhostAuthContext(ownerUserId: string, accessorUserId: string, trustLevel?: number): AuthContext;
 /** Initialize databases (idempotent — safe to call many times) */
 export declare function e2eInit(): Promise<void>;

package/dist/server-factory.d.ts

@@ -7,51 +7,27 @@ export interface ServerOptions {
     name?: string;
     version?: string;
     /**
-     * Ghost mode configuration. When set, the server operates in ghost mode:
-     * - Search/query tools search the ghost owner's collection
-     * - Trust filtering is applied based on the accessor's trust level
-     * - Trust level is resolved server-side from GhostConfig (Firestore)
+     * Internal context for ghost/agent sessions. When set, the server provides
+     * unified internal memory tools with behavior driven by the context type.
      *
-     * agentbase.me sets this when creating a ghost conversation server.
+     * Populated from platform HTTP headers via mcp-auth extras:
+     *   X-Internal-Type → type ('ghost' | 'agent')
+     *   X-Ghost-Owner   → owner_user_id
+     *   X-Ghost-Type    → ghost_type ('user' | 'space' | 'group')
+     *   X-Ghost-Space   → ghost_space
+     *   X-Ghost-Group   → ghost_group
+     *
+     * Trust level is resolved server-side from GhostConfig (Firestore).
      * The LLM never has access to set or override these values.
      */
-    ghostMode?: {
-        /** Ghost owner's user ID (whose memories to search) */
-        owner_user_id: string;
-        /** Accessor's user ID (who is chatting with the ghost) */
+    internalContext?: {
+        type: 'ghost' | 'agent';
+        ghost_type?: 'user' | 'space' | 'group';
+        ghost_space?: string;
+        ghost_group?: string;
+        owner_user_id?: string;
         accessor_user_id: string;
     };
 }
-/**
- * Create a server instance for a specific user/tenant
- *
- * This factory function is compatible with mcp-auth wrapping pattern.
- * It creates isolated server instances with no shared state.
- *
- * Note: Databases (Weaviate + Firestore) are initialized once globally on first call.
- *
- * @param accessToken - User's access token (reserved for future external APIs)
- * @param userId - User identifier for scoping operations
- * @param options - Optional server configuration
- * @returns Configured MCP Server instance (not connected to transport)
- *
- * @example
- * ```typescript
- * // Direct usage
- * const server = createServer('token', 'user123');
- * const transport = new StdioServerTransport();
- * await server.connect(transport);
- *
- * // With mcp-auth
- * import { wrapServer } from '@prmichaelsen/mcp-auth';
- * const wrapped = wrapServer({
- *   serverFactory: createServer,
- *   authProvider: new JWTAuthProvider({ ... }),
- *   tokenResolver: new APITokenResolver({ ... }),
- *   resourceType: 'remember',
- *   transport: { type: 'sse', port: 3000 }
- * });
- * ```
- */
-export declare function createServer(accessToken: string, userId: string, options?: ServerOptions): Promise<Server>;
+export declare function createServer(accessToken: string, userId: string, options?: ServerOptions | Record<string, string | string[] | undefined>): Promise<Server>;
 //# sourceMappingURL=server-factory.d.ts.map