@prmichaelsen/remember-mcp 3.15.7 → 3.16.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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).
 
+## [3.16.0] - 2026-03-08
+
+### Added
+
+- `normalizeOptions()` in server-factory — maps flat mcp-auth extras (`internal_type`, `ghost_owner`, etc.) into structured `ServerOptions.internalContext`
+- `createServer` now accepts either structured `ServerOptions` or flat `Record<string, string>` extras from mcp-auth
+
+### Changed
+
+- Replace `GhostModeContext` and `AuthContext.ghostMode` with unified `InternalContext` on `AuthContext.internalContext`
+- `InternalContext` supports ghost (user/space/group) and agent session types via platform HTTP headers
+- Server factory maps `X-Internal-Type`, `X-Ghost-Type`, `X-Ghost-Space`, `X-Ghost-Group` headers into `InternalContext`
+- Trust resolution moved into `InternalContext` construction (accessor_trust_level)
+- All search/query tools (`search-memory`, `query-memory`, `search-by`) rewired from `ghostMode` to `internalContext`
+
+### Removed
+
+- Delete 5 standalone ghost tool files (`create-ghost-memory`, `update-ghost-memory`, `search-ghost-memory`, `query-ghost-memory`, `search-ghost-memory-by`) and `ghost-tools.spec.ts` — replaced by unified `remember_*_internal_memory` tools
+- Remove ghost tool imports, tool list entries, and switch cases from server-factory
+
 ## [3.15.7] - 2026-03-07
 
 ### Changed

package/agent/design/local.unified-internal-memory-tools.md

