atlas-mcp 0.1.0

package/src/shared/brain-regions.js

@@ -0,0 +1,61 @@
+export const CORE_BRAIN_REGIONS = Object.freeze([
+  "hippocampus",
+  "prefrontal",
+  "temporalCortex",
+  "parietalCortex",
+  "amygdala",
+  "basalGanglia",
+  "cerebellum",
+  "motorCortex",
+  "insula",
+]);
+
+const SURFACE_REGION_PROFILES = Object.freeze({
+  prefrontal: {
+    center: [0, 0.35, 1.8],
+    radius: [1.8, 1.45, 1.15],
+  },
+  temporalCortex: {
+    center: [1.45, -0.5, 0.35],
+    radius: [0.85, 1.1, 1.45],
+    bilateral: true,
+  },
+  parietalCortex: {
+    center: [0, 1.2, -0.9],
+    radius: [1.9, 1.05, 1.35],
+  },
+  cerebellum: {
+    center: [0, -1.55, -1.45],
+    radius: [1.45, 0.7, 1.1],
+  },
+  motorCortex: {
+    center: [0, 1.25, 0.25],
+    radius: [1.9, 0.7, 0.75],
+  },
+  insula: {
+    center: [1.25, -0.05, 0.45],
+    radius: [0.7, 0.8, 0.8],
+    bilateral: true,
+  },
+});
+
+export function getSurfaceBrainRegion(point) {
+  let closestRegion = null;
+  let closestDistance = Infinity;
+
+  for (const [region, profile] of Object.entries(SURFACE_REGION_PROFILES)) {
+    const x = profile.bilateral ? Math.abs(point[0]) : point[0];
+    const distance = profile.center.reduce((total, center, index) => {
+      const coordinate = index === 0 ? x : point[index];
+      const normalized = (coordinate - center) / profile.radius[index];
+      return total + normalized * normalized;
+    }, 0);
+
+    if (distance < closestDistance) {
+      closestRegion = region;
+      closestDistance = distance;
+    }
+  }
+
+  return closestRegion;
+}

package/src/shared/entity-lens.js

