@prmichaelsen/remember-mcp 3.15.4 → 3.15.6

package/src/server-factory.ts

@@ -44,6 +44,18 @@ import { searchSpaceTool, handleSearchSpace } from './tools/search-space.js';
 import { querySpaceTool, handleQuerySpace } from './tools/query-space.js';
 import { moderateTool, handleModerate } from './tools/moderate.js';
 import { ghostConfigTool, handleGhostConfig } from './tools/ghost-config.js';
+import { searchByTool, handleSearchBy } from './tools/search-by.js';
+
+// Import ghost memory tools
+import { createGhostMemoryTool, handleCreateGhostMemory } from './tools/create-ghost-memory.js';
+import { updateGhostMemoryTool, handleUpdateGhostMemory } from './tools/update-ghost-memory.js';
+import { searchGhostMemoryTool, handleSearchGhostMemory } from './tools/search-ghost-memory.js';
+import { queryGhostMemoryTool, handleQueryGhostMemory } from './tools/query-ghost-memory.js';
+import { searchGhostMemoryByTool, handleSearchGhostMemoryBy } from './tools/search-ghost-memory-by.js';
+
+// Import core introspection tools
+import { getCoreTool, handleGetCore } from './tools/get-core.js';
+import { searchSpaceByTool, handleSearchSpaceBy } from './tools/search-space-by.js';
 
 // Import services (static — avoids dynamic import overhead on hot path)
 import { getGhostConfig } from './services/ghost-config.service.js';
@@ -237,6 +249,18 @@ function registerHandlers(
         querySpaceTool,
         moderateTool,
         ghostConfigTool,
+        // Search modes
+        searchByTool,
+        // Ghost memory tools
+        createGhostMemoryTool,
+        updateGhostMemoryTool,
+        searchGhostMemoryTool,
+        queryGhostMemoryTool,
+        searchGhostMemoryByTool,
+        // Core introspection
+        getCoreTool,
+        // Space search modes
+        searchSpaceByTool,
       ],
     };
   });
