@prmichaelsen/remember-mcp 3.15.4 → 3.15.6

package/agent/tasks/milestone-19-new-search-ghost-tools/task-207-add-emotional-composites-search-results.md

@@ -0,0 +1,88 @@
+# Task 207: Add Emotional Composites + REM Metadata to Search Results
+
+**Milestone**: M19 — New Search Modes, Ghost Tools & Emotional Exposure
+**Status**: Not Started
+**Created**: 2026-03-07
+**Estimated Hours**: 2-3
+**Dependencies**: remember-core schema with composite scores and REM metadata
+
+---
+
+## Objective
+
+Include emotional composite scores (`total_significance`, `feel_significance`, `functional_significance`) and REM metadata (`rem_touched_at`, `rem_visits`) in search result objects across all search tools.
+
+## Context
+
+When REM has scored memories, the composite significance scores and REM visit metadata are stored in Weaviate. These should be included in search results so the LLM and downstream tools have emotional context. Not all memories will have been scored — unscored fields must be omitted (not returned as null).
+
+## Fields to Include
+
+```typescript
+// Added to search result memory objects (when non-null):
+{
+  // ... existing fields (memory_id, title, content, content_type, tags, weight, trust, created_at, etc.) ...
+
+  // Composite scores (computed by REM, 0-1 floats)
+  total_significance?: number;       // Combined emotional + functional significance
+  feel_significance?: number;        // Weighted sum of Layer 1 (21 discrete emotions)
+  functional_significance?: number;  // Weighted sum of Layer 2 (10 functional signals)
+
+  // REM metadata
+  rem_touched_at?: string;           // ISO timestamp of last REM scoring update
+  rem_visits?: number;               // Number of REM scoring visits
+}
+```
+
+## Tools to Update
+
+| Tool File | Function | Notes |
+|-----------|----------|-------|
+| `src/tools/search-memory.ts` | Result serialization | Add composites to each memory result |
+| `src/tools/find-similar.ts` | Result serialization | Add composites to each memory result |
+| `src/tools/query-memory.ts` | Result serialization | Add composites to each memory result |
+| `src/tools/search-space.ts` | Result serialization | Add composites to published memory results |
+| `src/tools/search-by.ts` | Result serialization | Add composites (all modes) |
+
+## Implementation Pattern
+
+For each tool, find the result serialization code (where memory objects are mapped to response JSON) and add:
+
+```typescript
+// After existing field mappings:
+...(memory.total_significance != null && { total_significance: memory.total_significance }),
+...(memory.feel_significance != null && { feel_significance: memory.feel_significance }),
+...(memory.functional_significance != null && { functional_significance: memory.functional_significance }),
+...(memory.rem_touched_at != null && { rem_touched_at: memory.rem_touched_at }),
+...(memory.rem_visits != null && { rem_visits: memory.rem_visits }),
+```
+
+## Key Decisions
+
+- **Null/undefined values MUST be omitted**: Not all memories have been scored by REM. Never return `null` or `undefined` in the response — only include these fields when they have values.
+- **Use conditional spread**: The `...(value != null && { key: value })` pattern ensures clean omission.
+- **All search tools get composites**: Consistency across all search surfaces. If a memory has been scored, the scores are always visible.
+- **No individual feel_* fields in results**: Only the 3 composites + 2 REM metadata fields. Individual feel_* values are accessible via `byProperty` sorting or future detail tools.
+
+## Steps
+
+1. Identify result serialization pattern in each of the 5 tool files
+2. Add composite score and REM metadata fields using conditional spread
+3. Update result type definitions if the project has explicit result interfaces
+4. Write tests:
+   - Composites appear in results when memory has been scored
+   - Composites are omitted when memory has NOT been scored (null/undefined)
+   - REM metadata (rem_touched_at, rem_visits) included when available
+   - All 5 tools include composites consistently
+
+## Verification
+
+- [ ] Composite scores included in search_memory results
+- [ ] Composite scores included in find_similar results
+- [ ] Composite scores included in query_memory results
+- [ ] Composite scores included in search_space results
+- [ ] Composite scores included in search_by results
+- [ ] REM metadata (rem_touched_at, rem_visits) included when available
+- [ ] Null/unscored fields omitted from results (no nulls in output)
+- [ ] Tests passing
+- [ ] TypeScript clean

