@mnexium/core 0.1.0

package/src/contracts/storage.ts

@@ -0,0 +1,137 @@
+import type {
+  Claim,
+  ClaimAssertion,
+  ClaimEdge,
+  Memory,
+  MemoryRecallEvent,
+  MemoryRecallStats,
+  ResolvedTruthSlot,
+} from "./types";
+
+export interface CreateMemoryInput {
+  id: string;
+  project_id: string;
+  subject_id: string;
+  text: string;
+  kind?: Memory["kind"];
+  visibility?: Memory["visibility"];
+  importance?: number;
+  confidence?: number;
+  is_temporal?: boolean;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+  source_type?: string;
+  embedding?: number[] | null;
+}
+
+export interface UpdateMemoryInput {
+  text?: string;
+  kind?: Memory["kind"];
+  visibility?: Memory["visibility"];
+  importance?: number;
+  confidence?: number;
+  is_temporal?: boolean;
+  tags?: string[];
+  metadata?: Record<string, unknown>;
+  embedding?: number[] | null;
+}
+
+export interface CreateClaimInput {
+  claim_id: string;
+  project_id: string;
+  subject_id: string;
+  predicate: string;
+  object_value: string;
+  slot?: string;
+  claim_type?: string;
+  confidence?: number;
+  importance?: number;
+  tags?: string[];
+  source_memory_id?: string | null;
+  source_observation_id?: string | null;
+  subject_entity?: string;
+  valid_from?: string | null;
+  valid_until?: string | null;
+  embedding?: number[] | null;
+}
+
+export interface CoreStore {
+  listMemories(args: {
+    project_id: string;
+    subject_id: string;
+    limit: number;
+    offset: number;
+    include_deleted?: boolean;
+    include_superseded?: boolean;
+  }): Promise<Memory[]>;
+  searchMemories(args: {
+    project_id: string;
+    subject_id: string;
+    q: string;
+    query_embedding: number[] | null;
+    limit: number;
+    min_score: number;
+  }): Promise<Array<Memory & { score: number; effective_score: number }>>;
+  createMemory(input: CreateMemoryInput): Promise<Memory>;
+  getMemory(args: { project_id: string; id: string }): Promise<Memory | null>;
+  getMemoryClaims(args: { project_id: string; memory_id: string }): Promise<ClaimAssertion[]>;
+  updateMemory(args: { project_id: string; id: string; patch: UpdateMemoryInput }): Promise<Memory | null>;
+  deleteMemory(args: { project_id: string; id: string }): Promise<{ ok: true; deleted: boolean }>;
+  listSupersededMemories(args: {
+    project_id: string;
+    subject_id: string;
+    limit: number;
+    offset: number;
+  }): Promise<Memory[]>;
+  restoreMemory(args: { project_id: string; id: string }): Promise<Memory | null>;
+  findDuplicateMemory?(args: {
+    project_id: string;
+    subject_id: string;
+    embedding: number[];
+    threshold: number;
+  }): Promise<{ id: string; similarity: number } | null>;
+  findConflictingMemories?(args: {
+    project_id: string;
+    subject_id: string;
+    embedding: number[];
+    min_similarity: number;
+    max_similarity: number;
+    limit: number;
+  }): Promise<Array<{ id: string; similarity: number }>>;
+  supersedeMemories?(args: {
+    project_id: string;
+    subject_id: string;
+    memory_ids: string[];
+    superseded_by: string;
+  }): Promise<number>;
+
+  getRecallEventsByChat(args: { project_id: string; chat_id: string }): Promise<MemoryRecallEvent[]>;
+  getRecallEventsByMemory(args: { project_id: string; memory_id: string; limit: number }): Promise<MemoryRecallEvent[]>;
+  getMemoryRecallStats(args: { project_id: string; memory_id: string }): Promise<MemoryRecallStats>;
+
+  createClaim(input: CreateClaimInput): Promise<Claim>;
+  getClaim(args: { project_id: string; claim_id: string }): Promise<Claim | null>;
+  getAssertionsForClaim(args: { project_id: string; claim_id: string }): Promise<ClaimAssertion[]>;
+  getEdgesForClaim(args: { project_id: string; claim_id: string }): Promise<ClaimEdge[]>;
+  getCurrentTruth(args: { project_id: string; subject_id: string }): Promise<ResolvedTruthSlot[]>;
+  getCurrentSlot(args: { project_id: string; subject_id: string; slot: string }): Promise<ResolvedTruthSlot | null>;
+  getSlots(args: { project_id: string; subject_id: string; limit: number }): Promise<Array<ResolvedTruthSlot & { status: string }>>;
+  getClaimGraph(args: { project_id: string; subject_id: string; limit: number }): Promise<{ claims: Claim[]; edges: ClaimEdge[] }>;
+  getClaimHistory(args: {
+    project_id: string;
+    subject_id: string;
+    slot?: string | null;
+    limit: number;
+  }): Promise<{ claims: Claim[]; edges: ClaimEdge[]; by_slot: Record<string, Claim[]> }>;
+  retractClaim(args: {
+    project_id: string;
+    claim_id: string;
+    reason: string;
+  }): Promise<{
+    success: boolean;
+    claim_id: string;
+    slot: string;
+    previous_claim_id: string | null;
+    restored_previous: boolean;
+  }>;
+}