@@ -0,0 +1,249 @@
+export const ENTITY_KIND_COLORS = Object.freeze({
+  person: "#9bbcff",
+  place: "#7ee8d3",
+  object: "#ffd38a",
+  concept: "#e99fd1",
+  organization: "#ffad8a",
+});
+
+const HUB_OUTWARD_OFFSET = 0.62;
+const HUB_TANGENT_OFFSET = 0.12;
+const PREVIEW_OUTWARD_OFFSET = 0.36;
+const PREVIEW_TANGENT_OFFSET = 0.58;
+
+export function calculateEntityHubPosition(originPosition, entityId) {
+  const origin = toVector(originPosition);
+  const outward = normalize(origin, [0, 0, 1]);
+  const [tangentA, tangentB] = getTangents(outward);
+  const angle = hashUnit(`entity:${entityId}:hub`) * Math.PI * 2;
+
+  return clampToBrainBoundary(
+    addVectors(
+      origin,
+      scaleVector(outward, HUB_OUTWARD_OFFSET),
+      scaleVector(tangentA, Math.cos(angle) * HUB_TANGENT_OFFSET),
+      scaleVector(tangentB, Math.sin(angle) * HUB_TANGENT_OFFSET),
+    ),
+  );
+}
+
+export function calculateRelationshipPreviewPosition(
+  hubPosition,
+  counterpartEntityId,
+  direction,
+) {
+  const hub = toVector(hubPosition);
+  const outward = normalize(hub, [0, 0, 1]);
+  const [tangentA, tangentB] = getTangents(outward);
+  const directionOffset = direction === "incoming" ? Math.PI : 0;
+  const angle =
+    hashUnit(`entity:${counterpartEntityId}:preview`) * Math.PI * 2 +
+    directionOffset;
+
+  return clampToBrainBoundary(
+    addVectors(
+      hub,
+      scaleVector(outward, PREVIEW_OUTWARD_OFFSET),
+      scaleVector(tangentA, Math.cos(angle) * PREVIEW_TANGENT_OFFSET),
+      scaleVector(tangentB, Math.sin(angle) * PREVIEW_TANGENT_OFFSET),
+    ),
+  );
+}
+
+export function getRelationshipDirection(relationship, entityId) {
+  const activeId = Number(entityId);
+  if (Number(relationship?.source?.id) === activeId) return "outgoing";
+  if (Number(relationship?.target?.id) === activeId) return "incoming";
+  return null;
+}
+
+export function getRelationshipCounterpart(relationship, entityId) {
+  const direction = getRelationshipDirection(relationship, entityId);
+  if (direction === "outgoing") return relationship.target;
+  if (direction === "incoming") return relationship.source;
+  return null;
+}
+
+export function filterEntityGraphMemories(graph, visibleMemoryIds) {
+  const visibleIds =
+    visibleMemoryIds instanceof Set
+      ? visibleMemoryIds
+      : new Set(visibleMemoryIds || []);
+  const unique = new Map();
+
+  for (const memory of graph?.memories || []) {
+    if (memory?.id && !unique.has(memory.id)) unique.set(memory.id, memory);
+  }
+
+  const memories = [...unique.values()];
+  const visible = memories.filter((memory) => visibleIds.has(memory.id));
+  return {
+    visible,
+    hidden: memories.length - visible.length,
+    total: memories.length,
+  };
+}
+
+export function buildEntitySpokes(graph, visibleMemoryIds) {
+  const { visible, hidden, total } = filterEntityGraphMemories(
+    graph,
+    visibleMemoryIds,
+  );
+  return {
+    spokes: visible.map((memory) => ({
+      id: `${graph.entity.id}:${memory.id}`,
+      entityId: graph.entity.id,
+      memoryId: memory.id,
+    })),
+    hidden,
+    total,
+  };
+}
+
+export function normalizeMemoryLinkResponse(
+  response,
+  selectedMemoryId,
+  limit = 5,
+) {
+  const normalizedLimit = Number.isInteger(limit) && limit > 0 ? limit : 5;
+  const selectedId = String(selectedMemoryId);
+  const seen = new Set();
+  const links = [];
+
+  for (const link of response?.links || []) {
+    const memoryId = link?.memory?.id;
+    if (memoryId == null) continue;
+
+    const id = String(memoryId);
+    if (id === selectedId || seen.has(id)) continue;
+    seen.add(id);
+
+    const score = Number(link.score);
+    const semanticSimilarity =
+      link.semanticSimilarity == null
+        ? null
+        : Number(link.semanticSimilarity);
+    links.push({
+      ...link,
+      score: Number.isFinite(score) ? clampUnit(score) : 0,
+      reasons: Array.isArray(link.reasons) ? link.reasons : [],
+      sharedEntities: Array.isArray(link.sharedEntities)
+        ? link.sharedEntities
+        : [],
+      sharedRelationships: Array.isArray(link.sharedRelationships)
+        ? link.sharedRelationships
+        : [],
+      semanticSimilarity: Number.isFinite(semanticSimilarity)
+        ? clampUnit(semanticSimilarity)
+        : null,
+    });
+
+    if (links.length === normalizedLimit) break;
+  }
+
+  return {
+    memoryId: response?.memoryId ?? selectedMemoryId,
+    links,
+    semanticAvailable: response?.semanticAvailable !== false,
+  };
+}
+
+export function filterMemoryLinksForVisibleMemories(
+  links,
+  visibleMemoryIds,
+  limit = 5,
+) {
+  const visibleIds =
+    visibleMemoryIds instanceof Set
+      ? visibleMemoryIds
+      : new Set(visibleMemoryIds || []);
+  const normalizedLimit = Number.isInteger(limit) && limit > 0 ? limit : 5;
+  const visible = [];
+
+  for (const link of links || []) {
+    if (!visibleIds.has(link?.memory?.id)) continue;
+    visible.push(link);
+    if (visible.length === normalizedLimit) break;
+  }
+
+  return visible;
+}
+
+export function pushNavigation(history, entry) {
+  const current = history.at(-1);
+  if (
+    current?.type === entry?.type &&
+    String(current?.id) === String(entry?.id)
+  ) {
+    return [...history];
+  }
+  return [...history, { ...entry }];
+}
+
+export function restoreNavigation(history, index) {
+  if (!Number.isInteger(index) || index < 0 || index >= history.length) {
+    return { history: [...history], current: null };
+  }
+  const restored = history.slice(0, index + 1).map((entry) => ({ ...entry }));
+  return { history: restored, current: restored.at(-1) };
+}
+
+function toVector(value) {
+  if (!Array.isArray(value) || value.length !== 3) return [0, 0, 0];
+  return value.map((coordinate) =>
+    Number.isFinite(Number(coordinate)) ? Number(coordinate) : 0,
+  );
+}
+
+function normalize(vector, fallback) {
+  const length = Math.hypot(...vector);
+  return length > 1e-9
+    ? vector.map((coordinate) => coordinate / length)
+    : [...fallback];
+}
+
+function getTangents(outward) {
+  const reference = Math.abs(outward[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0];
+  const tangentA = normalize(cross(outward, reference), [1, 0, 0]);
+  return [tangentA, normalize(cross(outward, tangentA), [0, 1, 0])];
+}
+
+function addVectors(...vectors) {
+  return [0, 1, 2].map((index) =>
+    vectors.reduce((sum, vector) => sum + vector[index], 0),
+  );
+}
+
+function scaleVector(vector, scale) {
+  return vector.map((coordinate) => coordinate * scale);
+}
+
+function cross(a, b) {
+  return [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0],
+  ];
+}
+
+function hashUnit(value) {
+  let hash = 2166136261;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0) / 4294967296;
+}
+
+function clampUnit(value) {
+  return Math.min(Math.max(value, 0), 1);
+}
+
+const BRAIN_RADIUS = 1.95;
+
+function clampToBrainBoundary(position) {
+  const length = Math.hypot(...position);
+  if (length <= BRAIN_RADIUS) return position;
+  const scale = BRAIN_RADIUS / length;
+  return position.map((v) => v * scale);
+}