package/agent/tasks/milestone-19-new-search-ghost-tools/task-208-add-bybroad-byrandom-modes.md

@@ -0,0 +1,115 @@
+# Task 208: Add byBroad and byRandom Modes to search_by
+
+**Milestone**: M19 — New Search Modes, Ghost Tools & Emotional Exposure
+**Status**: Not Started
+**Created**: 2026-03-07
+**Estimated Hours**: 3-4
+**Dependencies**: Task 203 (search_by tool exists), remember-core byBroad and byRandom implementations
+
+---
+
+## Objective
+
+Add `byBroad` and `byRandom` modes to `remember_search_by`. These require new core methods that don't exist yet — this task is blocked until remember-core implements them.
+
+## Context
+
+- **byBroad**: Fetches massive result sets with truncated content (head/mid/tail slices ~100 chars each). Default limit 50-100. Enables "scan and drill-in" workflow — browse broad results, then use `remember_search_memory` or `remember_query_memory` to get full content of interesting items. Includes emotional composites in truncated results.
+- **byRandom**: Random sampling from the collection. Optional query to constrain the random pool. Useful for serendipitous rediscovery of forgotten content.
+
+## Schema Changes
+
+Update `src/tools/search-by.ts`:
+
+1. Add to mode enum: `'byBroad', 'byRandom'`
+2. Update tool description:
+```
+- byBroad: Massive results with truncated content for scan-and-drill-in workflow (default limit: 50)
+- byRandom: Random sampling for serendipitous rediscovery
+```
+
+## `byBroad` Response Shape
+
+byBroad returns a DIFFERENT response shape than other modes — truncated content instead of full content:
+
+```typescript
+interface BroadSearchResult {
+  memory_id: string;
+  title?: string;
+  content_type: string;
+  content_head: string;   // First ~100 chars
+  content_mid: string;    // ~100 chars from middle
+  content_tail: string;   // Last ~100 chars
+  created_at: string;
+  tags: string[];
+  weight: number;
+  // Include emotional composites for context
+  total_significance?: number;
+  feel_significance?: number;
+  functional_significance?: number;
+}
+```
+
+## Handler Logic
+
+```typescript
+case 'byBroad':
+  results = await services.memoryService.byBroad({
+    query: args.query,
+    limit: args.limit ?? 50,  // Default limit is 50, much higher than normal
+    offset: args.offset,
+    filters: args.filters,
+    deleted_filter: args.deleted_filter
+  });
+  // Results already have truncated content (content_head/mid/tail) from core
+  break;
+
+case 'byRandom':
+  results = await services.memoryService.byRandom({
+    query: args.query,  // Optional: constrains the random pool
+    limit: args.limit,
+    filters: args.filters,
+    deleted_filter: args.deleted_filter
+  });
+  // sort_order is not applicable for byRandom
+  break;
+```
+
+## Key Decisions
+
+- **byBroad default limit is 50**: Much higher than normal modes (10). The truncated content format makes this feasible without context overload.
+- **byBroad response shape differs**: `content_head`, `content_mid`, `content_tail` replace the full `content` field. The handler may need to serialize differently.
+- **byBroad includes composites**: `total_significance`, `feel_significance`, `functional_significance` in truncated results for emotional context during scanning.
+- **byRandom query is optional**: When provided, constrains the random pool (e.g., "only random memories tagged 'idea'"). When omitted, samples from entire collection.
+- **byRandom ignores sort_order**: Random is random — sort_order is not applicable.
+- **Both modes support standard filters**: types, tags, weight, trust, date, etc. all work with byBroad and byRandom.
+- **Blocked on core implementation**: Core needs `MemoryService.byBroad()` and `MemoryService.byRandom()`. byRandom could use Weaviate's `near_random` or a client-side shuffle approach.
+
+## Steps
+
+1. Update `src/tools/search-by.ts`:
+   - Add `byBroad` and `byRandom` to mode enum
+   - Add handler cases per logic above
+   - Handle byBroad's different response serialization (content_head/mid/tail)
+   - Update tool description with byBroad and byRandom documentation
+2. Write tests:
+   - `byBroad` returns truncated content format (content_head/mid/tail, NOT full content)
+   - `byBroad` default limit is 50
+   - `byBroad` includes emotional composites
+   - `byRandom` returns results
+   - `byRandom` with query constrains pool
+   - `byRandom` ignores sort_order
+   - Both modes support standard filters and deleted_filter
+
+## Verification
+
+- [ ] `byBroad` returns truncated content (content_head/mid/tail)
+- [ ] `byBroad` does NOT return full content field
+- [ ] `byBroad` default limit is 50
+- [ ] `byBroad` includes emotional composites in results
+- [ ] `byRandom` returns random results
+- [ ] `byRandom` query parameter constrains pool
+- [ ] `byRandom` ignores sort_order
+- [ ] Both modes support standard filters
+- [ ] Tests passing
+- [ ] TypeScript clean

