cogmemory 0.0.1-beta.2

package/src/helpers/turn.ts

@@ -0,0 +1,172 @@
+import type { Cogmem } from "../cogmem"
+import type { ContextReport, LearnResult, Memory } from "../types"
+
+/**
+ * Workflows.
+ *
+ * Resource methods are one call each. These compose them into the sequences
+ * people actually get wrong when they write the loop themselves — and the
+ * mistakes are mundane: forgetting to learn from a turn, learning from a question,
+ * letting a memory failure take down the turn it was meant to help, or never
+ * telling the service how a task went so the guardrails never fire.
+ *
+ * Each helper takes the client explicitly rather than closing over one, so it
+ * works with a second client without a module-level singleton.
+ */
+
+export interface TurnOptions {
+  /** Groups everything learned in one conversation. */
+  sessionId?: string
+  /**
+   * What the turn turned out to be about, e.g. `"database"`.
+   *
+   * Recorded against the self-model, which is what eventually produces a
+   * guardrail for a domain the agent keeps failing in. Cheap to send and the
+   * difference between a self-model that learns and one that sits at its priors.
+   */
+  domain?: string
+  /** What went wrong, when the turn was a failure. */
+  failurePattern?: string
+  /** What worked, when the turn was a success. */
+  strategy?: string
+  /** Set false to skip learning — a retrieval-only turn, say. */
+  learn?: boolean
+  onLearn?: (result: LearnResult) => void
+}
+
+export interface RunTurnResult {
+  context: ContextReport
+  learning: LearnResult | null
+  /**
+   * Why learning did not happen, if it did not.
+   *
+   * Present because a silent skip looks identical to a working one until the
+   * thing you taught it never comes back.
+   */
+  learningSkipped?: string
+}
+
+/**
+ * One turn of an agent loop, with memory handled correctly.
+ *
+ * The order is the point:
+ *
+ * 1. build context *before* the model runs, keyed on the message being answered;
+ * 2. run the model;
+ * 3. learn from the finished exchange;
+ * 4. record how the domain went, so the self-model moves.
+ *
+ * Steps 3 and 4 never fail the turn. Memory is an enhancement; an outage in it
+ * must not take down the agent that was working fine without it, and the errors
+ * are surfaced through `onLearn` and the returned skip reason rather than
+ * swallowed.
+ */
+export async function runTurn(
+  memory: Cogmem,
+  input: {
+    userMessage: string
+    run: (context: string) => Promise<string>
+  },
+  options: TurnOptions = {}
+): Promise<RunTurnResult> {
+  const context = await memory.context.build({
+    userMessage: input.userMessage,
+    ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId })
+  })
+
+  const assistantResponse = await input.run(context.text)
+
+  if (options.learn === false) {
+    return { context, learning: null, learningSkipped: "learning disabled for this turn" }
+  }
+
+  let learning: LearnResult | null = null
+  try {
+    learning = await memory.turns.learn({
+      userMessage: input.userMessage,
+      assistantResponse,
+      ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId })
+    })
+    options.onLearn?.(learning)
+  } catch (error) {
+    // Deliberately not rethrown: the turn already succeeded, and the assistant's
+    // answer does not become wrong because memory could not be written.
+    console.warn("[cognitive-memory] could not learn from this turn", error)
+    return { context, learning: null, learningSkipped: String(error) }
+  }
+
+  if (options.domain !== undefined) {
+    try {
+      await memory.selfModel.record({
+        domain: options.domain,
+        success: options.failurePattern === undefined,
+        ...(options.failurePattern === undefined ? {} : { failurePattern: options.failurePattern }),
+        ...(options.strategy === undefined ? {} : { strategy: options.strategy })
+      })
+    } catch (error) {
+      console.warn("[cognitive-memory] could not record the domain outcome", error)
+    }
+  }
+
+  return { context, learning }
+}
+
+export interface RecallOrExplainOptions {
+  limit?: number
+  /** Overrides the default "you were not told this" wording. */
+  emptyMessage?: string
+}
+
+/**
+ * Recall, phrased for injection into a prompt.
+ *
+ * Returns text rather than results because the caller's next step is almost
+ * always "put this in the prompt", and doing the formatting here means every
+ * integration handles the empty case the same way: by saying so, rather than
+ * letting a model fill the gap with a guess.
+ */
+export async function recallOrExplain(
+  memory: Cogmem,
+  query: string,
+  options: RecallOrExplainOptions = {}
+): Promise<string> {
+  const response = await memory.recall.search({
+    query,
+    ...(options.limit === undefined ? {} : { limit: options.limit })
+  })
+
+  if (response.empty) {
+    return options.emptyMessage ?? `Nothing in memory matches "${query}". If you were not told, say so rather than guessing.`
+  }
+
+  const lines = response.results.map((hit) => {
+    const domains = hit.memory.domains.length > 0 ? ` (${hit.memory.domains.join(", ")})` : ""
+    return `- ${hit.memory.content}${domains} [${hit.memory.tier}, relevance ${hit.score.toFixed(2)}]`
+  })
+  return `Remembered (${response.results.length} match${response.results.length === 1 ? "" : "es"}):\n${lines.join("\n")}`
+}
+
+export interface SeedOptions {
+  /** Statements worth keeping regardless of how they are phrased. */
+  facts: string[]
+  sessionId?: string
+}
+
+/**
+ * Store a set of statements once, tolerating the ones already held.
+ *
+ * For a migration or a first run, where you have a list of facts and no way to
+ * know which the service already knows. Restatements come back under
+ * `mergedInto` rather than as errors, so re-running it is safe.
+ */
+export async function seedMemories(memory: Cogmem, options: SeedOptions): Promise<{
+  stored: Memory[]
+  merged: Memory[]
+  rejected: LearnResult["rejected"]
+}> {
+  const result = await memory.memories.create({
+    items: options.facts.map((content) => ({ content })),
+    ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId })
+  })
+  return { stored: result.stored, merged: result.mergedInto, rejected: result.rejected }
+}