package/src/shared/memory-placement.js

@@ -0,0 +1,171 @@
+import { getRegionAnchor } from "./region-anchors.js";
+
+const MIN_REGION_INSET = 0.34;
+const REGION_INSET_RANGE = 0.14;
+const MIN_TANGENT_OFFSET = 0.04;
+const TANGENT_OFFSET_RANGE = 0.14;
+
+export function getDominantRegion(regions) {
+  let dominant = null;
+
+  for (const activation of regions || []) {
+    if (
+      !getRegionAnchor(activation.region) ||
+      !Number.isFinite(activation.weight)
+    ) {
+      continue;
+    }
+
+    if (
+      !dominant ||
+      activation.weight > dominant.weight ||
+      (activation.weight === dominant.weight &&
+        activation.region.localeCompare(dominant.region) < 0)
+    ) {
+      dominant = activation;
+    }
+  }
+
+  return dominant?.region || null;
+}
+
+export function calculateMemoryPosition(memoryId, regions) {
+  const dominantRegion = getDominantRegion(regions);
+  const dominantActivation = (regions || []).find(
+    ({ region }) => region === dominantRegion,
+  );
+  return calculateRegionPosition(
+    memoryId,
+    dominantRegion,
+    getActivationAnchorPosition(dominantActivation),
+  );
+}
+
+export function calculateRegionPosition(memoryId, region, positionOverride) {
+  const anchor = getRegionAnchor(region);
+  if (!anchor) return null;
+  const anchorPosition = positionOverride || anchor.position;
+
+  const outward = normalize(anchorPosition);
+  const reference =
+    Math.abs(outward[1]) < 0.9 ? [0, 1, 0] : [1, 0, 0];
+  const tangentA = normalize(cross(outward, reference));
+  const tangentB = cross(outward, tangentA);
+
+  const angle = hashUnit(`${memoryId}:${region}:angle`) * Math.PI * 2;
+  const tangentDistance =
+    MIN_TANGENT_OFFSET +
+    hashUnit(`${memoryId}:${region}:distance`) * TANGENT_OFFSET_RANGE;
+  const inset =
+    MIN_REGION_INSET +
+    hashUnit(`${memoryId}:${region}:inset`) * REGION_INSET_RANGE;
+  const tangentX = Math.cos(angle) * tangentDistance;
+  const tangentY = Math.sin(angle) * tangentDistance;
+
+  const position = anchorPosition.map(
+    (coordinate, index) =>
+      coordinate +
+      outward[index] * -inset +
+      tangentA[index] * tangentX +
+      tangentB[index] * tangentY,
+  );
+
+  return clampToBrainBoundary(position);
+}
+
+function getActivationAnchorPosition(activation) {
+  if (activation?.region !== "hippocampus") return null;
+
+  const anchor = getRegionAnchor("hippocampus");
+  const { left, right } = activation.hemispheres || {};
+  const total = left + right;
+  if (
+    !anchor?.hemispherePositions
+    || !Number.isFinite(left)
+    || !Number.isFinite(right)
+    || total <= 0
+  ) {
+    return anchor?.position || null;
+  }
+
+  const leftShare = left / total;
+  const rightShare = right / total;
+  return anchor.hemispherePositions.left.map(
+    (coordinate, index) =>
+      coordinate * leftShare
+      + anchor.hemispherePositions.right[index] * rightShare,
+  );
+}
+
+export function createMemoryNodeState(memories) {
+  const state = new Map();
+
+  for (const memory of memories) {
+    const activations = (memory.regions || [])
+      .filter(
+        ({ region, weight }) =>
+          getRegionAnchor(region) && Number.isFinite(weight) && weight > 0,
+      )
+      .sort(
+        (a, b) => b.weight - a.weight || a.region.localeCompare(b.region),
+      );
+    const dominantRegion = activations[0]?.region;
+    if (!dominantRegion) continue;
+
+    const normalizedActivations = activations.map(
+      ({ region, weight, hemispheres }, index) => ({
+        region,
+        weight,
+        ...(hemispheres ? { hemispheres } : {}),
+        isDominant: index === 0,
+      }),
+    );
+
+    state.set(memory.id, {
+      core: {
+        region: dominantRegion,
+        weight: normalizedActivations[0].weight,
+        ...(normalizedActivations[0].hemispheres
+          ? { hemispheres: normalizedActivations[0].hemispheres }
+          : {}),
+        position: calculateMemoryPosition(memory.id, activations),
+      },
+      activations: normalizedActivations,
+    });
+  }
+
+  return state;
+}
+
+const BRAIN_RADIUS = 1.95;
+
+function clampToBrainBoundary(position) {
+  const length = Math.hypot(...position);
+  if (length <= BRAIN_RADIUS) return position;
+  const scale = BRAIN_RADIUS / length;
+  return position.map((v) => v * scale);
+}
+
+function hashUnit(value) {
+  let hash = 2166136261;
+
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 16777619);
+  }
+
+  return (hash >>> 0) / 4294967296;
+}
+
+function normalize(vector) {
+  const length = Math.hypot(...vector);
+  return vector.map((value) => value / length);
+}
+
+function cross(a, b) {
+  return [
+    a[1] * b[2] - a[2] * b[1],
+    a[2] * b[0] - a[0] * b[2],
+    a[0] * b[1] - a[1] * b[0],
+  ];
+}

