@kinqs/brainrouter-types 0.3.4

package/README.md

@@ -0,0 +1,15 @@
+# @kinqs/brainrouter-types
+
+Shared TypeScript types for the [BrainRouter](https://github.com/kinqsradiollc/BrainRouter) monorepo — used by `brainrouter` (CLI), `@kinqs/brainrouter-mcp-server`, and `@kinqs/brainrouter-sdk`.
+
+No runtime code, just types.
+
+## Install
+
+```bash
+npm install --save-dev @kinqs/brainrouter-types
+```
+
+## License
+
+MIT

package/dist/api.d.ts

@@ -0,0 +1,251 @@
+import type { EvidenceKind, ContradictionRecord, DiagnosticsBundle, ImportResult, CognitiveRecord, ContextualFocusRecord, MemoryEvidence, MemoryExport, MemoryImport, MemoryOperation, MemoryStatus, RecallResult, SkillActivationRecord } from "./memory.js";
+import type { MemoryListItem } from "./store.js";
+import { PublicUserRecord } from "./memory.js";
+export interface SigninRequest {
+    email: string;
+    password?: string;
+}
+export interface SigninResponse {
+    jwt: string;
+    userId: string;
+    isAdmin: boolean;
+    displayName: string;
+    apiKey: string;
+}
+export interface SignupRequest {
+    email: string;
+    password?: string;
+    displayName?: string;
+}
+export interface SignupResponse {
+    jwt: string;
+    userId: string;
+    isAdmin: boolean;
+    displayName: string;
+}
+export interface MeResponse extends PublicUserRecord {
+    apiKey: string;
+    mcpPath?: string;
+}
+export interface UserStatusRequest {
+    status: "active" | "disabled";
+}
+export interface UserResetKeyResponse {
+    apiKey: string;
+}
+export interface CursorPaginationParams {
+    cursor?: string;
+    limit?: number;
+}
+export interface CursorPaginatedResponse<T> {
+    nextCursor: string | null;
+    limit: number;
+    hasMore: boolean;
+    data: T[];
+}
+export interface NamedCursorPaginatedResponse<T, K extends string> {
+    nextCursor: string | null;
+    limit: number;
+    hasMore: boolean;
+    [key: string]: T[] | string | number | boolean | null;
+}
+export interface MemoryStatsResponse {
+    total: number;
+    archived: number;
+    byType: Record<string, number>;
+    citationRate: number;
+    lastRecallAt: string | null;
+    extraction: unknown;
+}
+export type MemoriesResponse = {
+    memories: MemoryListItem[];
+    nextCursor: string | null;
+    limit: number;
+    hasMore: boolean;
+};
+export type OperationsResponse = {
+    operations: MemoryOperation[];
+    nextCursor: string | null;
+    limit: number;
+    hasMore: boolean;
+};
+export type EvidenceResponse = {
+    evidence: MemoryEvidence[];
+    nextCursor: string | null;
+    limit: number;
+    hasMore: boolean;
+};
+export type ScenesResponse = {
+    scenes: ContextualFocusRecord[];
+    nextCursor: string | null;
+    limit: number;
+    hasMore: boolean;
+};
+export type ContradictionsResponse = {
+    contradictions: ContradictionRecord[];
+    nextCursor: string | null;
+    limit: number;
+    hasMore: boolean;
+};
+export type DiagnosticsResponse = DiagnosticsBundle;
+export interface MemoryWithEvidenceResponse {
+    memory: CognitiveRecord;
+    evidence: MemoryEvidence[];
+}
+export interface MemoryEvidenceByRecordResponse {
+    evidence: MemoryEvidence[];
+    total?: number;
+}
+export interface UpdateMemoryRequest {
+    content?: string;
+    status?: MemoryStatus;
+    confidence?: number;
+    verificationStatus?: CognitiveRecord["verificationStatus"];
+    note?: string;
+}
+export interface AddEvidenceRequest {
+    kind: EvidenceKind;
+    ref: string;
+    excerpt?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface AddEvidenceResponse {
+    evidence: MemoryEvidence;
+}
+export interface ExplainRecallRequest {
+    query: string;
+    sessionKey?: string;
+    activeSkill?: string;
+    userId?: string;
+}
+export type ExplainRecallResponse = RecallResult;
+export interface WorkingStep {
+    nodeId: string;
+    title: string;
+    summary: string;
+    kind: string;
+    createdAt: string;
+    refPath?: string;
+    tokenEstimate: number;
+}
+export type TokenPressureLevel = "none" | "mild" | "aggressive";
+export interface WorkingMemoryState {
+    sessionKey: string;
+    workDir: string;
+    pressureLevel: TokenPressureLevel;
+    contextWindowTokens: number;
+    estimatedTokens: number;
+    injectedState: {
+        currentNode?: WorkingStep;
+        recentSteps: WorkingStep[];
+        refs: Array<{
+            nodeId: string;
+            refPath?: string;
+            title: string;
+        }>;
+        rawPayloadsIncluded: false;
+    };
+    updatedAt: string;
+}
+export interface WorkingContextRequest extends CursorPaginationParams {
+    workspacePath?: string;
+    userId?: string;
+    sessionKey: string;
+    nodeId?: string;
+    activeNodeId?: string;
+    contextWindowTokens?: number;
+    estimatedTokens?: number;
+}
+export interface WorkingContextResponse {
+    sessionKey: string;
+    workDir: string;
+    canvas: string;
+    annotatedCanvas?: string;
+    state: WorkingMemoryState;
+    steps: WorkingStep[];
+    ref?: {
+        nodeId: string;
+        path: string;
+        content: string;
+    };
+}
+export interface WorkingOffloadRequest {
+    workspacePath?: string;
+    userId?: string;
+    sessionKey: string;
+    payload: string;
+    title?: string;
+    summary?: string;
+    kind?: string;
+    contextWindowTokens?: number;
+    estimatedTokens?: number;
+    forceAggressive?: boolean;
+}
+export interface WorkingOffloadResponse {
+    nodeId: string;
+    refPath: string;
+    pressureLevel: TokenPressureLevel;
+    canvas: string;
+    state: WorkingMemoryState;
+}
+export interface WorkingResetRequest {
+    workspacePath?: string;
+    userId?: string;
+    sessionKey: string;
+}
+export interface WorkingResetResponse {
+    deleted: boolean;
+    workDir: string;
+}
+export type HostHookSource = "claude-code" | "codex" | "generic-mcp";
+export interface RegisteredHook {
+    id: string;
+    userId: string;
+    source: HostHookSource | string;
+    events: string[];
+    sessionKey?: string;
+    workspacePath?: string;
+    registeredAt: string;
+    lastSeenAt: string | null;
+    lastEvent: string | null;
+    metadata: Record<string, unknown>;
+}
+export interface HookRegisterRequest {
+    source: HostHookSource;
+    events?: string[];
+    userId?: string;
+    sessionKey?: string;
+    sessionId?: string;
+    workspacePath?: string;
+    event?: string;
+    payload?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+export interface HookRegisterResponse {
+    registered: RegisteredHook;
+    captureResult?: {
+        hookId: string;
+        l0RecordedCount: number;
+        l0RecordId: string;
+        flushedWorkingMemory: boolean;
+    };
+}
+export interface HookStatusParams {
+    source?: HostHookSource;
+    userId?: string;
+}
+export interface HookStatusResponse {
+    hooks: RegisteredHook[];
+}
+export type ExportMemoriesResponse = MemoryExport;
+export type ImportMemoriesRequest = MemoryImport;
+export type ImportMemoriesResponse = ImportResult;
+export interface ActiveSessionInfo {
+    sessionKey: string;
+    workspaceId: string;
+    updatedAt: string;
+}
+export interface ActiveSessionsResponse {
+    sessions: ActiveSessionInfo[];
+}
+export type SkillActivationsResponse = SkillActivationRecord[];

package/dist/api.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./memory.js";
+export * from "./store.js";
+export * from "./api.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./memory.js";
+export * from "./store.js";
+export * from "./api.js";

package/dist/memory.d.ts

@@ -0,0 +1,391 @@
+/**
+ * BrainRouter Memory Types
+ *
+ * Defines the types and boundaries for the BrainRouter memory engine.
+ * Inspired by the reference architecture but scoped explicitly for MCP + Multi-tenant.
+ */
+export interface BrainRouterMemoryContext {
+    /** User identifier — REQUIRED. Enables multi-tenant isolation. */
+    userId: string;
+    /** Session identifier (unique per conversation session). */
+    sessionKey: string;
+    /** Sub-session identifier (optional). */
+    sessionId?: string;
+    /** Which BrainRouter skill is currently active (if any) */
+    activeSkill?: string;
+}
+export interface SensoryRecord {
+    id: string;
+    userId: string;
+    sessionKey: string;
+    sessionId: string;
+    role: string;
+    messageText: string;
+    recordedAt: string;
+    timestamp: number;
+    skillTag: string;
+}
+export type MemoryType = "persona" | "episodic" | "instruction" | "skill_context" | "tool_preference" | "codebase_fact" | "api_contract" | "data_model" | "dependency_constraint" | "environment_constraint" | "architecture_decision" | "implementation_decision" | "design_constraint" | "security_policy" | "performance_baseline" | "bug_finding" | "debug_trace" | "fix_summary" | "verification_result" | "failed_attempt" | "regression_risk" | "task_state" | "handover_note" | "blocked_reason" | "review_comment" | "release_note" | "source_evidence" | "artifact_reference" | "file_history" | "command_knowledge";
+export type MemoryStatus = "active" | "superseded" | "archived" | "needs_verification";
+export type MemorySourceKind = "" | "user_instruction" | "source_file" | "command_output" | "test_result" | "model_inference" | "prior_memory";
+export type MemoryVerificationStatus = "" | "verified" | "unverified" | "stale";
+export type EvidenceKind = "file" | "command" | "url" | "test" | "benchmark" | "memory" | "other";
+export interface EvidenceRef {
+    kind: EvidenceKind;
+    ref: string;
+}
+export interface CognitiveRecord {
+    id: string;
+    userId: string;
+    sessionKey: string;
+    sessionId: string;
+    content: string;
+    type: MemoryType;
+    priority: number;
+    sceneName: string;
+    skillTag: string;
+    halfLifeDays: number | null;
+    supersededBy: string | null;
+    invalidAt?: string | null;
+    timestampStr: string;
+    timestampStart: string;
+    timestampEnd: string;
+    createdTime: string;
+    updatedTime: string;
+    metadata: Record<string, unknown>;
+    confidence: number;
+    status: MemoryStatus;
+    sourceKind: MemorySourceKind;
+    verificationStatus: MemoryVerificationStatus;
+    repoPaths: string[];
+    filePaths: string[];
+    commands: string[];
+    citationCount: number;
+    lastCitedAt: string | null;
+    neverCitedCount: number;
+    archived: boolean;
+}
+export interface MemoryEvidence {
+    id: string;
+    userId: string;
+    recordId: string;
+    kind: EvidenceKind;
+    ref: string;
+    excerpt: string;
+    observedAt: string;
+    metadata: Record<string, unknown>;
+}
+export interface MemoryOperation {
+    id: string;
+    userId: string;
+    recordId: string | null;
+    operation: string;
+    actor: string;
+    sessionKey: string;
+    reason: string;
+    createdAt: string;
+    metadata: Record<string, unknown>;
+}
+export interface MemoryExport {
+    version: 1;
+    exportedAt: string;
+    userId: string;
+    memories: CognitiveRecord[];
+    evidence: MemoryEvidence[];
+    operations: MemoryOperation[];
+}
+export interface MemoryImport {
+    version: 1;
+    memories: CognitiveRecord[];
+    evidence?: MemoryEvidence[];
+    operations?: MemoryOperation[];
+}
+export interface ImportResult {
+    importedMemories: number;
+    importedEvidence: number;
+    importedOperations: number;
+}
+export interface DiagnosticsBundle {
+    timestamp: string;
+    sqliteVersion: string;
+    nodeVersion: string;
+    databaseStats: {
+        userStats: {
+            total: number;
+            archived: number;
+            byType: Record<string, number>;
+            citationRate: number;
+            lastRecallAt: string | null;
+            extraction: ExtractionStatus;
+        };
+    };
+    envKeys: string[];
+    recentErrors: MemoryOperation[];
+}
+export interface VectorSearchResult {
+    record_id: string;
+    user_id: string;
+    content: string;
+    type: string;
+    priority: number;
+    scene_name: string;
+    skill_tag: string;
+    score: number;
+    timestamp_str: string;
+    timestamp_start: string;
+    timestamp_end: string;
+    session_key: string;
+    session_id: string;
+    metadata_json: string;
+    created_time: string;
+}
+export interface CognitiveFtsResult {
+    record_id: string;
+    user_id: string;
+    content: string;
+    type: string;
+    priority: number;
+    scene_name: string;
+    skill_tag: string;
+    score: number;
+    timestamp_str: string;
+    timestamp_start: string;
+    timestamp_end: string;
+    session_key: string;
+    session_id: string;
+    metadata_json: string;
+    created_time: string;
+    /** ACE feedback: number of times this memory was cited by the agent. */
+    citation_count?: number;
+}
+export interface RecalledMemory {
+    content: string;
+    score: number;
+    type: string;
+    recordId: string;
+    skillTag?: string;
+}
+export type MemoryTaskIntent = "build" | "debug" | "review" | "test" | "plan" | "refactor" | "security" | "performance" | "release";
+export interface RecallExplanation {
+    /** Number of FTS5 BM25 hits returned before RRF merge. */
+    ftsHits: number;
+    /** Number of vector search hits returned before RRF merge. */
+    vecHits: number;
+    /** Number of file-path expansion hits. */
+    filePathHits: number;
+    /** Top RRF fusion score (pre-decay). */
+    rrfTopScore: number;
+    /** Task intent detected from the query. */
+    intentDetected: MemoryTaskIntent | "none";
+    /** Memory types that received an intent boost (type → multiplier). */
+    typeBoosts: Record<string, number>;
+    /** Whether the active skill triggered a 1.2× skill boost. */
+    skillBoostApplied: boolean;
+    /** Whether the neural reranker was used in Stage 3. */
+    rerankerUsed: boolean;
+    /** Whether graph context expansion was appended. */
+    graphExpansion: boolean;
+    /** Per-record citation boost contribution (recordId → boost). */
+    citationBoosts: Record<string, number>;
+    /** Total recall pipeline duration in milliseconds. */
+    durationMs: number;
+    /** Number of candidates sent to reranker (pre-filter). */
+    rerankerCandidates: number;
+    /** Final ranked records (recordId → finalScore). */
+    scoredRecords: Array<{
+        recordId: string;
+        finalScore: number;
+        type: string;
+    }>;
+    /**
+     * Per-node trace of the neural-spark spreading activation pass.
+     *
+     * Each entry carries the node id, its final potential (clamped to [0, 1]),
+     * whether it crossed the firing threshold, and human-readable label fields
+     * so the UI can show "codebase_fact · the cli uses sqlite for…" instead of
+     * an opaque record id. The full id stays on the entry for click-through.
+     *
+     * Order is: initial seeds first (whether or not they fired), then propagated
+     * nodes that fired via 2-hop excitation.
+     */
+    sparkedNodes?: Array<{
+        id: string;
+        potential: number;
+        fired: boolean;
+        /** Memory type, e.g. "codebase_fact", "instruction". */
+        type?: string;
+        /** Optional short content preview (≤ 100 chars, single-line). */
+        preview?: string;
+        /** Optional focus-scene name the memory belongs to. */
+        sceneName?: string;
+    }>;
+}
+export interface RecallResult {
+    /** Cognitive relevant memories — prepended to user prompt text (dynamic, per-turn). */
+    prependContext?: string;
+    /** Stable recall context appended to system prompt (core identity, focus nav, tools guide). */
+    appendSystemContext?: string;
+    /** Recalled Cognitive memories with scores (for metrics/debugging). */
+    recalledCognitiveMemories?: RecalledMemory[];
+    /** Strategy used. Phase 1 = keyword. */
+    recallStrategy: string;
+    /** Core identity markdown (for metrics/debugging). */
+    coreIdentitySummary?: string;
+    /** Current most active focus scene name (for metrics/debugging). */
+    activeFocusName?: string;
+    /** Full recall pipeline explanation (populated in explain mode or always). */
+    recallExplanation?: RecallExplanation;
+}
+/**
+ * Outcome of the cognitive extraction step for a single capture call. Lets
+ * the CLI distinguish "the LLM said nothing notable here" (ok, zero records)
+ * from "the LLM call itself failed" (failed) from "extraction wasn't tried
+ * this turn" (skipped — below the every-N-turns threshold).
+ */
+export type CognitiveExtractionStatus = "ok" | "failed" | "skipped";
+export interface CaptureResult {
+    /** Number of Sensory messages recorded. */
+    sensoryRecordedCount: number;
+    /** Whether Cognitive extraction was triggered this turn. */
+    cognitiveExtractionTriggered: boolean;
+    /** Number of Cognitive memories extracted (if triggered). */
+    cognitiveExtractedCount: number;
+    /**
+     * Status of the extraction LLM call. `ok` means it ran and returned a
+     * (possibly empty) list of records. `failed` means the LLM call itself
+     * errored. `skipped` means we didn't try this turn. Callers should only
+     * surface a warning to the user on `failed`.
+     */
+    cognitiveExtractionStatus?: CognitiveExtractionStatus;
+    /** Error string when status === "failed", for diagnostic display. */
+    cognitiveExtractionError?: string;
+}
+export interface EmbeddingServiceConfig {
+    endpoint?: string;
+    apiKey?: string;
+    model?: string;
+    dimensions?: number;
+}
+export interface RerankerServiceConfig {
+    endpoint?: string;
+    apiKey?: string;
+    model?: string;
+    topN?: number;
+}
+export interface SkillHintsRecord {
+    skillName: string;
+    hints: string;
+    sourceFile: string;
+    registeredAt: string;
+}
+export interface SkillActivationRecord {
+    skillName: string;
+    potential: number;
+    lastDecayTime: string;
+}
+export interface UserRecord {
+    userId: string;
+    apiKey: string;
+    passwordHash: string | null;
+    displayName: string;
+    email: string;
+    isAdmin: boolean;
+    status: "active" | "disabled";
+    createdAt: string;
+}
+export interface PublicUserRecord {
+    userId: string;
+    displayName: string;
+    email: string;
+    isAdmin: boolean;
+    status: "active" | "disabled";
+    createdAt: string;
+}
+export interface LLMRunParams {
+    prompt: string;
+    systemPrompt?: string;
+    taskId: string;
+    timeoutMs?: number;
+}
+export interface LLMRunner {
+    run(params: LLMRunParams): Promise<string>;
+}
+export interface ContextualFocusRecord {
+    id: string;
+    userId: string;
+    sceneName: string;
+    summaryMd: string;
+    heatScore: number;
+    lastActiveTime: string;
+    createdTime: string;
+    updatedTime: string;
+}
+export interface CoreIdentityRecord {
+    userId: string;
+    personaMd: string;
+    cognitiveCountAtGeneration: number;
+    createdTime: string;
+    updatedTime: string;
+}
+export interface ContradictionRecord {
+    id: string;
+    user_id?: string;
+    userId?: string;
+    record_id_a?: string;
+    recordIdA?: string;
+    record_id_b?: string;
+    recordIdB?: string;
+    reason: string;
+    confidence: number;
+    status?: "pending" | "resolved" | "dismissed";
+    created_time?: string;
+    createdTime?: string;
+    content_a?: string;
+    contentA?: string;
+    content_b?: string;
+    contentB?: string;
+}
+export interface SchedulerState {
+    cognitiveCountSinceLastFocus: number;
+    cognitiveCountSinceLastIdentity: number;
+    totalCognitiveCount: number;
+    extractionErrors: number;
+    lastErrorMessage: string | null;
+    lastErrorAt: string | null;
+}
+export interface StalledExtractionBacklog {
+    userId: string;
+    sessionKey: string;
+    sessionId: string;
+    unextractedCount: number;
+    latestRecordedAt: string;
+    extractionErrors: number;
+    lastErrorMessage: string | null;
+}
+export interface ExtractionStatus {
+    extractionErrors: number;
+    lastErrorMessage: string | null;
+    lastErrorAt: string | null;
+    syncPaused: boolean;
+}
+export interface GraphNode {
+    id: string;
+    userId: string;
+    entity: string;
+    entityType: string;
+    skillTag: string;
+    confidence: number;
+    sourceRecordId: string;
+    createdTime: string;
+}
+export interface GraphEdge {
+    id: string;
+    userId: string;
+    fromNodeId: string;
+    toNodeId: string;
+    relation: string;
+    skillTag: string;
+    confidence: number;
+    sourceRecordId: string;
+    createdTime: string;
+}

package/dist/memory.js

@@ -0,0 +1,7 @@
+/**
+ * BrainRouter Memory Types
+ *
+ * Defines the types and boundaries for the BrainRouter memory engine.
+ * Inspired by the reference architecture but scoped explicitly for MCP + Multi-tenant.
+ */
+export {};

package/dist/store.d.ts

@@ -0,0 +1,195 @@
+import type { GraphEdge, GraphNode, ContradictionRecord, ImportResult, SensoryRecord, CognitiveFtsResult, CognitiveRecord, ContextualFocusRecord, CoreIdentityRecord, MemoryEvidence, MemoryExport, MemoryImport, ExtractionStatus, MemoryOperation, MemoryStatus, SchedulerState, SkillActivationRecord, SkillHintsRecord, StalledExtractionBacklog, UserRecord, VectorSearchResult } from "./memory.js";
+export interface CursorPaginationOptions<TCursor = Record<string, unknown>> {
+    cursor?: TCursor;
+    limit: number;
+}
+export interface CursorPage<T> {
+    items: T[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+export interface MemoryListFilters {
+    query?: string;
+    type?: string;
+    scene?: string;
+    skill?: string;
+    archived?: boolean;
+}
+export interface MemoryListItem {
+    recordId: string;
+    content: string;
+    type: string;
+    priority: number;
+    sceneName: string;
+    skillTag: string;
+    createdTime: string;
+    citationCount: number;
+    neverCitedCount: number;
+    archived: boolean;
+}
+export interface EvidenceListFilters {
+    recordId?: string;
+    kind?: string;
+}
+export interface OperationLogFilters {
+    operation?: string;
+    sessionKey?: string;
+    createdAfter?: string;
+    createdBefore?: string;
+}
+export interface IMemoryStore {
+    init(): void;
+    initVec(dimensions: number): void;
+    reembedStaleRecords(embedder: (text: string) => Promise<Float32Array>): Promise<number>;
+    getSqliteVersion(): string;
+    upsertSensory(record: SensoryRecord): void;
+    getRecentSensoryMessages(userId: string, sessionKey: string, limit: number, afterIsoTime?: string): SensoryRecord[];
+    getUnextractedSensoryCount(userId: string, sessionKey: string): number;
+    markSensoryExtracted(userId: string, sessionKey: string, recordIds: string[], extractedAt?: string): void;
+    upsertCognitive(record: CognitiveRecord, options?: {
+        skipAudit?: boolean;
+    }): void;
+    /** Batch upsert with optional embedding vectors. Pass skipAudit to suppress per-record
+     * cognitive_upsert noise when the caller will write a higher-level audit entry itself. */
+    upsertCognitiveBatch(entries: Array<{
+        record: CognitiveRecord;
+        embedding?: Float32Array;
+    }>, options?: {
+        skipAudit?: boolean;
+    }): void;
+    invalidateCognitiveRecord(userId: string, recordId: string, supersededById: string): void;
+    getMemoryById(userId: string, recordId: string): CognitiveRecord | null;
+    getMemoriesByFilePath(userId: string, filePath: string, limit: number): CognitiveRecord[];
+    updateCognitiveConfidence(userId: string, recordId: string, confidence: number, status: MemoryStatus): void;
+    insertEvidence(ev: MemoryEvidence): void;
+    getEvidenceByRecord(userId: string, recordId: string): MemoryEvidence[];
+    listEvidence(userId: string, filters?: EvidenceListFilters, pagination?: CursorPaginationOptions<{
+        observedAt: string;
+        id: string;
+    }>): MemoryEvidence[];
+    /** Write an audit operation. Kept on the interface because the engine layer needs to
+     * correlate external events (memory_update, import) with store writes atomically.
+     * It is NOT intended for use by any caller outside of SqliteMemoryStore or MemoryEngine. */
+    insertOperation(op: MemoryOperation): void;
+    getOperationLog(userId: string, options?: CursorPaginationOptions<{
+        createdAt: string;
+        id: string;
+    }>, filters?: OperationLogFilters): MemoryOperation[];
+    exportMemories(userId: string): MemoryExport;
+    importMemories(userId: string, data: MemoryImport): ImportResult;
+    hardDeleteMemory(userId: string, recordId: string, reason: string): void;
+    searchCognitiveFts(userId: string, query: string, limit: number): CognitiveFtsResult[];
+    searchCognitiveFtsAsOf(userId: string, query: string, limit: number, asOf: string): CognitiveFtsResult[];
+    upsertCognitiveVec(recordId: string, embedding: Float32Array): void;
+    searchCognitiveVec(userId: string, queryEmbedding: Float32Array, limit: number): VectorSearchResult[];
+    upsertContradiction(data: {
+        id: string;
+        userId: string;
+        recordIdA: string;
+        recordIdB: string;
+        reason: string;
+        confidence: number;
+        createdTime?: string;
+    }): void;
+    getPendingContradictions(userId: string, pagination?: CursorPaginationOptions<{
+        confidence: number;
+        id: string;
+    }>): ContradictionRecord[];
+    resolveContradiction(id: string, userId: string, status: "resolved" | "dismissed"): void;
+    upsertSkillHints(skillName: string, hints: string, sourceFile?: string): void;
+    listSkillHints(): SkillHintsRecord[];
+    getSkillHints(skillName: string): string | null;
+    getSkillActivations(userId: string): SkillActivationRecord[];
+    upsertSkillActivations(userId: string, activations: SkillActivationRecord[]): void;
+    upsertContextualFocus(record: ContextualFocusRecord): void;
+    getTopContextualFocus(userId: string, limit?: number, cursor?: {
+        heatScore: number;
+        id: string;
+    }): ContextualFocusRecord[];
+    decayContextualFocusHeatScores(userId: string, decayFactor?: number): void;
+    boostContextualFocusHeatScore(userId: string, sceneName: string, boost?: number): void;
+    getCognitivesByFocus(userId: string, sceneName: string, limit?: number): any[];
+    getContextualFocusCount(userId: string): number;
+    getColdContextualFocus(userId: string, limit: number): ContextualFocusRecord[];
+    deleteContextualFocus(userId: string, sceneIds: string[]): void;
+    getContextualFocusByName(userId: string, sceneName: string): ContextualFocusRecord | null;
+    getDistinctSceneNames(userId: string): string[];
+    renameFocusInCognitiveRecords(userId: string, oldName: string, canonicalName: string): void;
+    upsertCoreIdentity(record: CoreIdentityRecord): void;
+    getCoreIdentity(userId: string): CoreIdentityRecord | null;
+    getIdentityAndInstructionCognitives(userId: string, limit?: number): any[];
+    getSchedulerState(userId: string): SchedulerState;
+    incrementSchedulerCognitiveCount(userId: string, count: number): void;
+    resetSchedulerFocusCount(userId: string): void;
+    resetSchedulerIdentityCount(userId: string): void;
+    recordExtractionFailure(userId: string, message: string): void;
+    resetExtractionFailures(userId: string): void;
+    getExtractionStatus(userId: string): ExtractionStatus;
+    sweepUnextractedBacklog(options: {
+        olderThanMs: number;
+        minUnextracted?: number;
+        maxFailures?: number;
+        limit?: number;
+    }): StalledExtractionBacklog[];
+    getAllGraphNodes(userId: string): GraphNode[];
+    upsertGraphNode(node: GraphNode): void;
+    upsertGraphEdge(edge: GraphEdge): void;
+    getGraphNodeByEntity(userId: string, entity: string): GraphNode | null;
+    getGraphNeighbors(userId: string, entityId: string, skillTag?: string, maxHops?: number): {
+        nodes: GraphNode[];
+        edges: GraphEdge[];
+    };
+    markCited(userId: string, recordIds: string[]): void;
+    incrementNeverCited(userId: string, recordIds: string[]): {
+        recordId: string;
+        neverCitedCount: number;
+    }[];
+    archiveCognitiveRecord(userId: string, recordId: string): void;
+    getRecentSkillContextCognitives(userId: string, limit: number): {
+        skillTag: string;
+        createdTime: string;
+    }[];
+    createUser(userId: string, apiKey: string, displayName?: string, isAdmin?: boolean): UserRecord;
+    getUserByApiKey(apiKey: string): UserRecord | null;
+    getUserByEmail(email: string): UserRecord | null;
+    getUserById(userId: string): UserRecord | null;
+    updateUserPassword(userId: string, passwordHash: string): void;
+    updateUserEmail(userId: string, email: string): void;
+    updateUserDisplayName(userId: string, displayName: string): void;
+    updateUserStatus(userId: string, status: "active" | "disabled"): void;
+    updateUserApiKey(userId: string, apiKey: string): void;
+    listUsers(pagination?: CursorPaginationOptions<{
+        createdAt: string;
+        userId: string;
+    }>): UserRecord[];
+    deleteUser(userId: string): void;
+    listMemories(userId: string, filters?: MemoryListFilters, pagination?: CursorPaginationOptions<{
+        createdTime: string;
+        recordId: string;
+    }>): MemoryListItem[];
+    getMemoryStats(userId: string): {
+        total: number;
+        archived: number;
+        byType: Record<string, number>;
+        citationRate: number;
+        lastRecallAt: string | null;
+        extraction: ExtractionStatus;
+    };
+    upsertConnection(userId: string, sourceId: string, targetId: string, weight: number): void;
+    getConnectionsForSource(userId: string, sourceId: string): Array<{
+        targetId: string;
+        weight: number;
+    }>;
+    strengthenConnectionsBatch(userId: string, pairs: Array<{
+        source: string;
+        target: string;
+    }>, delta: number): void;
+    decayConnections(userId: string, decayFactor: number): void;
+    pruneConnections(userId: string, threshold: number): void;
+    getAllConnections(userId: string): Array<{
+        sourceId: string;
+        targetId: string;
+        weight: number;
+        lastActivatedAt: string;
+    }>;
+}

package/dist/store.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@kinqs/brainrouter-types",
+  "version": "0.3.4",
+  "description": "Shared TypeScript types for BrainRouter — used by the CLI, MCP server, and SDK.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4"
+  },
+  "keywords": [
+    "brainrouter",
+    "types",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "BrainRouter contributors",
+  "homepage": "https://github.com/kinqsradiollc/BrainRouter#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kinqsradiollc/BrainRouter.git",
+    "directory": "packages/types"
+  },
+  "bugs": {
+    "url": "https://github.com/kinqsradiollc/BrainRouter/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}