package/src/index.ts

@@ -0,0 +1,134 @@
+/**
+ * @astracollab/cogmem — Cognitive Memory for agents.
+ *
+ * Two things in one package, deliberately:
+ *
+ * 1. **A client** for the Cognitive Memory service, for agents that call memory
+ *    over HTTP.
+ * 2. **The cognitive layer itself** — the deterministic decisions about what to
+ *    store, what to inject, and whether a new statement is new. No database, no
+ *    network, no model in the retrieval path.
+ *
+ * Shipping both means a consumer can start with the service and later run the
+ * same logic in-process, or run it only in-process, without the behaviour
+ * changing underneath them. The primitives are the reason the two cannot drift.
+ *
+ * The exports are arranged for tree-shaking: importing `createClient` alone does
+ * not pull in the in-process engine, and the model-backed arbiter — which needs
+ * `ai` and `zod` — is a separate entry point so those stay optional peers.
+ */
+
+// ---------------------------------------------------------------------------
+// The service client
+// ---------------------------------------------------------------------------
+export { Cogmem, createClient } from "./cogmem"
+export { createHttpClient, type HttpClient } from "./client"
+export { CognitiveMemoryError } from "./errors"
+
+// Helpers — the workflows that encode best practice
+export {
+  runTurn,
+  recallOrExplain,
+  seedMemories,
+  type TurnOptions,
+  type RunTurnResult,
+  type RecallOrExplainOptions,
+  type SeedOptions
+} from "./helpers/turn"
+
+// Resources, for advanced use and for testing
+export { MemoriesResource } from "./resources/memories"
+export { ContextResource } from "./resources/context"
+export { RecallResource } from "./resources/recall"
+export { TurnsResource } from "./resources/turns"
+export { TensionsResource } from "./resources/tensions"
+export { SelfModelResource } from "./resources/self-model"
+export { StatsResource, fetchHealth } from "./resources/stats"
+
+// ---------------------------------------------------------------------------
+// The cognitive layer — runnable in-process
+// ---------------------------------------------------------------------------
+export { CognitiveMemory, runFastGate, extractDomains } from "./cognitive"
+export {
+  extractDeterministic,
+  relevanceTokens,
+  overlapScore,
+  distinctiveTokens,
+  isLossyRewrite,
+  extractIdentifiers,
+  isInteractionScoped,
+  similarity,
+  normalise,
+  estimateTokens,
+  gistOf,
+  CANDIDATE_FLOOR,
+  COLLAPSE_THRESHOLD,
+  MAX_CANDIDATES,
+  PROMOTE_THRESHOLD
+} from "./cognitive"
+export type { FastGateResult, DeterministicMemory } from "./cognitive"
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+// The client's wire types.
+export type {
+  Memory,
+  MemoryTier,
+  MemorySource,
+  Impact,
+  TensionStatus,
+  InclusionReason,
+  Scope,
+  RecallHit,
+  ContextEntry,
+  ContextReport,
+  LearnResult,
+  RejectedStatement,
+  Claim,
+  Tension,
+  DomainCapability,
+  SelfModel,
+  Health,
+  Stats,
+  RememberRequest,
+  ListMemoriesParams,
+  RecallRequest,
+  RecallResponse,
+  TurnRequest,
+  ContextRequest,
+  AddTensionRequest,
+  ResolveTensionRequest,
+  DomainOutcomeRequest,
+  CognitiveMemoryConfig,
+  CognitiveMemoryErrorBody
+} from "./types"
+
+/*
+ * The cognitive layer's own vocabulary, under its own names.
+ *
+ * No prefixing was necessary: the client's types are `Memory`, `Impact`,
+ * `Tension` and `SelfModel`, and the layer's are `MemoryItem`, `TensionImpact`,
+ * `KnowledgeTension` and `ProprioceptiveSelfModel`. The only genuine overlap is
+ * `MemoryTier`, `TensionStatus` and `DomainCapability`, which are identical in
+ * both — the same field names and the same string values — so the client's
+ * copies above are the canonical ones and are not re-exported here.
+ */
+export type {
+  MemoryItem,
+  MemoryMetadata,
+  MemoryInclusionReason,
+  MemoryInjectionEntry,
+  MemoryInjectionReport,
+  MemoryReconciliation,
+  MemoryTier as CognitiveMemoryTier,
+  KnowledgeTension,
+  ProprioceptiveSelfModel,
+  TrajectoryPrediction,
+  TensionImpact,
+  ArbiterEvaluationResult,
+  ArbiterFn,
+  CognitiveMemoryOptions,
+  CognitiveMemoryStateSnapshot
+} from "./cognitive"