package/src/shared/memory-search.js

@@ -0,0 +1,55 @@
+function normalizeSearchValue(value) {
+  return String(value || "").trim().toLocaleLowerCase();
+}
+
+function getEntitySearchValues(entity) {
+  return [
+    entity?.canonical_name,
+    entity?.canonicalName,
+    entity?.mention,
+  ];
+}
+
+export function matchesMemorySearch(memory, query) {
+  const terms = normalizeSearchValue(query).split(/\s+/).filter(Boolean);
+  if (!terms.length) return true;
+
+  const extractionEntities = memory.extraction?.entities || [];
+  const searchableText = normalizeSearchValue(
+    [
+      memory.text,
+      memory.summary,
+      ...(memory.entities || []).flatMap(getEntitySearchValues),
+      ...extractionEntities.flatMap(getEntitySearchValues),
+    ].join(" "),
+  );
+
+  return terms.every((term) => searchableText.includes(term));
+}
+
+export function filterMemoriesForSearch(
+  memories,
+  { query = "", source = "all", semanticIds = null } = {},
+) {
+  const sourceMatches = (memory) =>
+    source === "all" || memory.source === source;
+  const normalizedQuery = normalizeSearchValue(query);
+
+  if (!normalizedQuery) return memories.filter(sourceMatches);
+
+  if (Array.isArray(semanticIds)) {
+    const memoriesById = new Map(
+      memories.map((memory) => [String(memory.id), memory]),
+    );
+    return semanticIds
+      .map((id) => memoriesById.get(String(id)) || null)
+      .filter(
+        (memory) => memory !== null && memory !== undefined && sourceMatches(memory),
+      );
+  }
+
+  return memories.filter(
+    (memory) =>
+      sourceMatches(memory) && matchesMemorySearch(memory, normalizedQuery),
+  );
+}

package/src/shared/region-anchors.js

