@prmichaelsen/remember-mcp 3.15.3 → 3.15.5

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

@@ -0,0 +1,73 @@
+/**
+ * remember_search_ghost_memory tool
+ * Wraps search_memory with hardcoded ghost type filter
+ */
+
+import { handleToolError } from '../utils/error-handler.js';
+import { createDebugLogger } from '../utils/debug.js';
+import type { AuthContext } from '../types/auth.js';
+import { handleSearchMemory } from './search-memory.js';
+
+export const searchGhostMemoryTool = {
+  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'],
+  },
+};
+
+export interface SearchGhostMemoryArgs {
+  query: string;
+  alpha?: number;
+  tags?: string[];
+  limit?: number;
+  offset?: number;
+  deleted_filter?: 'exclude' | 'include' | 'only';
+}
+
+export async function handleSearchGhostMemory(
+  args: SearchGhostMemoryArgs,
+  userId: string,
+  authContext?: AuthContext
+): Promise<string> {
+  const debug = createDebugLogger({ tool: 'remember_search_ghost_memory', userId, operation: 'search ghost memories' });
+  try {
+    debug.info('Tool invoked');
+    debug.trace('Arguments', { args });
+
+    // Delegate to search_memory with ghost type filter hardcoded
+    return await handleSearchMemory(
+      {
+        query: args.query,
+        alpha: args.alpha,
+        limit: args.limit,
+        offset: args.offset,
+        filters: {
+          types: ['ghost'] as any,
+          tags: args.tags,
+        },
+        deleted_filter: args.deleted_filter,
+      },
+      userId,
+      authContext
+    );
+  } catch (error) {
+    debug.error('Tool failed', { error: error instanceof Error ? error.message : String(error) });
+    handleToolError(error, {
+      toolName: 'remember_search_ghost_memory',
+      operation: 'search ghost memories',
+      userId,
+    });
+  }
+}

package/src/tools/search-memory.ts