package/agent/tasks/milestone-19-new-search-ghost-tools/task-209-create-ghost-memory-tools.md

@@ -0,0 +1,192 @@
+# Task 209: Create Ghost Memory Tool Suite (5 Tools)
+
+**Milestone**: M19 — New Search Modes, Ghost Tools & Emotional Exposure
+**Status**: Not Started
+**Created**: 2026-03-07
+**Estimated Hours**: 4-6
+**Dependencies**: Task 203 (search_by tool exists for ghost_search_by wrapper)
+
+---
+
+## Objective
+
+Create 5 dedicated ghost memory MCP tools that hardcode `content_type: 'ghost'` and ghost-specific tags. Each tool is a thin wrapper around the corresponding non-ghost tool.
+
+## Context
+
+Ghost memories track cross-user interaction records. Currently, creating ghost memories requires manually setting the correct content_type and tags. Dedicated tools eliminate this error-prone process. Ghost memories are excluded from default searches — they are only visible when explicitly searching with content_type: 'ghost' or using ghost memory tools.
+
+## Tool 1: `remember_create_ghost_memory` (`src/tools/create-ghost-memory.ts`)
+
+```typescript
+{
+  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)' },
+      // Select feel_* fields relevant to ghost interactions
+      feel_salience: { type: 'number', minimum: 0, maximum: 1 },
+      feel_social_weight: { type: 'number', minimum: 0, maximum: 1 },
+      feel_narrative_importance: { type: 'number', minimum: 0, maximum: 1 }
+    },
+    required: ['content']
+  }
+}
+```
+
+**Handler hardcodes**:
+- `content_type: 'ghost'`
+- Adds tags: `ghost`, `ghost:{accessor_user_id}` (accessor_user_id from auth context)
+- Merges hardcoded tags with any user-provided tags
+- Calls `handleCreateMemory` (or core `memoryService.create()`) with merged args
+
+## Tool 2: `remember_update_ghost_memory` (`src/tools/update-ghost-memory.ts`)
+
+```typescript
+{
+  name: 'remember_update_ghost_memory',
+  description: 'Update a ghost memory. Only works on memories with content_type: ghost.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      memory_id: { type: 'string', description: 'Ghost memory ID to update' },
+      content: { type: 'string' },
+      title: { type: 'string' },
+      tags: { type: 'array', items: { type: 'string' } },
+      weight: { type: 'number', minimum: 0, maximum: 1 },
+      trust: { type: 'number', minimum: 0, maximum: 1 }
+    },
+    required: ['memory_id']
+  }
+}
+```
+
+**Handler logic**:
+1. Fetch the memory by ID first
+2. Validate `content_type === 'ghost'` — reject with clear error if not ghost
+3. Delegate to `handleUpdateMemory` / core `memoryService.update()`
+
+## Tool 3: `remember_search_ghost_memory` (`src/tools/search-ghost-memory.ts`)
+
+```typescript
+{
+  name: 'remember_search_ghost_memory',
+  description: `Search ghost memories using hybrid semantic + keyword search.
+  Automatically filters to content_type: ghost. Use this to find specific
+  ghost interaction records.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Search query' },
+      alpha: { type: 'number', minimum: 0, maximum: 1, description: 'Semantic vs keyword balance. Default: 0.7' },
+      tags: { type: 'array', items: { type: 'string' }, description: 'Filter by tags' },
+      limit: { type: 'number', description: 'Max results. Default: 10' },
+      offset: { type: 'number' },
+      deleted_filter: { type: 'string', enum: ['exclude', 'include', 'only'] }
+    },
+    required: ['query']
+  }
+}
+```
+
+**Handler hardcodes**: `filters.types: ['ghost']` before calling `handleSearchMemory` / core search.
+
+## Tool 4: `remember_query_ghost_memory` (`src/tools/query-ghost-memory.ts`)
+
+```typescript
+{
+  name: 'remember_query_ghost_memory',
+  description: `Query ghost memories using natural language (pure semantic search).
+  Automatically filters to content_type: ghost.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Natural language question' },
+      limit: { type: 'number', description: 'Max results. Default: 5' },
+      min_relevance: { type: 'number', description: 'Minimum relevance score. Default: 0.6' }
+    },
+    required: ['query']
+  }
+}
+```
+
+**Handler hardcodes**: `filters.types: ['ghost']` before calling `handleQueryMemory` / core query.
+
+## Tool 5: `remember_search_ghost_memory_by` (`src/tools/search-ghost-memory-by.ts`)
+
+```typescript
+{
+  name: 'remember_search_ghost_memory_by',
+  description: `Search ghost memories using specialized modes (byTime, byDensity,
+  byProperty, byBroad, etc.). Automatically filters to content_type: ghost.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      mode: {
+        type: 'string',
+        enum: ['byTime', 'byDensity', 'byRating', 'byDiscovery', 'byProperty', 'bySignificance', 'byRandom', 'byBroad'],
+        description: 'Search mode'
+      },
+      query: { type: 'string', description: 'Optional search query' },
+      sort_order: { type: 'string', enum: ['asc', 'desc'] },
+      sort_field: { type: 'string', description: 'Property to sort by (byProperty mode)' },
+      limit: { type: 'number' },
+      offset: { type: 'number' },
+      deleted_filter: { type: 'string', enum: ['exclude', 'include', 'only'] }
+    },
+    required: ['mode']
+  }
+}
+```
+
+**Handler hardcodes**: `filters.types: ['ghost']` before calling `handleSearchBy`.
+
+## Key Decisions
+
+- **Ghost tools don't need rating**: Ghosts are read-only accessors. No rating parameters on ghost tools.
+- **Only 3 feel_* fields on create_ghost_memory**: `feel_salience`, `feel_social_weight`, `feel_narrative_importance` — the most relevant for ghost interaction records. NOT all 31.
+- **update_ghost_memory validates content_type**: Must fetch memory first, check `content_type === 'ghost'`, reject if not. This prevents using the ghost update tool on non-ghost memories.
+- **All search/query ghost tools hardcode `filters.types: ['ghost']`**: This is the core behavioral difference from the non-ghost versions. User-provided filters are merged, not replaced.
+- **search_ghost_memory_by has ALL modes**: Even byRating and byDiscovery, though these are less useful for ghost memories. Consistency over restriction.
+- **Tags merging on create**: User-provided tags are merged with hardcoded `['ghost', 'ghost:{accessor_user_id}']`. If user already includes 'ghost' tag, don't duplicate.
+
+## Steps
+
+1. Create 5 tool files in `src/tools/`
+2. Each file exports tool definition + handler function
+3. Register all 5 tools in `src/server-factory.ts` (imports, ListTools, CallTool switch cases)
+4. Write unit tests for each tool:
+   - create: content_type hardcoded to 'ghost', ghost tags added automatically, user tags merged
+   - update: validates content_type before update, rejects non-ghost memories with error
+   - search: filters.types hardcoded to ['ghost'], query/alpha/tags passthrough
+   - query: filters.types hardcoded to ['ghost'], query/limit/min_relevance passthrough
+   - search_by: filters.types hardcoded to ['ghost'], all modes work, sort_field passthrough
+
+## Verification
+
+- [ ] 5 tool files created in src/tools/
+- [ ] All 5 tools registered in server-factory.ts
+- [ ] create_ghost_memory hardcodes content_type: 'ghost'
+- [ ] create_ghost_memory adds 'ghost' and 'ghost:{accessor_user_id}' tags
+- [ ] create_ghost_memory merges user tags without duplicating 'ghost'
+- [ ] update_ghost_memory fetches memory and validates content_type before update
+- [ ] update_ghost_memory rejects non-ghost memories with clear error message
+- [ ] search_ghost_memory hardcodes filters.types: ['ghost']
+- [ ] query_ghost_memory hardcodes filters.types: ['ghost']
+- [ ] search_ghost_memory_by hardcodes filters.types: ['ghost'], all modes work
+- [ ] Unit tests for all 5 tools
+- [ ] TypeScript clean
+- [ ] Build passing

package/agent/tasks/milestone-19-new-search-ghost-tools/task-210-create-get-core-tool.md

@@ -0,0 +1,203 @@
+# Task 210: Create `remember_get_core` Tool
+
+**Milestone**: M19 — New Search Modes, Ghost Tools & Emotional Exposure
+**Status**: Not Started
+**Created**: 2026-03-07
+**Estimated Hours**: 2-3
+**Dependencies**: remember-core mood + perception Firestore service
+
+---
+
+## Objective
+
+Create `remember_get_core` MCP tool that reads the ghost's core state from Firestore — mood dimensions, pressures, motivation/goal/purpose, dominant emotion, color, and user perceptions — in a single call.
+
+## Context
+
+The core mood state lives at `users/{user_id}/core/mood` and user perceptions at `users/{owner_id}/core/perceptions/{target_user_id}` in Firestore. This tool enables ghost introspection — the ghost can explain how it feels and why. Consolidated from separate `remember_get_mood` and `remember_get_perception` since they're on one Firestore document path.
+
+## Tool Definition
+
+```typescript
+{
+  name: 'remember_get_core',
+  description: `Get the ghost's current emotional state and perception model.
+
+  Returns the ghost's current dimensional state (valence, arousal, confidence,
+  social_warmth, coherence, trust), derived emotion labels (dominant_emotion, color),
+  directional state (motivation, goal, purpose), and active pressure sources.
+
+  Optionally includes the ghost's internal model of a specific user (personality,
+  communication style, interests, patterns, needs).
+
+  Use this for introspection — understanding how the ghost feels and why.
+  The mood state biases memory retrieval and influences ghost behavior.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      include_pressures: {
+        type: 'boolean',
+        description: 'Include active pressure sources with reasons. Default: true'
+      },
+      include_perception: {
+        type: 'string',
+        description: 'Include the ghost\'s perception of a specific user (by user_id). Omit to skip. Use owner\'s user_id for self-perception.'
+      }
+    }
+  }
+}
+```
+
+## Return Shape
+
+```typescript
+interface GetCoreResult {
+  mood: {
+    state: {
+      valence: number;        // -1 to 1: Did events move toward or away from goals?
+      arousal: number;        // 0 to 1: How activated/alert? Prediction error level
+      confidence: number;     // 0 to 1: How well are actions working? Agency signal
+      social_warmth: number;  // 0 to 1: How positive are social interactions?
+      coherence: number;      // 0 to 1: Do beliefs and memories fit together?
+      trust: number;          // 0 to 1: Trust in user based on accumulated interactions
+    };
+    color: string;              // Natural language self-summary, e.g. "cautiously optimistic"
+    dominant_emotion: string;   // Emotion label, e.g. "curious wariness"
+    reasoning: string;          // Why this emotion fits
+    motivation: string;         // Current behavioral driver
+    goal: string;               // Active goal
+    purpose: string;            // Enduring purpose
+    pressures?: Pressure[];     // Active pressure sources (when include_pressures=true)
+    last_updated: string;       // ISO timestamp
+    rem_cycles_since_shift: number;
+  };
+  perception?: {
+    owner_id: string;
+    target_user_id: string;
+    personality_sketch: string;     // Sub-LLM summary of who the user is
+    communication_style: string;    // How the user communicates
+    emotional_baseline: string;     // User's normal emotional register (calibrates arousal)
+    interests: string[];            // Recurring topics
+    patterns: string[];             // Observed behavioral patterns
+    needs: string[];                // What the user wants from the ghost
+    evolution_notes: string[];      // How the perception has changed over time
+    confidence_level: number;       // 0-1, ghost's confidence in this model
+    last_updated: string;
+  };
+}
+```
+
+## Pressure Object Shape
+
+```typescript
+interface Pressure {
+  source_memory_id: string;   // Memory that caused this pressure
+  dimension: string;          // Which mood dimension is affected (e.g. 'valence', 'trust')
+  magnitude: number;          // Strength of pressure (-1 to 1)
+  reason: string;             // Why this memory creates pressure
+  decay_rate: number;         // How quickly this pressure fades
+}
+```
+
+## Threshold Flags
+
+The mood document may contain threshold flags that should be included in the response when present:
+
+| Threshold | Condition | Flag |
+|-----------|-----------|------|
+| coherence < 0.2 for 3+ cycles | Existential crisis | `existential_crisis` |
+| valence < -0.7 for 3+ cycles | Depression analog | `depression_analog` |
+| arousal > 0.9 for 3+ cycles | Burnout risk | `burnout_risk` |
+| social_warmth < 0.2 for 5+ cycles | Isolation | `isolation` |
+| trust < 0.15 for 3+ cycles | Trust crisis | `trust_crisis` |
+| trust > 0.95 for 5+ cycles | Over-trust vulnerability | `over_trust` |
+
+If any threshold flags are active, include them in the response as `threshold_flags: string[]`.
+
+## Handler Logic
+
+```typescript
+async function handleGetCore(userId: string, args: GetCoreArgs): Promise<ToolResult> {
+  const services = await createCoreServices(userId);
+
+  // Read mood state from Firestore: users/{user_id}/core/mood
+  const mood = await services.coreMoodService.getMood(userId);
+
+  if (!mood) {
+    return { content: [{ type: 'text', text: JSON.stringify({ mood: null, message: 'No mood state found. Mood is initialized during the first REM cycle.' }) }] };
+  }
+
+  const result: GetCoreResult = {
+    mood: {
+      state: mood.state,
+      color: mood.color,
+      dominant_emotion: mood.dominant_emotion,
+      reasoning: mood.reasoning,
+      motivation: mood.motivation,
+      goal: mood.goal,
+      purpose: mood.purpose,
+      last_updated: mood.last_updated,
+      rem_cycles_since_shift: mood.rem_cycles_since_shift,
+    }
+  };
+
+  // Include pressures if requested (default: true)
+  if (args.include_pressures !== false && mood.pressures) {
+    result.mood.pressures = mood.pressures;
+  }
+
+  // Include threshold flags if any are active
+  if (mood.threshold_flags?.length > 0) {
+    result.mood.threshold_flags = mood.threshold_flags;
+  }
+
+  // Include perception if requested
+  if (args.include_perception) {
+    const perception = await services.coreMoodService.getPerception(userId, args.include_perception);
+    if (perception) {
+      result.perception = perception;
+    }
+  }
+
+  return { content: [{ type: 'text', text: JSON.stringify(result) }] };
+}
+```
+
+## Key Decisions
+
+- **Privacy: owner only**: Only the owner can read their own core state. Ghost accessors cannot read another user's mood. Enforce via userId from auth context.
+- **Pressures included by default**: `include_pressures` defaults to `true`. Set to `false` to exclude.
+- **Perception is opt-in**: Must provide `include_perception` with a target user_id to include. Self-perception uses the owner's own user_id.
+- **Graceful handling of missing mood**: If no mood document exists (first-time user before any REM cycle), return `{ mood: null }` with a message. Do NOT error.
+- **Threshold flags only when active**: Don't include `threshold_flags` field at all if empty.
+- **Consolidated from get_mood + get_perception**: Single tool because mood and perception live under the same Firestore path (`users/{user_id}/core/`).
+
+## Steps
+
+1. Create `src/tools/get-core.ts` with tool definition and handler per above
+2. Register in `src/server-factory.ts`
+3. Write unit tests:
+   - Mood state returned correctly with all 6 dimensions + derived labels + directional state
+   - Pressures included by default, excludable with `include_pressures: false`
+   - Perception included when `include_perception` provided with valid user_id
+   - Perception omitted when `include_perception` not provided
+   - Self-perception works (include_perception = owner's user_id)
+   - Privacy enforced (no cross-user access)
+   - Graceful handling when mood doc doesn't exist yet (returns null, not error)
+   - Threshold flags included when active, omitted when empty/none
+
+## Verification
+
+- [ ] Tool definition exports `getCoreTool` and `handleGetCore`
+- [ ] Mood state returned with all 6 dimensions (valence, arousal, confidence, social_warmth, coherence, trust)
+- [ ] Derived labels returned (color, dominant_emotion, reasoning)
+- [ ] Directional state returned (motivation, goal, purpose)
+- [ ] Pressures included by default, excludable
+- [ ] Threshold flags included when active
+- [ ] Perception included when target_user_id provided
+- [ ] Self-perception works
+- [ ] Privacy enforced (owner only)
+- [ ] Graceful handling of missing mood doc (null, not error)
+- [ ] Registered in server-factory.ts
+- [ ] Unit tests passing
+- [ ] TypeScript clean