@@ -337,6 +361,38 @@ function registerHandlers(
           result = await handleGhostConfig(args as any, userId, authContext);
           break;
 
+        case 'remember_search_by':
+          result = await handleSearchBy(args as any, userId, authContext);
+          break;
+
+        case 'remember_create_ghost_memory':
+          result = await handleCreateGhostMemory(args as any, userId, authContext);
+          break;
+
+        case 'remember_update_ghost_memory':
+          result = await handleUpdateGhostMemory(args as any, userId, authContext);
+          break;
+
+        case 'remember_search_ghost_memory':
+          result = await handleSearchGhostMemory(args as any, userId, authContext);
+          break;
+
+        case 'remember_query_ghost_memory':
+          result = await handleQueryGhostMemory(args as any, userId, authContext);
+          break;
+
+        case 'remember_search_ghost_memory_by':
+          result = await handleSearchGhostMemoryBy(args as any, userId, authContext);
+          break;
+
+        case 'remember_get_core':
+          result = await handleGetCore(args as any, userId, authContext);
+          break;
+
+        case 'remember_search_space_by':
+          result = await handleSearchSpaceBy(args as any, userId, authContext);
+          break;
+
         default:
           throw new McpError(
             ErrorCode.MethodNotFound,

package/src/shared-spaces.e2e.ts

@@ -0,0 +1,204 @@
+/**
+ * E2E: Shared Spaces — publish/confirm/deny/search/query/revise/retract
+ *
+ * Run with:
+ *   DOTENV_CONFIG_PATH=.env.e1.local npm run test:e2e -- --testPathPattern=shared-spaces
+ */
+
+import {
+  e2eInit, e2eUserId, e2eAuthContext, e2eEnsureCollection,
+  e2eCleanup, e2eDeleteCollection, parseResult, waitForIndex,
+} from './e2e-helpers.js';
+import { handleCreateMemory } from './tools/create-memory.js';
+import { handleUpdateMemory } from './tools/update-memory.js';
+import { handlePublish } from './tools/publish.js';
+import { handleConfirm } from './tools/confirm.js';
+import { handleDeny } from './tools/deny.js';
+import { handleSearchSpace } from './tools/search-space.js';
+import { handleQuerySpace } from './tools/query-space.js';
+import { handleRevise } from './tools/revise.js';
+import { handleRetract } from './tools/retract.js';
+
+const userId = e2eUserId('space');
+const auth = e2eAuthContext();
+const SPACE = 'the_void';
+const SPACE_COLLECTION = 'Memory_spaces_public';
+
+describe('E2E: Shared Spaces', () => {
+  let memoryId: string;
+  let publishToken: string;
+
+  beforeAll(async () => {
+    await e2eInit();
+    await e2eEnsureCollection(userId);
+
+    // Create a memory to publish
+    const res = parseResult(await handleCreateMemory(
+      { content: 'The best sourdough starter tip: feed with rye flour for extra tang.', weight: 0.8, tags: ['sourdough', 'baking', 'tips'] },
+      userId, auth,
+    ));
+    memoryId = res.memory_id;
+    await waitForIndex();
+  }, 30_000);
+
+  afterAll(async () => {
+    await e2eCleanup(userId);
+    // Note: we don't delete the shared space collection as other tests may use it
+  }, 30_000);
+
+  // -------------------------------------------------------------------------
+  // DENY flow (publish → deny)
+  // -------------------------------------------------------------------------
+
+  it('publishes a memory and then denies it', async () => {
+    const pubRes = parseResult(await handlePublish(
+      { memory_id: memoryId, spaces: [SPACE] },
+      userId, auth,
+    ));
+    expect(pubRes.success).toBe(true);
+    expect(pubRes.token).toBeTruthy();
+
+    const denyRes = parseResult(await handleDeny(
+      { token: pubRes.token },
+      userId, auth,
+    ));
+    expect(denyRes.success).toBe(true);
+    console.log('  denied publish');
+  });
+
+  // -------------------------------------------------------------------------
+  // PUBLISH + CONFIRM
+  // -------------------------------------------------------------------------
+
+  it('publishes a memory to the_void', async () => {
+    const res = parseResult(await handlePublish(
+      { memory_id: memoryId, spaces: [SPACE] },
+      userId, auth,
+    ));
+    expect(res.success).toBe(true);
+    publishToken = res.token;
+  });
+
+  it('confirms the publish', async () => {
+    const res = parseResult(await handleConfirm(
+      { token: publishToken },
+      userId, auth,
+    ));
+    expect(res.success).toBe(true);
+    expect(res.composite_id).toBeTruthy();
+    expect(res.published_to).toBeDefined();
+    console.log(`  published as ${res.composite_id}`);
+  });
+
+  // -------------------------------------------------------------------------
+  // SEARCH SPACE
+  // -------------------------------------------------------------------------
+
+  it('finds published memory via search_space', async () => {
+    await waitForIndex();
+
+    const res = parseResult(await handleSearchSpace(
+      { query: 'sourdough rye flour starter', spaces: [SPACE], limit: 10 },
+      userId, auth,
+    ));
+
+    expect(res.memories).toBeDefined();
+    expect(res.memories.length).toBeGreaterThan(0);
+    const contents = res.memories.map((m: any) => m.content || m.properties?.content);
+    const found = contents.some((c: string) => c && c.includes('sourdough'));
+    expect(found).toBe(true);
+    console.log(`  search_space returned ${res.memories.length} results`);
+  });
+
+  // -------------------------------------------------------------------------
+  // QUERY SPACE (RAG)
+  // -------------------------------------------------------------------------
+
+  it('query_space returns relevant results', async () => {
+    const res = parseResult(await handleQuerySpace(
+      { question: 'How do I make my sourdough more tangy?', spaces: [SPACE], limit: 5 },
+      userId, auth,
+    ));
+
+    expect(res.memories).toBeDefined();
+    expect(res.memories.length).toBeGreaterThan(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // REVISE
+  // -------------------------------------------------------------------------
+
+  it('updates source memory then revises published copies', async () => {
+    // Update the source memory
+    await handleUpdateMemory(
+      { memory_id: memoryId, content: 'The best sourdough starter tip: feed with rye flour for extra tang. Also, keep it at 78F for best activity.' },
+      userId, auth,
+    );
+    await waitForIndex();
+
+    // Request revise
+    const revRes = parseResult(await handleRevise(
+      { memory_id: memoryId },
+      userId, auth,
+    ));
+    expect(revRes.token).toBeTruthy();
+
+    // Confirm revise
+    const confirmRes = parseResult(await handleConfirm(
+      { token: revRes.token },
+      userId, auth,
+    ));
+    expect(confirmRes.success).toBe(true);
+    console.log('  revised published copy');
+  });
+
+  it('revised content appears in space search', async () => {
+    await waitForIndex();
+
+    const res = parseResult(await handleSearchSpace(
+      { query: 'sourdough 78F temperature activity', spaces: [SPACE], limit: 10 },
+      userId, auth,
+    ));
+
+    const found = res.memories.some((m: any) => {
+      const content = m.content || m.properties?.content || '';
+      return content.includes('78F');
+    });
+    expect(found).toBe(true);
+  });
+
+  // -------------------------------------------------------------------------
+  // RETRACT
+  // -------------------------------------------------------------------------
+
+  it('retracts the memory from the_void', async () => {
+    const retRes = parseResult(await handleRetract(
+      { memory_id: memoryId, spaces: [SPACE] },
+      userId, auth,
+    ));
+    expect(retRes.token).toBeTruthy();
+
+    const confirmRes = parseResult(await handleConfirm(
+      { token: retRes.token },
+      userId, auth,
+    ));
+    expect(confirmRes.success).toBe(true);
+    console.log('  retracted from the_void');
+  });
+
+  it('retracted memory no longer appears in space search', async () => {
+    await waitForIndex();
+
+    const res = parseResult(await handleSearchSpace(
+      { query: 'sourdough rye flour starter', spaces: [SPACE], limit: 10 },
+      userId, auth,
+    ));
+
+    // Our specific memory should not be found (or the space may be empty)
+    const found = res.memories?.some((m: any) => {
+      const content = m.content || m.properties?.content || '';
+      return content.includes('sourdough') && content.includes('78F');
+    });
+    expect(found).toBeFalsy();
+  });
+});

package/src/tools/create-ghost-memory.ts

@@ -0,0 +1,103 @@
+/**
+ * remember_create_ghost_memory tool
+ * Creates a ghost memory with hardcoded content_type and ghost-specific tags
+ */
+
+import { handleToolError } from '../utils/error-handler.js';
+import { createDebugLogger } from '../utils/debug.js';
+import type { AuthContext } from '../types/auth.js';
+import { createCoreServices } from '../core-services.js';
+
+export const createGhostMemoryTool = {
+  name: 'remember_create_ghost_memory',
+  description: `Create a ghost memory (cross-user interaction record).
+
+  Ghost memories track what happened during ghost conversations — observations,
+  impressions, and insights about the accessor. Automatically sets content_type
+  to 'ghost' and adds ghost-specific tags.
+
+  Ghost memories are excluded from default searches. They are only visible when
+  explicitly searching with content_type: 'ghost' or using ghost memory tools.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      content: { type: 'string', description: 'Ghost memory content' },
+      title: { type: 'string', description: 'Optional title' },
+      tags: { type: 'array', items: { type: 'string' }, description: 'Additional tags (ghost-specific tags added automatically)' },
+      weight: { type: 'number', minimum: 0, maximum: 1, description: 'Significance (0-1)' },
+      trust: { type: 'number', minimum: 0, maximum: 1, description: 'Trust level (0-1)' },
+      feel_salience: { type: 'number', minimum: 0, maximum: 1, description: 'How unexpected/novel (0-1)' },
+      feel_social_weight: { type: 'number', minimum: 0, maximum: 1, description: 'Relationship/reputation impact (0-1)' },
+      feel_narrative_importance: { type: 'number', minimum: 0, maximum: 1, description: 'Story arc importance (0-1)' },
+    },
+    required: ['content'],
+  },
+};
+
+export interface CreateGhostMemoryArgs {
+  content: string;
+  title?: string;
+  tags?: string[];
+  weight?: number;
+  trust?: number;
+  [key: string]: any;
+}
+
+export async function handleCreateGhostMemory(
+  args: CreateGhostMemoryArgs,
+  userId: string,
+  authContext?: AuthContext
+): Promise<string> {
+  const debug = createDebugLogger({ tool: 'remember_create_ghost_memory', userId, operation: 'create ghost memory' });
+  try {
+    debug.info('Tool invoked');
+    debug.trace('Arguments', { args });
+
+    const { memory } = createCoreServices(userId);
+
+    // Build ghost-specific tags
+    const accessorUserId = authContext?.ghostMode?.accessor_user_id;
+    const ghostTags = ['ghost'];
+    if (accessorUserId) {
+      ghostTags.push(`ghost:${accessorUserId}`);
+    }
+
+    // Merge user tags with ghost tags (avoid duplicates)
+    const userTags = args.tags ?? [];
+    const mergedTags = [...new Set([...ghostTags, ...userTags])];
+
+    // Extract feel_* fields
+    const feelFields: Record<string, number> = {};
+    for (const [key, value] of Object.entries(args)) {
+      if (key.startsWith('feel_') && typeof value === 'number') {
+        feelFields[key] = value;
+      }
+    }
+
+    const result = await memory.create({
+      content: args.content,
+      title: args.title,
+      type: 'ghost' as any,
+      weight: args.weight,
+      trust: args.trust,
+      tags: mergedTags,
+      context_summary: 'Ghost memory created via MCP',
+      ...feelFields,
+    } as any);
+
+    return JSON.stringify({
+      memory_id: result.memory_id,
+      created_at: result.created_at,
+      content_type: 'ghost',
+      tags: mergedTags,
+      message: `Ghost memory created successfully with ID: ${result.memory_id}`,
+    }, null, 2);
+  } catch (error) {
+    debug.error('Tool failed', { error: error instanceof Error ? error.message : String(error) });
+    handleToolError(error, {
+      toolName: 'remember_create_ghost_memory',
+      operation: 'create ghost memory',
+      userId,
+    });
+  }
+}

package/src/tools/create-memory.ts

@@ -95,6 +95,38 @@ export const createMemoryTool = {
         description: 'Per-space moderation flags (format: "{space_id}:{flag_type}"). Usually empty.',
         default: [],
       },
+      // Emotional dimensions — create-time hints, REM re-scores authoritatively
+      // Layer 1: Discrete Emotions
+      feel_emotional_significance: { type: 'number', minimum: 0, maximum: 1, description: 'Overall emotional weight (0-1). REM re-scores.' },
+      feel_vulnerability: { type: 'number', minimum: 0, maximum: 1, description: 'Personal exposure/openness (0-1). REM re-scores.' },
+      feel_trauma: { type: 'number', minimum: 0, maximum: 1, description: 'Negative formative experience intensity (0-1). REM re-scores.' },
+      feel_humor: { type: 'number', minimum: 0, maximum: 1, description: 'Comedic/playful quality (0-1). REM re-scores.' },
+      feel_happiness: { type: 'number', minimum: 0, maximum: 1, description: 'Positive affect / joy (0-1). REM re-scores.' },
+      feel_sadness: { type: 'number', minimum: 0, maximum: 1, description: 'Negative affect / grief / loss (0-1). REM re-scores.' },
+      feel_fear: { type: 'number', minimum: 0, maximum: 1, description: 'Threat perception / anxiety (0-1). REM re-scores.' },
+      feel_anger: { type: 'number', minimum: 0, maximum: 1, description: 'Frustration / injustice (0-1). REM re-scores.' },
+      feel_surprise: { type: 'number', minimum: 0, maximum: 1, description: 'Unexpectedness / novelty (0-1). REM re-scores.' },
+      feel_disgust: { type: 'number', minimum: 0, maximum: 1, description: 'Aversion / rejection (0-1). REM re-scores.' },
+      feel_contempt: { type: 'number', minimum: 0, maximum: 1, description: 'Superiority / dismissal (0-1). REM re-scores.' },
+      feel_embarrassment: { type: 'number', minimum: 0, maximum: 1, description: 'Social discomfort (0-1). REM re-scores.' },
+      feel_shame: { type: 'number', minimum: 0, maximum: 1, description: 'Deep self-judgment (0-1). REM re-scores.' },
+      feel_guilt: { type: 'number', minimum: 0, maximum: 1, description: 'Responsibility for harm (0-1). REM re-scores.' },
+      feel_excitement: { type: 'number', minimum: 0, maximum: 1, description: 'Anticipatory positive arousal (0-1). REM re-scores.' },
+      feel_pride: { type: 'number', minimum: 0, maximum: 1, description: 'Accomplishment / self-evaluation (0-1). REM re-scores.' },
+      feel_valence: { type: 'number', minimum: -1, maximum: 1, description: 'Positive-negative spectrum (-1 to 1). REM re-scores.' },
+      feel_arousal: { type: 'number', minimum: 0, maximum: 1, description: 'Calm to excited (0-1). REM re-scores.' },
+      feel_dominance: { type: 'number', minimum: 0, maximum: 1, description: 'Control vs submission (0-1). REM re-scores.' },
+      feel_intensity: { type: 'number', minimum: 0, maximum: 1, description: 'Overall emotional magnitude (0-1). REM re-scores.' },
+      feel_coherence_tension: { type: 'number', minimum: 0, maximum: 1, description: 'Conflict with existing beliefs (0-1). REM re-scores.' },
+      // Layer 2: Functional Signals
+      feel_salience: { type: 'number', minimum: 0, maximum: 1, description: 'How unexpected/novel — prediction error (0-1). REM re-scores.' },
+      feel_urgency: { type: 'number', minimum: 0, maximum: 1, description: 'Time-sensitivity of relevance (0-1). REM re-scores.' },
+      feel_social_weight: { type: 'number', minimum: 0, maximum: 1, description: 'Relationship/reputation impact (0-1). REM re-scores.' },
+      feel_agency: { type: 'number', minimum: 0, maximum: 1, description: 'Caused by the bot\'s own actions? (0-1). REM re-scores.' },
+      feel_novelty: { type: 'number', minimum: 0, maximum: 1, description: 'Uniqueness relative to collection (0-1). REM re-scores.' },
+      feel_retrieval_utility: { type: 'number', minimum: 0, maximum: 1, description: 'Likelihood of future usefulness (0-1). REM re-scores.' },
+      feel_narrative_importance: { type: 'number', minimum: 0, maximum: 1, description: 'Advances/anchors a personal story arc (0-1). REM re-scores.' },
+      feel_aesthetic_quality: { type: 'number', minimum: 0, maximum: 1, description: 'Beauty, craft, artistry (0-1). REM re-scores.' },
     },
     required: ['content'],
   },
@@ -118,6 +150,8 @@ export interface CreateMemoryArgs {
   parent_id?: string | null;
   thread_root_id?: string | null;
   moderation_flags?: string[];
+  // Emotional dimensions (feel_* fields)
+  [key: string]: any;
 }
 
 /**
@@ -144,6 +178,15 @@ export async function handleCreateMemory(
     debug.trace('Arguments', { args });
 
     const { memory } = createCoreServices(userId);
+
+    // Extract feel_* fields from args
+    const feelFields: Record<string, number> = {};
+    for (const [key, value] of Object.entries(args)) {
+      if (key.startsWith('feel_') && typeof value === 'number') {
+        feelFields[key] = value;
+      }
+    }
+
     const result = await memory.create({
       content: args.content,
       title: args.title,
@@ -158,7 +201,8 @@ export async function handleCreateMemory(
       moderation_flags: args.moderation_flags,
       context_summary: context?.summary || 'Memory created via MCP',
       context_conversation_id: context?.conversation_id,
-    });
+      ...feelFields,
+    } as any);
 
     const response: CreateMemoryResult = {
       memory_id: result.memory_id,

package/src/tools/get-core.spec.ts

@@ -0,0 +1,223 @@
+import { getCoreTool, handleGetCore } from './get-core.js';
+
+const mockGetDocument = jest.fn();
+
+jest.mock('../firestore/init.js', () => ({
+  getDocument: (...args: any[]) => mockGetDocument(...args),
+}));
+
+jest.mock('../firestore/paths.js', () => ({
+  BASE: 'test-base',
+}));
+
+jest.mock('../utils/debug.js', () => ({
+  createDebugLogger: () => ({
+    info: jest.fn(),
+    trace: jest.fn(),
+    error: jest.fn(),
+  }),
+}));
+
+const mockMood = {
+  state: {
+    valence: 0.3,
+    arousal: 0.5,
+    confidence: 0.7,
+    social_warmth: 0.6,
+    coherence: 0.8,
+    trust: 0.65,
+  },
+  color: 'cautiously optimistic',
+  dominant_emotion: 'curious wariness',
+  reasoning: 'Recent interactions have been productive but uncertain',
+  motivation: 'understand user needs',
+  goal: 'build rapport',
+  purpose: 'be a helpful memory companion',
+  last_updated: '2026-03-07T12:00:00Z',
+  rem_cycles_since_shift: 3,
+  pressures: [
+    {
+      source_memory_id: 'mem-1',
+      dimension: 'valence',
+      magnitude: 0.2,
+      reason: 'positive feedback from user',
+      decay_rate: 0.1,
+    },
+  ],
+  threshold_flags: [],
+};
+
+const mockPerception = {
+  owner_id: 'user-1',
+  target_user_id: 'user-2',
+  personality_sketch: 'Curious and detail-oriented',
+  communication_style: 'Direct and concise',
+  emotional_baseline: 'Generally calm and focused',
+  interests: ['AI', 'music'],
+  patterns: ['asks follow-up questions'],
+  needs: ['quick answers'],
+  evolution_notes: ['became more trusting over time'],
+  confidence_level: 0.7,
+  last_updated: '2026-03-07T10:00:00Z',
+};
+
+describe('remember_get_core', () => {
+  const userId = 'test-user-1';
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('tool definition', () => {
+    it('has correct name', () => {
+      expect(getCoreTool.name).toBe('remember_get_core');
+    });
+
+    it('has no required parameters', () => {
+      expect((getCoreTool.inputSchema as any).required).toBeUndefined();
+    });
+
+    it('has include_pressures and include_perception properties', () => {
+      const props = getCoreTool.inputSchema.properties as any;
+      expect(props.include_pressures).toBeDefined();
+      expect(props.include_perception).toBeDefined();
+    });
+  });
+
+  describe('mood state', () => {
+    it('returns all 6 dimensions', async () => {
+      mockGetDocument.mockResolvedValue(mockMood);
+      const result = JSON.parse(await handleGetCore({}, userId));
+      expect(result.mood.state).toEqual(mockMood.state);
+    });
+
+    it('returns derived labels', async () => {
+      mockGetDocument.mockResolvedValue(mockMood);
+      const result = JSON.parse(await handleGetCore({}, userId));
+      expect(result.mood.color).toBe('cautiously optimistic');
+      expect(result.mood.dominant_emotion).toBe('curious wariness');
+      expect(result.mood.reasoning).toBeDefined();
+    });
+
+    it('returns directional state', async () => {
+      mockGetDocument.mockResolvedValue(mockMood);
+      const result = JSON.parse(await handleGetCore({}, userId));
+      expect(result.mood.motivation).toBe('understand user needs');
+      expect(result.mood.goal).toBe('build rapport');
+      expect(result.mood.purpose).toBe('be a helpful memory companion');
+    });
+
+    it('returns last_updated and rem_cycles_since_shift', async () => {
+      mockGetDocument.mockResolvedValue(mockMood);
+      const result = JSON.parse(await handleGetCore({}, userId));
+      expect(result.mood.last_updated).toBe('2026-03-07T12:00:00Z');
+      expect(result.mood.rem_cycles_since_shift).toBe(3);
+    });
+  });
+
+  describe('pressures', () => {
+    it('includes pressures by default', async () => {
+      mockGetDocument.mockResolvedValue(mockMood);
+      const result = JSON.parse(await handleGetCore({}, userId));
+      expect(result.mood.pressures).toHaveLength(1);
+      expect(result.mood.pressures[0].dimension).toBe('valence');
+    });
+
+    it('excludes pressures when include_pressures is false', async () => {
+      mockGetDocument.mockResolvedValue(mockMood);
+      const result = JSON.parse(await handleGetCore({ include_pressures: false }, userId));
+      expect(result.mood.pressures).toBeUndefined();
+    });
+  });
+
+  describe('threshold flags', () => {
+    it('omits threshold_flags when empty', async () => {
+      mockGetDocument.mockResolvedValue(mockMood);
+      const result = JSON.parse(await handleGetCore({}, userId));
+      expect(result.mood.threshold_flags).toBeUndefined();
+    });
+
+    it('includes threshold_flags when active', async () => {
+      mockGetDocument.mockResolvedValue({
+        ...mockMood,
+        threshold_flags: ['trust_crisis', 'isolation'],
+      });
+      const result = JSON.parse(await handleGetCore({}, userId));
+      expect(result.mood.threshold_flags).toEqual(['trust_crisis', 'isolation']);
+    });
+  });
+
+  describe('missing mood', () => {
+    it('returns null mood with message when no mood doc exists', async () => {
+      mockGetDocument.mockResolvedValue(null);
+      const result = JSON.parse(await handleGetCore({}, userId));
+      expect(result.mood).toBeNull();
+      expect(result.message).toContain('No mood state found');
+    });
+  });
+
+  describe('perception', () => {
+    it('omits perception when include_perception not provided', async () => {
+      mockGetDocument.mockResolvedValue(mockMood);
+      const result = JSON.parse(await handleGetCore({}, userId));
+      expect(result.perception).toBeUndefined();
+    });
+
+    it('includes perception when include_perception provided', async () => {
+      mockGetDocument
+        .mockResolvedValueOnce(mockMood) // mood doc
+        .mockResolvedValueOnce(mockPerception); // perception doc
+      const result = JSON.parse(
+        await handleGetCore({ include_perception: 'user-2' }, userId),
+      );
+      expect(result.perception).toBeDefined();
+      expect(result.perception.personality_sketch).toBe('Curious and detail-oriented');
+    });
+
+    it('reads perception from correct Firestore path', async () => {
+      mockGetDocument
+        .mockResolvedValueOnce(mockMood)
+        .mockResolvedValueOnce(mockPerception);
+      await handleGetCore({ include_perception: 'user-2' }, userId);
+      expect(mockGetDocument).toHaveBeenCalledWith(
+        'test-base.users/test-user-1/core/perceptions',
+        'user-2',
+      );
+    });
+
+    it('omits perception when doc not found', async () => {
+      mockGetDocument
+        .mockResolvedValueOnce(mockMood)
+        .mockResolvedValueOnce(null);
+      const result = JSON.parse(
+        await handleGetCore({ include_perception: 'unknown-user' }, userId),
+      );
+      expect(result.perception).toBeUndefined();
+    });
+
+    it('supports self-perception (include_perception = own user_id)', async () => {
+      mockGetDocument
+        .mockResolvedValueOnce(mockMood)
+        .mockResolvedValueOnce({ ...mockPerception, target_user_id: userId });
+      const result = JSON.parse(
+        await handleGetCore({ include_perception: userId }, userId),
+      );
+      expect(result.perception).toBeDefined();
+      expect(mockGetDocument).toHaveBeenCalledWith(
+        'test-base.users/test-user-1/core/perceptions',
+        userId,
+      );
+    });
+  });
+
+  describe('Firestore path', () => {
+    it('reads mood from correct path', async () => {
+      mockGetDocument.mockResolvedValue(null);
+      await handleGetCore({}, userId);
+      expect(mockGetDocument).toHaveBeenCalledWith(
+        'test-base.users/test-user-1/core',
+        'mood',
+      );
+    });
+  });
+});