@@ -35,6 +35,12 @@ export const searchMemoryTool = {
   - "Search for recipes I saved" → returns recipe memories + related relationships
   - "Show me notes from last week" → returns notes + any relationships created that week
   
+  **GRAPH TRAVERSAL**: Use include_relationships: true (the default) to discover graph nodes
+  that link memories together. Relationships contain observations about how memories connect.
+  When exploring a memory in more detail, search for it and examine the returned relationships
+  to find related memories you can drill into — this lets you traverse the memory graph and
+  explore a memory's "near field" of connected knowledge.
+
   **AGENT GUIDANCE**:
   - ⚠️ **CRITICAL - CONTENT TYPE FILTERING**: Do NOT add filters.types unless the user explicitly requests filtering by content type.
     * ✅ CORRECT: User says "search for hiking" → { query: "hiking" }
@@ -106,6 +112,23 @@ export const searchMemoryTool = {
             type: 'string',
             description: 'End date (ISO 8601)',
           },
+          exclude_types: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Exclude specific content types (takes precedence over types if both provided)',
+          },
+          rating_min: {
+            type: 'number',
+            description: 'Minimum Bayesian rating average',
+          },
+          relationship_count_min: {
+            type: 'number',
+            description: 'Minimum relationship count',
+          },
+          relationship_count_max: {
+            type: 'number',
+            description: 'Maximum relationship count',
+          },
         },
       },
       include_relationships: {

package/src/tools/search-space-by.spec.ts

@@ -0,0 +1,289 @@
+import { searchSpaceByTool, handleSearchSpaceBy } from './search-space-by.js';
+
+const mockByDiscovery = jest.fn();
+const mockByTime = jest.fn();
+const mockByRating = jest.fn();
+const mockByProperty = jest.fn();
+const mockByBroad = jest.fn();
+const mockByRandom = jest.fn();
+
+jest.mock('../core-services.js', () => ({
+  createCoreServices: jest.fn(() => ({
+    space: {
+      byDiscovery: mockByDiscovery,
+      byTime: mockByTime,
+      byRating: mockByRating,
+      byProperty: mockByProperty,
+      byBroad: mockByBroad,
+      byRandom: mockByRandom,
+    },
+  })),
+}));
+
+jest.mock('../utils/debug.js', () => ({
+  createDebugLogger: () => ({
+    info: jest.fn(),
+    trace: jest.fn(),
+    error: jest.fn(),
+  }),
+}));
+
+const mockResult = {
+  memories: [{ id: 'pub-1', content: 'published memory' }],
+  total: 1,
+  offset: 0,
+  limit: 10,
+};
+
+describe('remember_search_space_by', () => {
+  const userId = 'test-user-1';
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockByDiscovery.mockResolvedValue(mockResult);
+    mockByTime.mockResolvedValue(mockResult);
+    mockByRating.mockResolvedValue(mockResult);
+    mockByProperty.mockResolvedValue(mockResult);
+    mockByBroad.mockResolvedValue(mockResult);
+    mockByRandom.mockResolvedValue(mockResult);
+  });
+
+  describe('tool definition', () => {
+    it('has correct name', () => {
+      expect(searchSpaceByTool.name).toBe('remember_search_space_by');
+    });
+
+    it('requires mode', () => {
+      expect(searchSpaceByTool.inputSchema.required).toContain('mode');
+    });
+
+    it('has all mode options (no byDensity)', () => {
+      const modeProp = (searchSpaceByTool.inputSchema.properties as any).mode;
+      expect(modeProp.enum).toEqual(['byTime', 'byRating', 'byDiscovery', 'byProperty', 'byBroad', 'byRandom']);
+      expect(modeProp.enum).not.toContain('byDensity');
+    });
+
+    it('has spaces and groups parameters', () => {
+      const props = searchSpaceByTool.inputSchema.properties as any;
+      expect(props.spaces).toBeDefined();
+      expect(props.groups).toBeDefined();
+    });
+
+    it('has moderation_filter and include_comments', () => {
+      const props = searchSpaceByTool.inputSchema.properties as any;
+      expect(props.moderation_filter).toBeDefined();
+      expect(props.include_comments).toBeDefined();
+    });
+  });
+
+  describe('validation', () => {
+    it('returns error when neither spaces nor groups provided', async () => {
+      const result = await handleSearchSpaceBy({ mode: 'byDiscovery' }, userId);
+      const parsed = JSON.parse(result);
+      expect(parsed.error).toContain('spaces');
+      expect(parsed.error).toContain('groups');
+    });
+
+    it('returns error with empty spaces array and no groups', async () => {
+      const result = await handleSearchSpaceBy({ mode: 'byDiscovery', spaces: [] }, userId);
+      const parsed = JSON.parse(result);
+      expect(parsed.error).toContain('spaces');
+    });
+  });
+
+  describe('byDiscovery mode', () => {
+    it('dispatches to space.byDiscovery', async () => {
+      const result = await handleSearchSpaceBy(
+        { mode: 'byDiscovery', spaces: ['public'] },
+        userId,
+      );
+      expect(mockByDiscovery).toHaveBeenCalledTimes(1);
+      expect(JSON.parse(result)).toEqual(mockResult);
+    });
+
+    it('passes spaces parameter', async () => {
+      await handleSearchSpaceBy({ mode: 'byDiscovery', spaces: ['space-1', 'space-2'] }, userId);
+      expect(mockByDiscovery).toHaveBeenCalledWith(
+        expect.objectContaining({ spaces: ['space-1', 'space-2'] }),
+        undefined,
+      );
+    });
+
+    it('passes groups parameter', async () => {
+      await handleSearchSpaceBy({ mode: 'byDiscovery', groups: ['group-1'] }, userId);
+      expect(mockByDiscovery).toHaveBeenCalledWith(
+        expect.objectContaining({ groups: ['group-1'] }),
+        undefined,
+      );
+    });
+
+    it('passes both spaces and groups', async () => {
+      await handleSearchSpaceBy(
+        { mode: 'byDiscovery', spaces: ['pub'], groups: ['grp-1'] },
+        userId,
+      );
+      expect(mockByDiscovery).toHaveBeenCalledWith(
+        expect.objectContaining({ spaces: ['pub'], groups: ['grp-1'] }),
+        undefined,
+      );
+    });
+
+    it('passes query through', async () => {
+      await handleSearchSpaceBy(
+        { mode: 'byDiscovery', spaces: ['pub'], query: 'explore' },
+        userId,
+      );
+      expect(mockByDiscovery).toHaveBeenCalledWith(
+        expect.objectContaining({ query: 'explore' }),
+        undefined,
+      );
+    });
+
+    it('passes limit and offset', async () => {
+      await handleSearchSpaceBy(
+        { mode: 'byDiscovery', spaces: ['pub'], limit: 20, offset: 5 },
+        userId,
+      );
+      expect(mockByDiscovery).toHaveBeenCalledWith(
+        expect.objectContaining({ limit: 20, offset: 5 }),
+        undefined,
+      );
+    });
+
+    it('defaults limit to 10 and offset to 0', async () => {
+      await handleSearchSpaceBy({ mode: 'byDiscovery', spaces: ['pub'] }, userId);
+      expect(mockByDiscovery).toHaveBeenCalledWith(
+        expect.objectContaining({ limit: 10, offset: 0 }),
+        undefined,
+      );
+    });
+
+    it('passes moderation_filter', async () => {
+      await handleSearchSpaceBy(
+        { mode: 'byDiscovery', spaces: ['pub'], moderation_filter: 'approved' },
+        userId,
+      );
+      expect(mockByDiscovery).toHaveBeenCalledWith(
+        expect.objectContaining({ moderation_filter: 'approved' }),
+        undefined,
+      );
+    });
+
+    it('passes include_comments', async () => {
+      await handleSearchSpaceBy(
+        { mode: 'byDiscovery', spaces: ['pub'], include_comments: true },
+        userId,
+      );
+      expect(mockByDiscovery).toHaveBeenCalledWith(
+        expect.objectContaining({ include_comments: true }),
+        undefined,
+      );
+    });
+  });
+
+  describe('byTime mode', () => {
+    it('dispatches to space.byTime', async () => {
+      const result = await handleSearchSpaceBy({ mode: 'byTime', spaces: ['pub'] }, userId);
+      expect(mockByTime).toHaveBeenCalledTimes(1);
+      expect(JSON.parse(result)).toEqual(mockResult);
+    });
+
+    it('passes sort_order as direction', async () => {
+      await handleSearchSpaceBy({ mode: 'byTime', spaces: ['pub'], sort_order: 'asc' }, userId);
+      expect(mockByTime).toHaveBeenCalledWith(
+        expect.objectContaining({ direction: 'asc' }),
+        undefined,
+      );
+    });
+
+    it('defaults direction to desc', async () => {
+      await handleSearchSpaceBy({ mode: 'byTime', spaces: ['pub'] }, userId);
+      expect(mockByTime).toHaveBeenCalledWith(
+        expect.objectContaining({ direction: 'desc' }),
+        undefined,
+      );
+    });
+  });
+
+  describe('byRating mode', () => {
+    it('dispatches to space.byRating', async () => {
+      const result = await handleSearchSpaceBy({ mode: 'byRating', spaces: ['pub'] }, userId);
+      expect(mockByRating).toHaveBeenCalledTimes(1);
+      expect(JSON.parse(result)).toEqual(mockResult);
+    });
+
+    it('passes sort_order as direction', async () => {
+      await handleSearchSpaceBy({ mode: 'byRating', spaces: ['pub'], sort_order: 'asc' }, userId);
+      expect(mockByRating).toHaveBeenCalledWith(
+        expect.objectContaining({ direction: 'asc' }),
+        undefined,
+      );
+    });
+  });
+
+  describe('byProperty mode', () => {
+    it('returns error when sort_field missing', async () => {
+      const result = await handleSearchSpaceBy({ mode: 'byProperty', spaces: ['pub'] }, userId);
+      const parsed = JSON.parse(result);
+      expect(parsed.error).toContain('sort_field is required');
+    });
+
+    it('dispatches to space.byProperty with sort_field', async () => {
+      const result = await handleSearchSpaceBy(
+        { mode: 'byProperty', spaces: ['pub'], sort_field: 'feel_trauma' },
+        userId,
+      );
+      expect(mockByProperty).toHaveBeenCalledWith(
+        expect.objectContaining({ sort_field: 'feel_trauma', sort_direction: 'desc' }),
+        undefined,
+      );
+      expect(JSON.parse(result)).toEqual(mockResult);
+    });
+
+    it('passes sort_order as sort_direction', async () => {
+      await handleSearchSpaceBy(
+        { mode: 'byProperty', spaces: ['pub'], sort_field: 'weight', sort_order: 'asc' },
+        userId,
+      );
+      expect(mockByProperty).toHaveBeenCalledWith(
+        expect.objectContaining({ sort_field: 'weight', sort_direction: 'asc' }),
+        undefined,
+      );
+    });
+  });
+
+  describe('byBroad mode', () => {
+    it('dispatches to space.byBroad', async () => {
+      const result = await handleSearchSpaceBy({ mode: 'byBroad', spaces: ['pub'] }, userId);
+      expect(mockByBroad).toHaveBeenCalledTimes(1);
+      expect(JSON.parse(result)).toEqual(mockResult);
+    });
+
+    it('passes query through', async () => {
+      await handleSearchSpaceBy({ mode: 'byBroad', spaces: ['pub'], query: 'explore' }, userId);
+      expect(mockByBroad).toHaveBeenCalledWith(
+        expect.objectContaining({ query: 'explore' }),
+        undefined,
+      );
+    });
+  });
+
+  describe('byRandom mode', () => {
+    it('dispatches to space.byRandom', async () => {
+      const result = await handleSearchSpaceBy({ mode: 'byRandom', spaces: ['pub'] }, userId);
+      expect(mockByRandom).toHaveBeenCalledTimes(1);
+      expect(JSON.parse(result)).toEqual(mockResult);
+    });
+  });
+
+  describe('invalid mode', () => {
+    it('returns error for unknown mode', async () => {
+      const result = await handleSearchSpaceBy(
+        { mode: 'byInvalid' as any, spaces: ['pub'] },
+        userId,
+      );
+      const parsed = JSON.parse(result);
+      expect(parsed.error).toContain('Unknown mode');
+    });
+  });
+});