@@ -0,0 +1,325 @@
+# Unified Internal Memory Tool Suite
+
+**Concept**: Replace separate ghost/agent tool suites with 5 unified `remember_*_internal_memory` tools whose behavior is driven by HTTP headers
+**Created**: 2026-03-07
+**Status**: Design Specification
+
+---
+
+## Overview
+
+This document describes the design for a unified internal memory tool suite that replaces separate ghost and agent tool implementations. Instead of maintaining 5 ghost tools + 5 agent tools (10 total), we define 5 `remember_*_internal_memory` tools whose behavior is determined by platform-sent HTTP headers (`X-Internal-Type`, `X-Ghost-Type`, etc.).
+
+The design also addresses ghost source isolation — the problem that a single user's collection can contain ghost memories from multiple distinct ghost conversations (different user ghosts, space ghosts, group ghosts), and these need to be distinguishable via tags.
+
+---
+
+## Problem Statement
+
+1. **Tool proliferation**: Ghost tools hardcode `content_type: 'ghost'` and ghost-specific tags. Adding an equivalent agent tool suite means 5 more tools (10 total), with significant code duplication.
+
+2. **Ghost source isolation**: A user's collection can hold ghost memories from multiple ghost conversations. Bob might talk to alice's ghost, carol's ghost, and the music-lovers space ghost — all producing `content_type: 'ghost'` memories in bob's collection. The current `ghost:{accessor_user_id}` tag is redundant (bob is always the accessor in his own collection) and doesn't distinguish which ghost the memory came from.
+
+3. **Agent memories needed**: AI agent observations need a parallel storage pattern (`content_type: 'agent'`) with similar create/search/query tools, excluded from default user searches.
+
+---
+
+## Solution
+
+### Unified Tools (5 replacing 10+)
+
+Five `remember_*_internal_memory` tools that derive their behavior from server-side context set via HTTP headers:
+
+| Tool | Purpose |
+|------|---------|
+| `remember_create_internal_memory` | Create ghost or agent memory |
+| `remember_update_internal_memory` | Update ghost or agent memory |
+| `remember_search_internal_memory` | Semantic search ghost or agent memories |
+| `remember_query_internal_memory` | Query ghost or agent memories |
+| `remember_search_internal_memory_by` | Structured browse/sort ghost or agent memories |
+
+The platform (agentbase.me) sends headers indicating the conversation context. The tools error if no internal context headers are present — they cannot be used as normal memory tools.
+
+### Ghost Source Isolation via Tags
+
+Each ghost memory gets tags identifying its source:
+
+| Ghost type | Tags |
+|------------|------|
+| 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` |
+
+The old `ghost:{accessor_user_id}` tag is dropped (redundant in accessor's own collection).
+
+### Ghost Memory Storage Model
+
+Ghost memories are always written to the **accessor's** (conversing user's) collection. When bob talks to alice's ghost, memories go in bob's collection. These are metadata for the ghost to understand how to interact with bob long-term. This applies uniformly to user ghosts, space ghosts, and group ghosts.
+
+---
+
+## Implementation
+
+### 1. Platform Headers
+
+The platform sends these headers based on conversation type:
+
+| Header | Values | Purpose |
+|--------|--------|---------|
+| `X-Internal-Type` | `ghost`, `agent` | Which internal content type (drives unified tool behavior) |
+| `X-Ghost-Owner` | `alice` (already exists) | Whose ghost (user ghosts) |
+| `X-Ghost-Type` | `user`, `space`, `group` | What kind of ghost (required, not inferred) |
+| `X-Ghost-Space` | `music-lovers` | Space ID (space ghosts only) |
+| `X-Ghost-Group` | `band-mates` | Group ID (group ghosts only) |
+
+Header combinations by conversation type:
+
+```
+# User ghost (bob talking to alice's ghost)
+X-Internal-Type: ghost
+X-Ghost-Owner: alice
+X-Ghost-Type: user
+
+# Space ghost (bob talking to music-lovers space ghost)
+X-Internal-Type: ghost
+X-Ghost-Type: space
+X-Ghost-Space: music-lovers
+
+# Group ghost (bob talking to band-mates group ghost)
+X-Internal-Type: ghost
+X-Ghost-Type: group
+X-Ghost-Group: band-mates
+
+# Agent (bob's personal agent)
+X-Internal-Type: agent
+```
+
+### 2. Server Context
+
+`mcp-auth` extracts `X-*` headers into `extras` (snake_case). The server factory maps these into `InternalContext`:
+
+```typescript
+// types/auth.ts
+export interface InternalContext {
+  type: 'ghost' | 'agent';
+  ghost_type?: 'user' | 'space' | 'group';
+  ghost_space?: string;
+  ghost_group?: string;
+  // Absorbed from former GhostModeContext:
+  owner_user_id?: string;        // ghost owner (user ghosts)
+  accessor_user_id: string;      // who is conversing
+  accessor_trust_level?: number;  // resolved trust (ghost only)
+}
+
+export interface AuthContext {
+  accessToken: string | null;
+  credentials: UserCredentials | null;
+  internalContext?: InternalContext;
+  // ghostMode is removed — absorbed into internalContext
+}
+```
+
+Server factory mapping (ghostMode removed — all context on internalContext):
+
+```typescript
+serverFactory: async (accessToken, userId, extras) => {
+  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,
+    };
+  }
+
+  return await createRememberServer(accessToken, userId, { internalContext });
+},
+```
+
+### 3. Tag Builder
+
+```typescript
+function buildInternalTags(authContext: AuthContext): string[] {
+  const ctx = authContext.internalContext;
+  if (!ctx) return [];
+
+  if (ctx.type === 'agent') {
+    return ['agent'];
+  }
+
+  const tags = ['ghost'];
+
+  switch (ctx.ghost_type) {
+    case 'user':
+      tags.push('ghost_type:user');
+      if (ctx.owner_user_id) {
+        tags.push(`ghost_owner:user:${ctx.owner_user_id}`);
+      }
+      break;
+    case 'space':
+      tags.push('ghost_type:space');
+      if (ctx.ghost_space) {
+        tags.push(`ghost_owner:space:${ctx.ghost_space}`);
+      }
+      break;
+    case 'group':
+      tags.push('ghost_type:group');
+      if (ctx.ghost_group) {
+        tags.push(`ghost_owner:group:${ctx.ghost_group}`);
+      }
+      break;
+  }
+
+  return tags;
+}
+```
+
+### 4. Search Auto-Scoping
+
+Search tools auto-scope to the current ghost source via headers. When alice's ghost searches bob's collection, it auto-filters to `ghost_owner:user:alice` — it cannot see memories from carol's ghost or space ghosts. No override is allowed.
+
+```typescript
+// In search/query handlers
+const ctx = authContext.internalContext;
+if (!ctx) {
+  throw new Error('Internal context required. X-Internal-Type header must be set.');
+}
+
+const typeTags = buildInternalTags(authContext);
+const scopeTags = typeTags.filter(t => t !== 'ghost' && t !== 'agent');
+
+const filters = {
+  ...args.filters,
+  types: [ctx.type],
+  tags: [...(args.filters?.tags ?? []), ...scopeTags],
+};
+```
+
+### 5. Content Type
+
+- `'agent'` must be added to the `ContentType` enum in remember-core
+- Default searches (`remember_search_memory`, etc.) must exclude both `ghost` and `agent` content types
+
+### 6. Agent Auto-Tags
+
+Agent memories get the `agent` tag. An optional `agent:conversation:{conversationId}` tag is supported for future session isolation but not actively used yet.
+
+---
+
+## Benefits
+
+- **Fewer tools**: 5 tools instead of 10+, reducing LLM tool choice complexity
+- **Context-driven**: Platform determines behavior via headers — LLM can't pick wrong type
+- **Ghost isolation**: Tags distinguish memories from different ghost conversations
+- **Extensible**: New internal types can be added via headers without new tool suites
+- **Consistent**: Ghost and agent memories follow same create/search/query pattern
+
+---
+
+## Trade-offs
+
+- **Implicit behavior**: Tool behavior changes based on headers, not visible in tool schema. Mitigated by tools erroring without headers.
+- **Header dependency**: Platform must send correct headers. Mitigated by non-blocking rollout — platform updates in parallel.
+- **Lost legacy data**: Existing ghost memories lack new source tags and won't be backfilled. Acceptable given minimal existing data.
+
+---
+
+## Dependencies
+
+- **remember-core**: Add `'agent'` to `ContentType` enum
+- **remember-mcp-server**: Map new headers into `InternalContext` on `ServerOptions`
+- **agentbase.me (platform)**: Send `X-Internal-Type`, `X-Ghost-Type`, `X-Ghost-Space`, `X-Ghost-Group` headers
+- **mcp-auth**: Already supports `X-*` header extraction (no changes needed)
+
+---
+
+## Testing Strategy
+
+- **Unit tests**: Tag builder produces correct tags for each ghost type and agent
+- **Unit tests**: Search auto-scoping applies correct filters
+- **Unit tests**: Tools error when no `internalContext` is present
+- **Integration tests**: End-to-end create → search with ghost source isolation (alice's ghost memories don't leak into carol's ghost searches)
+- **Integration tests**: Default search tools exclude `agent` and `ghost` content types
+
+---
+
+## Migration Path
+
+1. Add `InternalContext` to `AuthContext` and `ServerOptions` in remember-mcp
+2. Add `'agent'` to `ContentType` enum in remember-core
+3. Create 5 unified `remember_*_internal_memory` tools
+4. Delete existing 5 standalone ghost tools
+5. Update default search filters to exclude `agent` content type
+6. Platform starts sending new headers (`X-Internal-Type`, `X-Ghost-Type`, `X-Ghost-Space`, `X-Ghost-Group`)
+
+Steps 1-5 are remember-mcp changes. Step 6 is platform work done in parallel (non-blocking).
+
+---
+
+## Key Design Decisions
+
+### Ghost Memory Architecture
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Ghost memory collection target | Accessor's collection (always) | Ghost memories are metadata for understanding the conversation partner long-term |
+| Ghost source tag scheme | `ghost_owner:{type}:{id}` | Consistent pattern across user/space/group ghosts |
+| Drop `ghost:{accessor_user_id}` tag | Yes | Redundant — accessor is always the collection owner |
+| `X-Ghost-Type: user` requirement | Required (not inferred) | Clarity and future-proofing |
+| Search auto-scoping | Based on headers, no override | Each ghost only sees its own memories |
+
+### Tool Architecture
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Unified vs separate tools | Unified (5 tools, header-driven) | Fewer tools, context-driven, extensible |
+| No-context behavior | Error | Prevents misuse as normal memory tools |
+| Agent content_type | `'agent'` | Follows ghost pattern |
+| Exclude agent from default search | Yes | Matches ghost exclusion pattern |
+| Agent auto-tags | `agent` + optional `agent:conversation:{id}` | Simple now, extensible later |
+
+### Migration
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Existing ghost tools | Delete | Clean break, no aliases |
+| Existing ghost memories | No backfill (acceptable loss) | Minimal existing data |
+| Platform header rollout | Non-blocking | Platform ships headers in parallel |
+
+### Space & Group Ghosts
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Space ghost personality | Synthesized from published space memories | Represents the collective space identity |
+| Space ghost search scope | Space published memories + accessor's ghost memories | Published for knowledge, ghost memories for conversation continuity |
+| Group vs space ghost implementation | Same, different source tag | No meaningful behavioral difference |
+
+---
+
+## Future Considerations
+
+- **Conversation-level agent isolation**: `agent:conversation:{conversationId}` tag is reserved for future use
+- **Ghost memory backfill**: If needed later, existing ghost memories could be tagged based on `ghost:{userId}` → `ghost_owner:user:{userId}` mapping
+- **Space ghost persona configuration**: Currently synthesized from published memories; could become configurable via space settings
+- **Cross-ghost search**: Currently disallowed; could be enabled for admin/diagnostic purposes
+
+---
+
+**Status**: Design Specification
+**Recommendation**: Implement in remember-mcp and remember-core, coordinate with platform for header rollout
+**Related Documents**: [clarification-4-internal-memory-tool-suite.md](../clarifications/clarification-4-internal-memory-tool-suite.md), [tool-suite-refinement.draft.md](../drafts/tool-suite-refinement.draft.md), [local.ghost-persona-system.md](local.ghost-persona-system.md)

package/agent/milestones/milestone-20-unified-internal-memory-tools.md

@@ -0,0 +1,58 @@
+# Milestone 20: Unified Internal Memory Tools
+
+**Goal**: Replace separate ghost/agent tool suites with 5 unified `remember_*_internal_memory` tools driven by HTTP headers, with ghost source isolation via `ghost_owner:{type}:{id}` tags
+
+**Started**: -
+**Status**: Not Started
+**Estimated Duration**: 1-2 weeks
+
+---
+
+## Overview
+
+Consolidate 5 standalone ghost tools + future agent tools into 5 unified internal memory tools. Behavior is determined by platform-sent HTTP headers (`X-Internal-Type`, `X-Ghost-Type`, etc.), not by which tool is called. Ghost source isolation tags (`ghost_owner:user:alice`, `ghost_owner:space:music-lovers`) replace the redundant `ghost:{accessor_user_id}` tag.
+
+## Deliverables
+
+1. `InternalContext` type added to `AuthContext`
+2. `'agent'` content type added to remember-core
+3. Tag builder utility (`buildInternalTags`)
+4. Server factory header mapping for new `X-*` headers
+5. 5 unified `remember_*_internal_memory` tools
+6. Existing 5 ghost tools deleted
+7. Default search filters updated to exclude `agent` content type
+8. Unit + integration tests
+
+## Success Criteria
+
+- [ ] 5 unified tools registered and functional
+- [ ] Ghost memories tagged with `ghost_type:{type}` + `ghost_owner:{type}:{id}`
+- [ ] Agent memories tagged with `agent` and `content_type: 'agent'`
+- [ ] Search auto-scopes to current ghost source (no cross-ghost leakage)
+- [ ] Tools error when no `X-Internal-Type` header is present
+- [ ] Default user searches exclude both `ghost` and `agent` content types
+- [ ] Old ghost tools deleted (no aliases)
+- [ ] All existing tests pass, new tests cover unified tools
+
+## Tasks
+
+| ID | Name | Est. Hours | Status |
+|----|------|-----------|--------|
+| task-212 | Add InternalContext type and agent content type | 2-3 | not_started |
+| task-213 | Update server factory for internal context headers | 2-3 | not_started |
+| task-214 | Create tag builder utility | 2-3 | not_started |
+| task-215 | Create unified internal memory tools | 6-8 | not_started |
+| task-216 | Update default search filters for agent exclusion | 2-3 | not_started |
+| task-217 | Delete standalone ghost tools | 1-2 | not_started |
+| task-218 | Add unit and integration tests | 4-6 | not_started |
+
+## Dependencies
+
+- remember-core: Add `'agent'` to `ContentType` enum (may need core PR)
+- Platform (agentbase.me): Send new headers (non-blocking, parallel work)
+
+## Design Reference
+
+- [Unified Internal Memory Tools](../design/local.unified-internal-memory-tools.md)
+- [Ghost Persona System](../design/local.ghost-persona-system.md)
+- [Clarification 4](../clarifications/clarification-4-internal-memory-tool-suite.md)

package/agent/progress.yaml

@@ -5,7 +5,7 @@ project:
   version: 3.15.4
   started: 2026-02-11
   status: in_progress
-  current_milestone: M18
+  current_milestone: M20
   last_updated: 2026-03-07
 
 milestones:
@@ -366,6 +366,21 @@ milestones:
       See: agent/milestones/milestone-19-new-search-ghost-tools.md
       Design: remember-core/agent/design/local.new-search-tools.md (authoritative)
 
+  - id: M20
+    name: Unified Internal Memory Tools
+    status: in_progress
+    progress: 100%
+    status: completed
+    estimated_weeks: 1-2
+    tasks_completed: 7
+    tasks_total: 7
+    notes: |
+      Replace 5 standalone ghost tools + future agent tools with 5 unified
+      remember_*_internal_memory tools. Header-driven behavior via X-Internal-Type.
+      Ghost source isolation via ghost_owner:{type}:{id} tags.
+      See: agent/milestones/milestone-20-unified-internal-memory-tools.md
+      Design: agent/design/local.unified-internal-memory-tools.md
+
 tasks:
   milestone_1:
     - id: task-1
@@ -2294,3 +2309,102 @@ task_20_completion:
       completed_date: null
       notes: |
         API docs, architecture docs, usage examples.
+
+  milestone_20:
+    - id: task-212
+      name: Add InternalContext Type and Agent Content Type
+      status: completed
+      file: agent/tasks/milestone-20-unified-internal-memory-tools/task-212-add-internal-context-type.md
+      estimated_hours: 2-3
+      actual_hours: null
+      completed_date: 2026-03-08
+      notes: |
+        ✅ InternalContext interface added to types/auth.ts
+        ✅ GhostModeContext removed, fields absorbed into InternalContext
+        ✅ AuthContext.ghostMode replaced by AuthContext.internalContext
+
+    - id: task-213
+      name: Update Server Factory — Replace ghostMode with InternalContext
+      status: completed
+      file: agent/tasks/milestone-20-unified-internal-memory-tools/task-213-update-server-factory-internal-context.md
+      estimated_hours: 3-5
+      actual_hours: null
+      completed_date: 2026-03-08
+      dependencies: [task-212]
+      notes: |
+        ✅ server-factory.ts: ghostMode → internalContext with trust resolution
+        ✅ search-memory.ts, query-memory.ts, search-by.ts: rewired to internalContext
+        ✅ e2e-helpers.ts: updated ghost auth context
+        ✅ All test fixtures updated, 439 tests passing, TypeScript clean
+
+    - id: task-214
+      name: Create Tag Builder Utility
+      status: completed
+      file: agent/tasks/milestone-20-unified-internal-memory-tools/task-214-create-tag-builder-utility.md
+      estimated_hours: 2-3
+      actual_hours: null
+      completed_date: 2026-03-08
+      dependencies: [task-212]
+      notes: |
+        ✅ buildInternalTags utility in src/utils/internal-tags.ts
+        ✅ 8 unit tests covering all tag permutations
+
+    - id: task-215
+      name: Create Unified Internal Memory Tools
+      status: completed
+      file: agent/tasks/milestone-20-unified-internal-memory-tools/task-215-create-unified-internal-memory-tools.md
+      estimated_hours: 6-8
+      actual_hours: null
+      completed_date: 2026-03-08
+      dependencies: [task-212, task-213, task-214]
+      notes: |
+        ✅ 5 unified tools: create, update, search, query, search-by
+        ✅ Auto-tags via buildInternalTags, auto-scoping via scope tags
+        ✅ Error without internalContext
+        ✅ Registered in server-factory (34 tools total)
+        ✅ 447 tests passing, TypeScript clean
+
+    - id: task-216
+      name: Update Default Search Filters for Agent Exclusion
+      status: completed
+      file: agent/tasks/milestone-20-unified-internal-memory-tools/task-216-update-default-search-filters.md
+      estimated_hours: 2-3
+      actual_hours: null
+      completed_date: 2026-03-08
+      dependencies: [task-212]
+      notes: |
+        ✅ search-memory, query-memory: agent excluded alongside ghost
+        ✅ find-similar: post-filter excludes agent
+        ✅ search-space: agent excluded from space searches
+        ✅ 447 tests passing
+
+    - id: task-217
+      name: Delete Standalone Ghost Tools
+      status: completed
+      file: agent/tasks/milestone-20-unified-internal-memory-tools/task-217-delete-standalone-ghost-tools.md
+      estimated_hours: 1-2
+      actual_hours: 1
+      completed_date: '2026-03-08'
+      dependencies: [task-215]
+      notes: |
+        ✅ Deleted 5 ghost tool files + ghost-tools.spec.ts
+        ✅ Removed imports, tool list entries, and switch cases from server-factory
+        ✅ Rewrote ghost-persona.e2e.ts to use unified internal tools
+        ✅ Updated tag assertions for ghost source isolation
+        ✅ TypeScript compiles clean, 414 tests pass
+
+    - id: task-218
+      name: Add Unit and Integration Tests
+      status: completed
+      file: agent/tasks/milestone-20-unified-internal-memory-tools/task-218-add-tests-unified-internal-tools.md
+      estimated_hours: 4-6
+      actual_hours: 1
+      completed_date: '2026-03-08'
+      dependencies: [task-214, task-215, task-216, task-217]
+      notes: |
+        ✅ 8 tag builder unit tests (task-214, internal-tags.spec.ts)
+        ✅ 22 unified tool unit tests (internal-tools.spec.ts)
+        ✅ Context validation, content_type derivation, auto-scoping, tag merging
+        ✅ Ghost source isolation verified (scope tags filter per ghost type)
+        ✅ Agent exclusion from default search verified (task-216)
+        ✅ 436 total tests passing

package/agent/tasks/milestone-20-unified-internal-memory-tools/task-212-add-internal-context-type.md

@@ -0,0 +1,54 @@
+# Task 212: Add InternalContext Type and Agent Content Type
+
+**Milestone**: M20 — Unified Internal Memory Tools
+**Status**: Not Started
+**Estimated Hours**: 2-3
+**Dependencies**: None
+
+---
+
+## Objective
+
+Add the `InternalContext` interface to `src/types/auth.ts` and add `'agent'` to the `ContentType` enum in remember-core. These are foundational types required by all subsequent tasks.
+
+## Context
+
+The unified internal tool suite needs a server-side context object (`InternalContext`) that captures header-derived information about whether the current session is ghost or agent, and what type of ghost. The `'agent'` content type parallels the existing `'ghost'` content type.
+
+## Design Reference
+
+- [Unified Internal Memory Tools — Section 2: Server Context](../design/local.unified-internal-memory-tools.md)
+
+## Steps
+
+1. Add `InternalContext` interface to `src/types/auth.ts` (absorbs all former `GhostModeContext` fields):
+   ```typescript
+   export interface InternalContext {
+     type: 'ghost' | 'agent';
+     ghost_type?: 'user' | 'space' | 'group';
+     ghost_space?: string;
+     ghost_group?: string;
+     owner_user_id?: string;        // ghost owner (user ghosts)
+     accessor_user_id: string;      // who is conversing
+     accessor_trust_level?: number;  // resolved trust (ghost only)
+   }
+   ```
+
+2. Replace `ghostMode?: GhostModeContext` with `internalContext?: InternalContext` on `AuthContext`
+
+3. Remove `GhostModeContext` interface (superseded by `InternalContext`)
+
+4. Add `'agent'` to the `ContentType` enum/type in remember-core:
+   - If remember-core owns the enum, submit a PR to remember-core
+   - If remember-mcp extends it locally, add it to the local extension
+
+5. Export `InternalContext` from the types module
+
+## Verification
+
+- [ ] `InternalContext` interface exists in `src/types/auth.ts` with all absorbed ghostMode fields
+- [ ] `GhostModeContext` removed
+- [ ] `AuthContext.ghostMode` replaced by `AuthContext.internalContext`
+- [ ] `'agent'` is a valid `ContentType` value
+- [ ] TypeScript compiles without errors
+- [ ] Existing tests still pass (no breaking changes)