package/src/contracts/types.ts

@@ -0,0 +1,138 @@
+export type Json =
+  | null
+  | boolean
+  | number
+  | string
+  | Json[]
+  | { [key: string]: Json };
+
+export type MemoryStatus = "active" | "superseded";
+export type ClaimStatus = "active" | "retracted";
+export type SlotStatus = "active" | "superseded" | "retracted";
+export type ClaimEdgeType = "supersedes" | "supports" | "duplicates" | "related" | "retracts";
+
+export interface Memory {
+  id: string;
+  project_id: string;
+  subject_id: string;
+  text: string;
+  kind: "fact" | "preference" | "context" | "note" | "event" | "trait";
+  visibility: "private" | "shared" | "public";
+  importance: number;
+  confidence: number;
+  is_temporal: boolean;
+  tags: string[];
+  metadata: Record<string, Json>;
+  status: MemoryStatus;
+  superseded_by: string | null;
+  is_deleted: boolean;
+  source_type: string;
+  created_at: string;
+  updated_at: string;
+  last_seen_at: string | null;
+  seen_count: number;
+  reinforcement_count: number;
+  last_reinforced_at: string | null;
+}
+
+export interface Claim {
+  claim_id: string;
+  project_id: string;
+  subject_id: string;
+  predicate: string;
+  object_value: string;
+  slot: string;
+  claim_type: string;
+  confidence: number;
+  importance: number;
+  tags: string[];
+  source_memory_id: string | null;
+  source_observation_id: string | null;
+  subject_entity: string;
+  status: ClaimStatus;
+  asserted_at: string;
+  updated_at: string;
+  retracted_at: string | null;
+  retract_reason: string | null;
+  valid_from: string | null;
+  valid_until: string | null;
+}
+
+export interface ClaimAssertion {
+  assertion_id: string;
+  project_id: string;
+  subject_id: string;
+  claim_id: string;
+  memory_id: string | null;
+  predicate: string;
+  object_type: "string" | "number" | "date" | "json";
+  value_string: string | null;
+  value_number: number | null;
+  value_date: string | null;
+  value_json: Json | null;
+  confidence: number;
+  status: string;
+  first_seen_at: string;
+  last_seen_at: string;
+}
+
+export interface ClaimEdge {
+  edge_id: number;
+  project_id: string;
+  subject_id: string;
+  from_claim_id: string;
+  to_claim_id: string;
+  edge_type: ClaimEdgeType;
+  weight: number;
+  reason_code: string | null;
+  reason_text: string | null;
+  created_at: string;
+}
+
+export interface SlotState {
+  project_id: string;
+  subject_id: string;
+  slot: string;
+  active_claim_id: string | null;
+  status: SlotStatus;
+  replaced_by_claim_id: string | null;
+  updated_at: string;
+}
+
+export interface ResolvedTruthSlot {
+  slot: string;
+  active_claim_id: string;
+  predicate: string;
+  object_value: string;
+  claim_type: string;
+  confidence: number;
+  tags: string[];
+  updated_at: string;
+  source_memory_id: string | null;
+  source_observation_id: string | null;
+}
+
+export interface MemoryRecallEvent {
+  event_id: string;
+  project_id: string;
+  subject_id: string;
+  memory_id: string;
+  memory_text: string;
+  chat_id: string;
+  message_index: number;
+  chat_logged: boolean;
+  similarity_score: number;
+  request_type: string;
+  model: string;
+  metadata: Record<string, Json>;
+  recalled_at: string;
+}
+
+export interface MemoryRecallStats {
+  total_recalls: number;
+  unique_chats: number;
+  unique_subjects: number;
+  avg_score: number;
+  first_recalled_at: string | null;
+  last_recalled_at: string | null;
+}