package/src/resources/context.ts

@@ -0,0 +1,17 @@
+import type { HttpClient } from "../client"
+import type { ContextReport, ContextRequest } from "../types"
+
+/**
+ * The prompt block.
+ *
+ * One call per turn, and the reason the service exists: a one-line index of
+ * everything remembered, plus full bodies only where a named identifier, an
+ * unresolved contradiction, or a weak domain earned them.
+ */
+export class ContextResource {
+  constructor(private readonly client: HttpClient) {}
+
+  build(request: ContextRequest = {}): Promise<ContextReport> {
+    return this.client<ContextReport>("/context", { method: "POST", body: request })
+  }
+}

package/src/resources/memories.ts

@@ -0,0 +1,60 @@
+import type { HttpClient } from "../client"
+import type { LearnResult, ListMemoriesParams, Memory, MemoryTier, RememberRequest } from "../types"
+
+/**
+ * Reading and writing what is stored.
+ *
+ * Deliberately thin: one method, one endpoint, no cleverness. The class is a
+ * namespace, so `memory.memories.` offers the whole surface in an editor, but it
+ * is not a place for business logic. The workflow that composes these calls lives
+ * in `../helpers`.
+ */
+export class MemoriesResource {
+  constructor(private readonly client: HttpClient) {}
+
+  /**
+   * The envelope is unwrapped here rather than passed on.
+   *
+   * The service replies with `{ memories, stats }` so a dashboard can get both in
+   * one call, but an SDK caller who asked for a list wants a list. Deciding that
+   * in one place here is better than making every integration know the shape.
+   */
+  async list(params: ListMemoriesParams = {}): Promise<Memory[]> {
+    const response = await this.client<{ memories: Memory[] }>("/memories", {
+      method: "GET",
+      query: params
+    })
+    return response.memories
+  }
+
+  async get(id: string): Promise<Memory> {
+    const response = await this.client<{ memory: Memory }>(`/memories/${encodeURIComponent(id)}`, {
+      method: "GET"
+    })
+    return response.memory
+  }
+
+  /**
+   * State facts outright.
+   *
+   * Restatements of something already held are folded in rather than stored
+   * twice, and the result says which ones were folded and into what — a write
+   * that silently did nothing is indistinguishable from a bug.
+   */
+  create(request: RememberRequest): Promise<LearnResult> {
+    return this.client<LearnResult>("/memories", { method: "POST", body: request })
+  }
+
+  /** Move a memory between tiers. L1 is pre-staged into every context build. */
+  async promote(id: string, tier: MemoryTier): Promise<Memory> {
+    const response = await this.client<{ memory: Memory }>(`/memories/${encodeURIComponent(id)}`, {
+      method: "PATCH",
+      body: { tier }
+    })
+    return response.memory
+  }
+
+  remove(id: string): Promise<{ deleted: boolean; id: string }> {
+    return this.client(`/memories/${encodeURIComponent(id)}`, { method: "DELETE" })
+  }
+}

