@inupedia/spotlight-memory

Optional exact + semantic answer-cache primitives for repeated deterministic requests.

This package is no longer wired into the Spotlight Server Agent lifecycle. The Server uses LangGraph Checkpointer for Thread state and LangGraph Store for explicit, user-approved long-term memory. It never semantically replays complete assistant answers.

Use this package only when an application explicitly needs an independently versioned response cache. A cache hit must not bypass Agent routing, Knowledge, authorization, or Tool execution.

Role

| Layer | Storage | Package API | |-------|---------|-------------| | L0 Exact | packs/<id>/memory/exact/ | ExactMemoryStore | | L1 Semantic | packs/<id>/memory/semantic/ (Phase 3) | findSemantic (MVP: bigram scan) | | Gate | — | createMemoryGate |

Install

pnpm add @inupedia/spotlight-memory @inupedia/spotlight-protocol

Legacy cache usage

import { createPackMemoryStores } from "@inupedia/spotlight-memory/node";

const { gate } = createPackMemoryStores({
  packsRoot: "/app/packs",
  projectId: "ydjm-construction-map",
  gateConfig: { semanticThreshold: 0.92 },
});

// Application-owned cache lookup. Do not place this before Agent routing.
const result = await gate.lookup({
  projectId,
  question: request.userQuestion,
  invalidation: {
    assetsVersion: assetsMeta.version,
    catalogVersion: catalogHash,
  },
});

// Cache only a deterministic, versioned artifact after independent validation.
await gate.write({
  projectId,
  question: request.userQuestion,
  kind: "qa_answer",
  answer: finalReply,
  invalidation: { assetsVersion, catalogVersion },
  confidence: 0.9,
  sourceRunId: run.id,
});

Exports

| Entry | Runtime | Purpose | |-------|---------|---------| | @inupedia/spotlight-memory | isomorphic | normalize, classify, gate factory | | @inupedia/spotlight-memory/node | Node | pack paths, exact jsonl store |

Build

pnpm install
pnpm build
pnpm test