@@ -0,0 +1,112 @@
+export const REGION_COLORS = Object.freeze({
+  hippocampus: "#ffd38a",
+  prefrontal: "#FF7A90",
+  amygdala: "#ff8fa8",
+  temporalCortex: "#A78BFA",
+  parietalCortex: "#7ee8d3",
+  basalGanglia: "#8B7CFF",
+  cerebellum: "#7EE0B8",
+  motorCortex: "#F6B26B",
+  insula: "#e99fd1",
+  associationCortex: "#5B7CFF",
+  entorhinal: "#80d8d0",
+});
+
+export const REGION_ANCHORS = Object.freeze({
+  hippocampus: {
+    label: "Hippocampus",
+    role: "Binds events to their spatial and temporal context.",
+    position: [0, -0.85, 0.8],
+    // The calibrated brain model uses negative X for anatomical left.
+    hemispherePositions: {
+      left: [-0.93, -0.85, 0.8],
+      right: [0.93, -0.85, 0.8],
+    },
+    color: REGION_COLORS.hippocampus,
+    markerScale: 0.85,
+  },
+  prefrontal: {
+    label: "Prefrontal cortex",
+    role: "Supports active recall, planning, and working control.",
+    position: [0, 0.35, 2.28],
+    activationRadius: [1.15, 1.05, 0.78],
+    color: REGION_COLORS.prefrontal,
+    markerScale: 1.1,
+  },
+  associationCortex: {
+    label: "Association cortex",
+    role: "Integrates concepts across knowledge and sensory systems.",
+    position: [-1.25, 0.75, 0.85],
+    activationRadius: [0.95, 1.05, 1.05],
+    color: REGION_COLORS.associationCortex,
+    markerScale: 1.15,
+  },
+  temporalCortex: {
+    label: "Temporal cortex",
+    role: "Supports semantic knowledge and recognizable concepts.",
+    position: [1.72, -0.45, 0.35],
+    activationRadius: [0.62, 0.9, 1.12],
+    color: REGION_COLORS.temporalCortex,
+    markerScale: 1.1,
+  },
+  basalGanglia: {
+    label: "Basal ganglia",
+    role: "Supports learned routines, habits, and procedural patterns.",
+    position: [0.62, -0.12, 0.25],
+    activationRadius: [0.95, 0.82, 0.95],
+    color: REGION_COLORS.basalGanglia,
+    markerScale: 0.8,
+  },
+  cerebellum: {
+    label: "Cerebellum",
+    role: "Coordinates timing and precision in practiced movement.",
+    position: [0.45, -1.3, -1.15],
+    activationRadius: [1.28, 0.72, 1],
+    color: REGION_COLORS.cerebellum,
+    markerScale: 1.1,
+  },
+  motorCortex: {
+    label: "Motor cortex",
+    role: "Represents and plans physical actions.",
+    position: [1.15, 1.35, 0.05],
+    activationRadius: [0.72, 0.82, 1.05],
+    color: REGION_COLORS.motorCortex,
+    markerScale: 1,
+  },
+  amygdala: {
+    label: "Amygdala",
+    role: "Tags experiences with emotional salience.",
+    position: [0.82, -0.78, 0.72],
+    activationRadius: [0.82, 0.72, 0.82],
+    color: REGION_COLORS.amygdala,
+    markerScale: 0.72,
+  },
+  insula: {
+    label: "Insula",
+    role: "Represents internal feelings and bodily state.",
+    position: [1.48, 0.02, 0.48],
+    activationRadius: [0.7, 0.82, 0.82],
+    color: REGION_COLORS.insula,
+    markerScale: 0.9,
+  },
+  entorhinal: {
+    label: "Entorhinal cortex",
+    role: "Supports spatial context and navigation through memory.",
+    position: [1.08, -0.92, 0.18],
+    activationRadius: [0.82, 0.68, 0.88],
+    color: REGION_COLORS.entorhinal,
+    markerScale: 0.76,
+  },
+  parietalCortex: {
+    label: "Parietal cortex",
+    role: "Supports spatial attention and active information.",
+    position: [0.82, 1.3, -1.08],
+    activationRadius: [1.05, 0.82, 0.95],
+    color: REGION_COLORS.parietalCortex,
+    markerScale: 1.1,
+  },
+});
+
+export function getRegionAnchor(region) {
+  return REGION_ANCHORS[region];
+}