package/src/dev.ts

@@ -0,0 +1,144 @@
+import "dotenv/config";
+import { Pool } from "pg";
+import { createCoreServer } from "./server/createCoreServer";
+import { PostgresCoreStore } from "./adapters/postgres/PostgresCoreStore";
+import { createOpenAIEmbedder } from "./providers/openaiEmbedding";
+import { createCerebrasClient } from "./providers/cerebras";
+import { createOpenAIChatClient } from "./providers/openaiChat";
+import { createLLMRecallService, createSimpleRecallService } from "./ai/recallService";
+import { createLLMMemoryExtractionService, createSimpleMemoryExtractionService } from "./ai/memoryExtractionService";
+import type { JsonLlmClient } from "./ai/types";
+
+function envFlag(raw: string | undefined, fallback = false): boolean {
+  const v = String(raw ?? "").trim().toLowerCase();
+  if (!v) return fallback;
+  if (["1", "true", "yes", "on"].includes(v)) return true;
+  if (["0", "false", "no", "off"].includes(v)) return false;
+  return fallback;
+}
+
+function toErrorMessage(err: unknown): string {
+  if (!err) return "unknown_error";
+  if (typeof err === "string") return err;
+  if (err instanceof AggregateError && Array.isArray(err.errors) && err.errors.length > 0) {
+    return `AggregateError: ${err.errors.map((e) => toErrorMessage(e)).join(" | ")}`;
+  }
+  if (typeof err === "object" && err && Array.isArray((err as any).errors) && (err as any).errors.length > 0) {
+    return `AggregateError: ${(err as any).errors.map((e: unknown) => toErrorMessage(e)).join(" | ")}`;
+  }
+  if (typeof err === "object" && err && (err as any).cause) {
+    return `${String((err as any).message || err)} (cause: ${toErrorMessage((err as any).cause)})`;
+  }
+  return String((err as any)?.message || err);
+}
+
+const required = ["POSTGRES_HOST", "POSTGRES_DB", "POSTGRES_USER", "POSTGRES_PASSWORD"];
+for (const key of required) {
+  if (!process.env[key]) {
+    throw new Error(`Missing env var: ${key}`);
+  }
+}
+
+const pool = new Pool({
+  host: process.env.POSTGRES_HOST,
+  port: Number(process.env.POSTGRES_PORT || 5432),
+  database: process.env.POSTGRES_DB,
+  user: process.env.POSTGRES_USER,
+  password: process.env.POSTGRES_PASSWORD,
+});
+
+const store = new PostgresCoreStore(pool);
+const embed = createOpenAIEmbedder({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: process.env.OPENAI_EMBED_MODEL || "text-embedding-3-small",
+});
+
+const configuredAiMode = String(process.env.CORE_AI_MODE || "auto").trim().toLowerCase();
+const cerebrasApiKey = String(process.env.CEREBRAS_API || "").trim();
+const openaiApiKey = String(process.env.OPENAI_API_KEY || "").trim();
+const retrievalModel = String(process.env.RETRIEVAL_MODEL || "").trim();
+const useRetrievalExpand = envFlag(process.env.USE_RETRIEVAL_EXPAND, true);
+const debugEnabled = envFlag(process.env.CORE_DEBUG, false);
+
+let llmClient: JsonLlmClient | null = null;
+let resolvedAiMode: "cerebras" | "openai" | "simple" = "simple";
+
+const wantCerebras = configuredAiMode === "cerebras" || configuredAiMode === "auto";
+const wantOpenAI = configuredAiMode === "openai" || configuredAiMode === "auto";
+const wantSimple = configuredAiMode === "simple";
+
+if (wantCerebras && cerebrasApiKey) {
+  llmClient = createCerebrasClient({
+    apiKey: cerebrasApiKey,
+    model: retrievalModel || "gpt-oss-120b",
+  });
+  resolvedAiMode = "cerebras";
+} else if (wantOpenAI && openaiApiKey) {
+  llmClient = createOpenAIChatClient({
+    apiKey: openaiApiKey,
+    model: retrievalModel || "gpt-4o-mini",
+  });
+  resolvedAiMode = "openai";
+} else if (wantSimple || configuredAiMode === "auto") {
+  llmClient = null;
+  resolvedAiMode = "simple";
+}
+
+if (configuredAiMode === "cerebras" && !cerebrasApiKey) {
+  console.warn("[core] CORE_AI_MODE=cerebras but CEREBRAS_API is missing; falling back to simple mode.");
+}
+if (configuredAiMode === "openai" && !openaiApiKey) {
+  console.warn("[core] CORE_AI_MODE=openai but OPENAI_API_KEY is missing; falling back to simple mode.");
+}
+
+const recallService = llmClient
+  ? (useRetrievalExpand
+      ? createLLMRecallService({
+          store,
+          embed,
+          llm: llmClient,
+        })
+      : createSimpleRecallService({
+          store,
+          embed,
+        }))
+  : createSimpleRecallService({
+      store,
+      embed,
+    });
+
+const memoryExtractionService = llmClient
+  ? createLLMMemoryExtractionService({
+      llm: llmClient,
+    })
+  : createSimpleMemoryExtractionService();
+
+const server = createCoreServer({
+  store,
+  defaultProjectId: process.env.CORE_DEFAULT_PROJECT_ID || "default-project",
+  embed,
+  recallService,
+  memoryExtractionService,
+  debug: debugEnabled,
+});
+
+const port = Number(process.env.PORT || 8080);
+server.listen(port, () => {
+  const model = llmClient?.model ? ` (${llmClient.provider}:${llmClient.model})` : "";
+  console.log(
+    `[core] postgres target: ${process.env.POSTGRES_HOST}:${Number(process.env.POSTGRES_PORT || 5432)}/${process.env.POSTGRES_DB} user=${process.env.POSTGRES_USER}`,
+  );
+  console.log(`[core] ai mode: ${resolvedAiMode}${model}`);
+  console.log(`[core] retrieval expand: ${useRetrievalExpand ? "enabled" : "disabled (simple mode)"}`);
+  console.log(`[core] debug: ${debugEnabled ? "enabled" : "disabled"}`);
+  console.log(`[core] listening on http://localhost:${port}`);
+});
+
+void pool
+  .query("select 1 as ok")
+  .then(() => {
+    console.log("[core] postgres connectivity check: ok");
+  })
+  .catch((err) => {
+    console.warn(`[core] postgres connectivity check failed: ${toErrorMessage(err)}`);
+  });