package/src/tools/search-space-by.ts

@@ -0,0 +1,173 @@
+/**
+ * remember_search_space_by tool
+ * Unified search modes for space/group published memories
+ */
+
+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 type SearchSpaceByMode = 'byTime' | 'byRating' | 'byDiscovery' | 'byProperty' | 'byBroad' | 'byRandom';
+
+export const searchSpaceByTool = {
+  name: 'remember_search_space_by',
+  description: `Search shared spaces using specialized modes. Similar to remember_search_by
+  but operates on published memories in spaces and groups.
+
+  Modes:
+  - byTime: Chronological sort of published memories
+  - byRating: Sort by Bayesian rating average (social ratings)
+  - byDiscovery: Interleaved rated + unrated for exploration
+  - byProperty: Sort by any property (e.g., feel_trauma, total_significance)
+  - byBroad: Massive results with truncated content
+  - byRandom: Random sampling from space
+
+  At least one of 'spaces' or 'groups' must be provided.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      mode: {
+        type: 'string',
+        enum: ['byTime', 'byRating', 'byDiscovery', 'byProperty', 'byBroad', 'byRandom'],
+        description: 'Search mode',
+      },
+      spaces: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Space names to search',
+      },
+      groups: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Group IDs to search',
+      },
+      query: { type: 'string', description: 'Optional search query' },
+      sort_order: {
+        type: 'string',
+        enum: ['asc', 'desc'],
+        description: 'Sort order. Default: desc',
+      },
+      sort_field: {
+        type: 'string',
+        description: 'Property to sort by (byProperty mode only)',
+      },
+      limit: { type: 'number', description: 'Max results. Default: 10 (byBroad: 50)' },
+      offset: { type: 'number', description: 'Pagination offset' },
+      moderation_filter: {
+        type: 'string',
+        description: 'Moderation filter level',
+      },
+      include_comments: {
+        type: 'boolean',
+        description: 'Include comments on published memories. Default: false',
+      },
+    },
+    required: ['mode'],
+  },
+};
+
+export interface SearchSpaceByArgs {
+  mode: SearchSpaceByMode;
+  spaces?: string[];
+  groups?: string[];
+  query?: string;
+  sort_order?: 'asc' | 'desc';
+  sort_field?: string;
+  limit?: number;
+  offset?: number;
+  moderation_filter?: string;
+  include_comments?: boolean;
+}
+
+export async function handleSearchSpaceBy(
+  args: SearchSpaceByArgs,
+  userId: string,
+  authContext?: AuthContext
+): Promise<string> {
+  const debug = createDebugLogger({ tool: 'remember_search_space_by', userId, operation: `space search by ${args.mode}` });
+  try {
+    debug.info('Tool invoked');
+    debug.trace('Arguments', { args });
+
+    // Validate at least one of spaces or groups is provided
+    if (!args.spaces?.length && !args.groups?.length) {
+      return JSON.stringify({
+        error: 'At least one of "spaces" or "groups" must be provided.',
+      });
+    }
+
+    const { space } = createCoreServices(userId);
+
+    const baseParams = {
+      spaces: args.spaces,
+      groups: args.groups,
+      query: args.query,
+      limit: args.limit ?? 10,
+      offset: args.offset ?? 0,
+      moderation_filter: args.moderation_filter,
+      include_comments: args.include_comments,
+    };
+
+    let result;
+    switch (args.mode) {
+      case 'byDiscovery':
+        result = await space.byDiscovery(baseParams as any, authContext as any);
+        break;
+
+      case 'byTime':
+        result = await space.byTime({
+          ...baseParams,
+          direction: args.sort_order ?? 'desc',
+        } as any, authContext as any);
+        break;
+
+      case 'byRating':
+        result = await space.byRating({
+          ...baseParams,
+          direction: args.sort_order ?? 'desc',
+        } as any, authContext as any);
+        break;
+
+      case 'byProperty': {
+        if (!args.sort_field) {
+          return JSON.stringify({
+            error: 'sort_field is required for byProperty mode. Provide a property name (e.g., "feel_trauma", "total_significance").',
+          });
+        }
+        result = await space.byProperty({
+          ...baseParams,
+          sort_field: args.sort_field,
+          sort_direction: args.sort_order ?? 'desc',
+        } as any, authContext as any);
+        break;
+      }
+
+      case 'byBroad':
+        result = await space.byBroad({
+          ...baseParams,
+          query: args.query,
+          sort_order: args.sort_order,
+        } as any, authContext as any);
+        break;
+
+      case 'byRandom':
+        result = await space.byRandom(baseParams as any, authContext as any);
+        break;
+
+      default:
+        return JSON.stringify({
+          error: `Unknown mode: ${(args as any).mode}. Valid modes: byTime, byRating, byDiscovery, byProperty, byBroad, byRandom`,
+        });
+    }
+
+    return JSON.stringify(result, null, 2);
+  } catch (error) {
+    debug.error('Tool failed', { error: error instanceof Error ? error.message : String(error) });
+    handleToolError(error, {
+      toolName: 'remember_search_space_by',
+      operation: `space search by ${args.mode}`,
+      userId,
+    });
+  }
+}

package/src/tools/search-space.ts

@@ -28,6 +28,11 @@ Destinations:
 
 Results from multiple sources are merged and deduplicated by composite ID, sorted by relevance.
 
+**GRAPH TRAVERSAL**: To explore a space memory's connections, take the memory's source ID and
+use remember_search_memory with include_relationships: true to find graph nodes linking to it.
+This lets you traverse the original author's memory graph to discover related context, connected
+topics, and the memory's "near field" of knowledge.
+
 ⚠️ **CRITICAL - CONTENT TYPE FILTERING**: Do NOT add content_type filter unless the user explicitly requests filtering by type.
 - ✅ CORRECT: User says "search The Void for hiking" → { spaces: ["the_void"], query: "hiking" }
 - ❌ WRONG: User says "search The Void for hiking" → { spaces: ["the_void"], query: "hiking", content_type: "note" }
@@ -91,6 +96,15 @@ Let the search algorithm find ALL relevant memories regardless of type unless ex
         type: 'string',
         description: 'Filter memories created before this date (ISO 8601)',
       },
+      exclude_types: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Exclude specific content types',
+      },
+      rating_min: {
+        type: 'number',
+        description: 'Minimum Bayesian rating average',
+      },
       moderation_filter: {
         type: 'string',
         enum: ['approved', 'pending', 'rejected', 'removed', 'all'],
@@ -161,11 +175,13 @@ interface SearchSpaceArgs {
   groups?: string[];
   search_type?: 'hybrid' | 'bm25' | 'semantic';
   content_type?: string;
+  exclude_types?: string[];
   tags?: string[];
   min_weight?: number;
   max_weight?: number;
   date_from?: string;
   date_to?: string;
+  rating_min?: number;
   moderation_filter?: ModerationFilter;
   include_comments?: boolean;
   limit?: number;
@@ -207,7 +223,10 @@ export async function handleSearchSpace(
         include_comments: args.include_comments,
         limit: args.limit,
         offset: args.offset,
-      },
+        // New filters — passed through when core supports them
+        ...(args.exclude_types && { exclude_types: args.exclude_types }),
+        ...(args.rating_min !== undefined && { rating_min: args.rating_min }),
+      } as any,
       authContext as any
     );