package/src/resources/recall.ts

@@ -0,0 +1,17 @@
+import type { HttpClient } from "../client"
+import type { RecallRequest, RecallResponse } from "../types"
+
+/**
+ * Deterministic ranked lookup.
+ *
+ * No model is involved, so recall quality does not change when a provider is
+ * down or a different model is configured. `empty: true` is the signal to admit
+ * ignorance rather than guess.
+ */
+export class RecallResource {
+  constructor(private readonly client: HttpClient) {}
+
+  search(request: RecallRequest): Promise<RecallResponse> {
+    return this.client<RecallResponse>("/recall", { method: "POST", body: request })
+  }
+}

package/src/resources/self-model.ts

@@ -0,0 +1,21 @@
+import type { HttpClient } from "../client"
+import type { DomainOutcomeRequest, SelfModel } from "../types"
+
+/**
+ * The proprioceptive self-model: how reliably this agent has done in each domain.
+ *
+ * Nothing here is inferred. Without outcomes recorded through `record`, the
+ * model stays at its priors and no guardrail ever fires — which is the most
+ * common reason a self-model looks like it is not working.
+ */
+export class SelfModelResource {
+  constructor(private readonly client: HttpClient) {}
+
+  get(): Promise<SelfModel> {
+    return this.client<SelfModel>("/self-model", { method: "GET" })
+  }
+
+  record(request: DomainOutcomeRequest): Promise<SelfModel> {
+    return this.client<SelfModel>("/self-model/outcome", { method: "POST", body: request })
+  }
+}

package/src/resources/stats.ts

@@ -0,0 +1,27 @@
+import type { HttpClient } from "../client"
+import type { Health, Stats } from "../types"
+
+/** What the memory currently holds, and what the service can do. */
+export class StatsResource {
+  constructor(private readonly client: HttpClient) {}
+
+  /** Needs only `stats:read`, so monitoring can watch without reading memories. */
+  get(): Promise<Stats> {
+    return this.client<Stats>("/stats", { method: "GET" })
+  }
+}
+
+/**
+ * Liveness, and this deployment's limits and extractor mode.
+ *
+ * Takes an explicit base URL because it is the one call that must work with no
+ * key at all — including from a health check that has no credentials.
+ */
+export const fetchHealth = async (baseUrl: string): Promise<Health> => {
+  const origin = baseUrl.replace(/\/$/, "")
+  const response = await fetch(`${origin}/api/v1/health`, { headers: { accept: "application/json" } })
+  if (!response.ok) {
+    throw new Error(`cognitive-memory: health check failed with ${response.status}`)
+  }
+  return (await response.json()) as Health
+}

package/src/resources/tensions.ts

@@ -0,0 +1,36 @@
+import type { HttpClient } from "../client"
+import type { AddTensionRequest, ResolveTensionRequest, Tension, TensionStatus } from "../types"
+
+/**
+ * Knowledge tensions: two claims that cannot both be true.
+ *
+ * A tension is worth more than either claim alone, so it is pinned into every
+ * context build with an actionable question until it is resolved.
+ */
+export class TensionsResource {
+  constructor(private readonly client: HttpClient) {}
+
+  async list(status?: TensionStatus): Promise<Tension[]> {
+    const response = await this.client<{ tensions: Tension[] }>("/tensions", {
+      method: "GET",
+      query: status === undefined ? {} : { status }
+    })
+    return response.tensions
+  }
+
+  async create(request: AddTensionRequest): Promise<Tension> {
+    const response = await this.client<{ tension: Tension }>("/tensions", {
+      method: "POST",
+      body: request
+    })
+    return response.tension
+  }
+
+  async resolve(id: string, request: ResolveTensionRequest): Promise<Tension> {
+    const response = await this.client<{ tension: Tension }>(`/tensions/${encodeURIComponent(id)}`, {
+      method: "POST",
+      body: request
+    })
+    return response.tension
+  }
+}

package/src/resources/turns.ts

@@ -0,0 +1,16 @@
+import type { HttpClient } from "../client"
+import type { LearnResult, TurnRequest } from "../types"
+
+/**
+ * Learning from a completed turn.
+ *
+ * A turn whose user message contains a question is treated as a lookup rather
+ * than a lesson, so this is called after work is done, not before.
+ */
+export class TurnsResource {
+  constructor(private readonly client: HttpClient) {}
+
+  learn(request: TurnRequest): Promise<LearnResult> {
+    return this.client<LearnResult>("/turns", { method: "POST", body: request })
+  }
+}