package/src/index.ts

@@ -0,0 +1,15 @@
+export { PostgresCoreStore } from "./adapters/postgres/PostgresCoreStore";
+export { createCoreServer } from "./server/createCoreServer";
+export type { CreateCoreServerOptions } from "./server/createCoreServer";
+export { createOpenAIEmbedder } from "./providers/openaiEmbedding";
+export { createCerebrasClient } from "./providers/cerebras";
+export { createOpenAIChatClient } from "./providers/openaiChat";
+export { createLLMRecallService, createSimpleRecallService, createCerebrasRecallService } from "./ai/recallService";
+export {
+  createLLMMemoryExtractionService,
+  createSimpleMemoryExtractionService,
+  createCerebrasMemoryExtractionService,
+} from "./ai/memoryExtractionService";
+export type { JsonLlmClient } from "./ai/types";
+export type * from "./contracts/types";
+export type * from "./contracts/storage";

package/src/providers/cerebras.ts

@@ -0,0 +1,101 @@
+const CEREBRAS_API_URL = "https://api.cerebras.ai/v1/chat/completions";
+const DEFAULT_MODEL = "gpt-oss-120b";
+
+export interface CerebrasClientOptions {
+  apiKey?: string;
+  model?: string;
+}
+
+export interface CerebrasCallOptions {
+  systemPrompt: string;
+  userPrompt: string;
+  jsonMode?: boolean;
+  timeoutMs?: number;
+  temperature?: number;
+}
+
+export interface CerebrasClient {
+  provider: "cerebras";
+  callRaw: (opts: {
+    messages: Array<{ role: string; content: string }>;
+    jsonMode?: boolean;
+    timeoutMs?: number;
+    temperature?: number;
+  }) => Promise<any>;
+  call: (opts: CerebrasCallOptions) => Promise<any | null>;
+  model: string;
+}
+
+export function createCerebrasClient(options: CerebrasClientOptions = {}): CerebrasClient {
+  const apiKey = String(options.apiKey || process.env.CEREBRAS_API || "").trim();
+  const model = String(options.model || process.env.RETRIEVAL_MODEL || DEFAULT_MODEL).trim();
+
+  async function callRaw(opts: {
+    messages: Array<{ role: string; content: string }>;
+    jsonMode?: boolean;
+    timeoutMs?: number;
+    temperature?: number;
+  }): Promise<any> {
+    if (!apiKey) {
+      throw new Error("[core:cerebras] CEREBRAS_API env var is not set");
+    }
+
+    const body: Record<string, unknown> = {
+      model,
+      stream: false,
+      messages: opts.messages,
+      temperature: Number.isFinite(Number(opts.temperature)) ? Number(opts.temperature) : 0,
+      max_tokens: -1,
+      seed: 0,
+      top_p: 1,
+    };
+    if (opts.jsonMode !== false) {
+      body.response_format = { type: "json_object" };
+    }
+
+    const fetchOptions: RequestInit = {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify(body),
+    };
+    if (opts.timeoutMs && typeof AbortSignal.timeout === "function") {
+      fetchOptions.signal = AbortSignal.timeout(opts.timeoutMs);
+    }
+
+    const res = await fetch(CEREBRAS_API_URL, fetchOptions);
+    if (!res.ok) {
+      const errorText = await res.text().catch(() => "");
+      throw new Error(`[core:cerebras] API error: ${res.status} - ${errorText}`);
+    }
+    return res.json();
+  }
+
+  async function call(opts: CerebrasCallOptions): Promise<any | null> {
+    const raw = await callRaw({
+      messages: [
+        { role: "system", content: String(opts.systemPrompt || "") },
+        { role: "user", content: String(opts.userPrompt || "") },
+      ],
+      jsonMode: opts.jsonMode !== false,
+      timeoutMs: opts.timeoutMs,
+      temperature: opts.temperature,
+    });
+
+    const content = raw?.choices?.[0]?.message?.content || "";
+    try {
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+
+  return {
+    provider: "cerebras",
+    callRaw,
+    call,
+    model,
+  };
+}

package/src/providers/openaiChat.ts

@@ -0,0 +1,116 @@
+const OPENAI_RESPONSES_URL = "https://api.openai.com/v1/responses";
+const DEFAULT_MODEL = "gpt-4o-mini";
+
+export interface OpenAIChatClientOptions {
+  apiKey?: string;
+  model?: string;
+}
+
+export interface OpenAIChatClient {
+  provider: "openai";
+  model: string;
+  callRaw: (opts: {
+    systemPrompt: string;
+    userPrompt: string;
+    jsonMode?: boolean;
+    timeoutMs?: number;
+    temperature?: number;
+  }) => Promise<any>;
+  call: (opts: {
+    systemPrompt: string;
+    userPrompt: string;
+    jsonMode?: boolean;
+    timeoutMs?: number;
+    temperature?: number;
+  }) => Promise<any | null>;
+}
+
+export function createOpenAIChatClient(options: OpenAIChatClientOptions = {}): OpenAIChatClient {
+  const apiKey = String(options.apiKey || process.env.OPENAI_API_KEY || "").trim();
+  const model = String(options.model || process.env.RETRIEVAL_MODEL || DEFAULT_MODEL).trim();
+
+  async function callRaw(opts: {
+    systemPrompt: string;
+    userPrompt: string;
+    jsonMode?: boolean;
+    timeoutMs?: number;
+    temperature?: number;
+  }): Promise<any> {
+    if (!apiKey) {
+      throw new Error("[core:openai] OPENAI_API_KEY env var is not set");
+    }
+
+    const body: Record<string, unknown> = {
+      model,
+      input: [
+        {
+          role: "developer",
+          content: [{ type: "input_text", text: String(opts.systemPrompt || "") }],
+        },
+        {
+          role: "user",
+          content: [{ type: "input_text", text: String(opts.userPrompt || "") }],
+        },
+      ],
+      store: false,
+      reasoning: { effort: "minimal" },
+      temperature: Number.isFinite(Number(opts.temperature)) ? Number(opts.temperature) : 0,
+    };
+
+    if (opts.jsonMode !== false) {
+      body.text = { format: { type: "json_object" } };
+    }
+
+    const fetchOptions: RequestInit = {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify(body),
+    };
+    if (opts.timeoutMs && typeof AbortSignal.timeout === "function") {
+      fetchOptions.signal = AbortSignal.timeout(opts.timeoutMs);
+    }
+
+    const res = await fetch(OPENAI_RESPONSES_URL, fetchOptions);
+    if (!res.ok) {
+      const errorText = await res.text().catch(() => "");
+      throw new Error(`[core:openai] API error: ${res.status} - ${errorText}`);
+    }
+    return res.json();
+  }
+
+  async function call(opts: {
+    systemPrompt: string;
+    userPrompt: string;
+    jsonMode?: boolean;
+    timeoutMs?: number;
+    temperature?: number;
+  }): Promise<any | null> {
+    const raw = await callRaw(opts);
+
+    const outputItem = Array.isArray(raw?.output)
+      ? raw.output.find((o: any) => o?.type === "message" && o?.role === "assistant")
+      : null;
+    const textContent = Array.isArray(outputItem?.content)
+      ? outputItem.content.find((c: any) => c?.type === "output_text")
+      : null;
+
+    const content = String(textContent?.text || raw?.output_text || "").trim();
+    if (!content) return null;
+
+    try {
+      return JSON.parse(content);
+    } catch {
+      return null;
+    }
+  }
+
+  return {
+    provider: "openai",
+    model,
+    callRaw,
+    call,
+  };
+}

package/src/providers/openaiEmbedding.ts

@@ -0,0 +1,52 @@
+const OPENAI_EMBED_URL = "https://api.openai.com/v1/embeddings";
+
+let warnedMissingKey = false;
+
+export interface OpenAIEmbedderOptions {
+  apiKey?: string;
+  model?: string;
+}
+
+/**
+ * Returns a text->embedding function backed by OpenAI embeddings.
+ * If no API key is configured, it safely returns an empty embedding.
+ */
+export function createOpenAIEmbedder(options: OpenAIEmbedderOptions = {}) {
+  const apiKey = String(options.apiKey || process.env.OPENAI_API_KEY || "").trim();
+  const model = String(options.model || process.env.OPENAI_EMBED_MODEL || "text-embedding-3-small").trim();
+
+  return async function embed(text: string): Promise<number[]> {
+    const input = String(text || "").trim();
+    if (!input) return [];
+
+    if (!apiKey) {
+      if (!warnedMissingKey) {
+        warnedMissingKey = true;
+        console.warn("[core] OPENAI_API_KEY not set; embedding-enabled routes will fall back to non-vector behavior.");
+      }
+      return [];
+    }
+
+    const res = await fetch(OPENAI_EMBED_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify({
+        model,
+        input,
+      }),
+    });
+
+    if (!res.ok) {
+      const errText = await res.text().catch(() => "");
+      throw new Error(`openai_embedding_failed: ${res.status} ${errText}`);
+    }
+
+    const json: any = await res.json();
+    const embedding = json?.data?.[0]?.embedding;
+    if (!Array.isArray(embedding)) return [];
+    return embedding.map((v: unknown) => Number(v)).filter((v: number) => Number.isFinite(v));
+  };
+}