list_entities

Instructions

Implementation Reference

• src/mcp/server.ts:115-128 (schema)

  Schema/input definition for the 'list_entities' tool, defining its name, description, and inputSchema properties (kind, min_memories, limit, offset).

  {
    name: 'list_entities',
    description:
      'List the entities currently known to this memory store, sorted by recent activity. Use at the start of a new session ("what do I know about?") before issuing specific recall queries. Cheaper than recall for the "give me an overview" question.',
    inputSchema: {
      type: 'object',
      properties: {
        kind: { type: 'string', enum: ['person', 'company', 'project', 'concept', 'file', 'other'], description: 'Filter by entity kind.' },
        min_memories: { type: 'number', description: 'Only include entities with at least N memories. Default 1.', default: 1 },
        limit: { type: 'number', description: 'Max entities to return. Default 30.', default: 30 },
        offset: { type: 'number', default: 0 },
      },
    },
  },

• src/mcp/server.ts:661-720 (handler)

  The actual handler function 'handleListEntities' that executes the tool logic: queries the entities table joined with memories, applies filters (kind, min_memories), sorts by momentum/memory_count/recency, and returns the matching entities with layer breakdown and pinned_count.

  function handleListEntities(args: any): string {
    const kind = args?.kind as string | undefined;
    const minMemories = Math.max(1, Number(args?.min_memories ?? 1));
    const limit = Math.max(1, Math.min(200, Number(args?.limit ?? 30)));
    const offset = Math.max(0, Number(args?.offset ?? 0));
  
    let sql = `
      SELECT e.id, e.name, e.kind, e.canonical_key, e.momentum_score,
             e.updated_at, e.created_at,
             COUNT(m.id) as memory_count,
             MAX(m.last_accessed_at) as last_memory_access,
             SUM(CASE WHEN m.layer = 'goal' THEN 1 ELSE 0 END) as goal_count,
             SUM(CASE WHEN m.layer = 'caveat' THEN 1 ELSE 0 END) as caveat_count,
             SUM(CASE WHEN m.layer = 'learning' THEN 1 ELSE 0 END) as learning_count,
             SUM(CASE WHEN m.layer = 'implementation' THEN 1 ELSE 0 END) as impl_count,
             SUM(CASE WHEN m.importance >= 0.9 THEN 1 ELSE 0 END) as pinned_count
      FROM entities e
      LEFT JOIN memories m ON m.entity_id = e.id
      WHERE 1=1
    `;
    const params: any[] = [];
    if (kind) { sql += ' AND e.kind = ?'; params.push(kind); }
    sql += ' GROUP BY e.id';
    if (minMemories > 1) sql += ' HAVING memory_count >= ?';
    if (minMemories > 1) params.push(minMemories);
    // Sort: active (high momentum) first, then most memories, then most recent
    sql += ' ORDER BY (COALESCE(e.momentum_score,0) * 10 + memory_count * 0.5 + (last_memory_access / 86400.0 / 365) * 2) DESC';
    sql += ' LIMIT ? OFFSET ?';
    params.push(limit, offset);
  
    const rows = db.prepare(sql).all(...params) as any[];
  
    const totalRow = db.prepare(
      kind ? 'SELECT COUNT(*) as c FROM entities WHERE kind = ?' : 'SELECT COUNT(*) as c FROM entities'
    ).get(...(kind ? [kind] : [])) as { c: number };
  
    return JSON.stringify({
      ok: true,
      total: totalRow.c,
      returned: rows.length,
      offset,
      has_more: offset + rows.length < totalRow.c,
      entities: rows.map((r) => ({
        id: r.id,
        name: r.name,
        kind: r.kind,
        canonical_key: r.canonical_key,
        momentum: Number((r.momentum_score ?? 0).toFixed(2)),
        memory_count: r.memory_count,
        last_memory_access: r.last_memory_access ? new Date(r.last_memory_access * 1000).toISOString() : null,
        layer_breakdown: {
          goal: r.goal_count,
          caveat: r.caveat_count,
          learning: r.learning_count,
          implementation: r.impl_count,
        },
        pinned_count: r.pinned_count,
      })),
    });
  }

• src/mcp/server.ts:807-807 (registration)

  The MCP tool dispatch registration in the CallToolRequestSchema handler, routing 'list_entities' to handleListEntities.

  case 'list_entities': text = handleListEntities(args); break;