cogmemory 0.0.1-beta.2

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "cogmemory",
+  "version": "0.0.1-beta.2",
+  "description": "Cognitive Memory for agents: a typed client for the service, plus the deterministic cognitive layer to run in-process. No model in the retrieval path.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cognitive-memory.cjs",
+  "module": "./dist/cognitive-memory.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/cognitive-memory.js",
+      "require": "./dist/cognitive-memory.cjs"
+    },
+    "./arbiter": {
+      "types": "./dist/arbiter.d.ts",
+      "import": "./dist/arbiter.js",
+      "require": "./dist/arbiter.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "author": "AstraCollab",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/astracollab/astracollab.git",
+    "directory": "packages/cognitive-memory"
+  },
+  "keywords": [
+    "memory",
+    "llm",
+    "agent",
+    "context",
+    "cogmem",
+    "cognitive-memory",
+    "sdk",
+    "ai"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "check-types": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "ai": "^7.0.0",
+    "ofetch": "^1.4.1",
+    "zod": "^3.25.76 || ^4.1.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.0",
+    "ai": "^7.0.127",
+    "ofetch": "^1.4.1",
+    "typescript": "^5.8.3",
+    "vite": "^5.4.19",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.4",
+    "zod": "^4.3.6"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  }
+}

package/src/arbiter.ts

@@ -0,0 +1,14 @@
+/**
+ * The model-backed arbiter, as a separate entry point.
+ *
+ * It needs `ai` and `zod`, and nothing else in this package does. Keeping it at
+ * `@astracollab/cogmem/arbiter` means a consumer who only wants the client or
+ * the deterministic core is not made to install them, and does not get a peer
+ * warning for a dependency they will never use.
+ *
+ * The arbiter is optional in the design too. Without it the engine promotes by
+ * content-word overlap, which is what `CognitiveMemory` does by default — so a
+ * deployment with no model configured still has working memory.
+ */
+export { createModelArbiter, type CreateModelArbiterOptions } from "./cognitive/arbiter"
+export type { ArbiterEvaluationResult, ArbiterFn } from "./cognitive/types"

package/src/client.ts

@@ -0,0 +1,105 @@
+import { FetchError, ofetch, type $Fetch } from "ofetch"
+
+import { CognitiveMemoryError } from "./errors"
+import type { CognitiveMemoryConfig, CognitiveMemoryErrorBody } from "./types"
+
+/**
+ * Configuration, as a factory rather than a constructor.
+ *
+ * A constructor with fifteen options is a dumping ground: configuration and
+ * instantiation get tangled, tests have to construct a whole class to check one
+ * header, and "the client with a different timeout" becomes a subclass. A factory
+ * is a plain function — no `new`, no `this`, composable, trivially mockable.
+ *
+ * The real work happens in the interceptors. Authentication, error translation
+ * and debug logging are configured once here instead of being repeated in each
+ * of the twenty-odd methods below, which is the difference between changing how
+ * auth works in one place and in twenty.
+ */
+export function createHttpClient(config: CognitiveMemoryConfig): $Fetch {
+  const {
+    apiKey,
+    baseUrl = defaultBaseUrl(),
+    timeout = 30_000,
+    retry = 2,
+    debug = false,
+    headers: extraHeaders = {}
+  } = config
+
+  if (typeof apiKey !== "string" || apiKey.trim() === "") {
+    throw new Error(
+      "cognitive-memory: apiKey is required. Issue one in the dashboard — the secret is shown only once."
+    )
+  }
+
+  const inner = ofetch.create({
+    baseURL: `${baseUrl.replace(/\/$/, "")}/api/v1`,
+    timeout,
+    // Retries are for transport hiccups, not for a 400. ofetch already limits
+    // this to idempotent-looking methods, and the service is idempotent for the
+    // reads that matter.
+    retry,
+    headers: {
+      accept: "application/json",
+      ...extraHeaders
+    },
+
+    onRequest({ options, request }) {
+      // `options.headers` is a Headers instance by this point, not a plain
+      // object — assigning to it silently drops every header.
+      options.headers.set("authorization", `Bearer ${apiKey}`)
+      options.headers.set("content-type", "application/json")
+      if (debug) {
+        // eslint-disable-next-line no-console
+        console.log("[cognitive-memory]", options.method ?? "GET", `${options.baseURL ?? ""}${request ?? ""}`)
+      }
+    },
+
+    onResponse({ response, options, request }) {
+      if (debug) {
+        // eslint-disable-next-line no-console
+        console.log("[cognitive-memory]", response.status, options.method ?? "GET", request ?? "")
+      }
+    },
+
+  })
+
+  /**
+   * Error translation happens out here rather than in `onResponseError`.
+   *
+   * ofetch 1.4 replaces anything thrown from that hook with its own `FetchError`
+   * before it reaches the caller, so a hook that throws is a hook whose error
+   * silently disappears — the caller gets an exception with no status, no scope
+   * and no issues. Catching here is the only place the service's envelope can be
+   * read, and it leaves genuine transport failures (no response) untouched.
+   */
+  // The parameter types are taken from `$Fetch` itself rather than restated, so
+  // this wrapper cannot drift out of step with the client it wraps.
+  const wrap = async (request: unknown, options?: unknown): Promise<unknown> => {
+    try {
+      return await (inner as (r: unknown, o?: unknown) => Promise<unknown>)(request, options)
+    } catch (error) {
+      if (!(error instanceof FetchError) || !error.response) throw error
+      const response = error.response
+      // The service always answers with this envelope; a proxy or a crash in
+      // front of it might not, so the body is treated as untrusted.
+      const body = (response._data ?? undefined) as CognitiveMemoryErrorBody | undefined
+      throw new CognitiveMemoryError(body?.message ?? `cognitive-memory: request failed with ${response.status}`, {
+        status: response.status,
+        code: body?.error ?? "UnknownError",
+        ...(body === undefined ? {} : { body }),
+        ...(body?.requiredScope === undefined ? {} : { requiredScope: body.requiredScope }),
+        ...(body?.issues === undefined ? {} : { issues: body.issues })
+      })
+    }
+  }
+
+  return wrap as unknown as $Fetch
+}
+
+function defaultBaseUrl(): string {
+  if (typeof window !== "undefined") return window.location.origin
+  return "http://localhost:3000"
+}
+
+export type HttpClient = ReturnType<typeof createHttpClient>

package/src/cogmem.ts

@@ -0,0 +1,74 @@
+import { createHttpClient, type HttpClient } from "./client"
+import { ContextResource } from "./resources/context"
+import { MemoriesResource } from "./resources/memories"
+import { RecallResource } from "./resources/recall"
+import { SelfModelResource } from "./resources/self-model"
+import { StatsResource } from "./resources/stats"
+import { TensionsResource } from "./resources/tensions"
+import { TurnsResource } from "./resources/turns"
+import type { Health, CognitiveMemoryConfig } from "./types"
+import { fetchHealth } from "./resources/stats"
+
+/**
+ * The client.
+ *
+ * Named `Cogmem` rather than `CognitiveMemory` because that name belongs to the
+ * in-process engine, and has for as long as this layer existed. Two exports
+ * cannot share a name, and the engine's is the older public API: quietly
+ * redefining it to mean an HTTP client would break every consumer of it.
+ *
+ * Resource classes rather than a flat list of functions, because
+ * `memory.memories.` in an editor shows every operation on memories and nothing
+ * else. The methods stay one-to-one with endpoints, so the class never becomes a
+ * second, divergent copy of the service.
+ *
+ * `readonly` on the resources is not decoration: it stops a caller reassigning
+ * `memory.memories` and wondering why the other half of the client stopped
+ * seeing the change.
+ */
+export class Cogmem {
+  private readonly client: HttpClient
+  readonly baseUrl: string
+
+  readonly memories: MemoriesResource
+  readonly context: ContextResource
+  readonly recall: RecallResource
+  readonly turns: TurnsResource
+  readonly tensions: TensionsResource
+  readonly selfModel: SelfModelResource
+  readonly stats: StatsResource
+
+  constructor(config: CognitiveMemoryConfig) {
+    this.baseUrl = (config.baseUrl ?? "http://localhost:3000").replace(/\/$/, "")
+    this.client = createHttpClient(config)
+    this.memories = new MemoriesResource(this.client)
+    this.context = new ContextResource(this.client)
+    this.recall = new RecallResource(this.client)
+    this.turns = new TurnsResource(this.client)
+    this.tensions = new TensionsResource(this.client)
+    this.selfModel = new SelfModelResource(this.client)
+    this.stats = new StatsResource(this.client)
+  }
+
+  /**
+   * Liveness and limits, without spending a request on the configured key.
+   *
+   * Useful in a readiness probe: if `extractor` is `rules-only` the service is up
+   * but is not doing model-backed extraction, and `problems` is non-empty when a
+   * setting is present but unusable.
+   */
+  health(): Promise<Health> {
+    return fetchHealth(this.baseUrl)
+  }
+}
+
+/**
+ * Both construction styles, deliberately.
+ *
+ * Some people prefer `new Cogmem(...)` and some prefer `createClient(...)`; there
+ * is no reason to make anyone rename. The factory is also the easier one to mock
+ * in tests, which is the whole reason `createHttpClient` is a function.
+ */
+export function createClient(config: CognitiveMemoryConfig): Cogmem {
+  return new Cogmem(config)
+}

package/src/cognitive/arbiter.ts

@@ -0,0 +1,105 @@
+import { generateObject, type LanguageModel } from "ai";
+import { z } from "zod";
+import type { ArbiterEvaluationResult, ArbiterFn } from "./types.js";
+
+const ArbiterSchema = z.object({
+  promotions: z.array(
+    z.object({
+      memoryId: z.string(),
+      targetTier: z.literal("L1"),
+      signalType: z.enum(["anticipatory", "tension", "proprioceptive", "recency"]),
+      urgency: z.number().min(0).max(1),
+    })
+  ),
+  demotions: z.array(
+    z.object({
+      memoryId: z.string(),
+      targetTier: z.literal("L2"),
+      reason: z.string(),
+    })
+  ),
+  pins: z.array(
+    z.object({
+      memoryId: z.string(),
+      targetTier: z.literal("L0"),
+      reason: z.string(),
+    })
+  ),
+  detectedTensions: z.array(
+    z.object({
+      claimA: z.string().describe("First conflicting claim or statement"),
+      claimB: z.string().describe("Contradicting statement from code or user"),
+      impact: z.enum(["low", "medium", "critical"]),
+      actionableQuestion: z.string().describe("Specific clarifying question the agent should resolve"),
+    })
+  ),
+  trajectoryPrediction: z
+    .object({
+      predictedDomains: z.array(z.string()),
+      predictedFiles: z.array(z.string()),
+      prefetchMemoryIds: z.array(z.string()),
+      confidence: z.number().min(0).max(1),
+    })
+    .optional(),
+  selfModelUpdate: z
+    .object({
+      domain: z.string(),
+      success: z.boolean().optional(),
+      failurePatternObserved: z.string().optional(),
+    })
+    .optional(),
+});
+
+export interface CreateModelArbiterOptions {
+  /** Fast decision model (e.g., Gemini 1.5/2.5 Flash, Claude 3.5 Haiku, or GPT-4o-mini) */
+  model: LanguageModel;
+  /** Custom system prompt override if desired */
+  systemPrompt?: string;
+}
+
+/**
+ * Creates an Arbiter function powered by an AI SDK model with structured output.
+ */
+export const createModelArbiter = (options: CreateModelArbiterOptions): ArbiterFn => {
+  return async ({ turnText, assistantReply, l0Prompt, l1Summaries, candidates }): Promise<ArbiterEvaluationResult> => {
+    try {
+      const prompt = `You are the Cache Arbiter for an AI coding agent.
+Evaluate the latest turn and candidate memories to decide what should be HOT (L1), COLD (L2), or PINNED (L0).
+
+CURRENT TURN:
+User: "${turnText}"
+Assistant: "${assistantReply}"
+
+L0 CORE STATE:
+${l0Prompt || "(none)"}
+
+CURRENT HOT L1 SUMMARIES:
+${JSON.stringify(l1Summaries, null, 2)}
+
+WARM L2 CANDIDATE MEMORIES:
+${JSON.stringify(candidates, null, 2)}
+
+Analyze:
+1. What will the agent likely need in the NEXT 1-2 turns? (Anticipatory -> promote candidate to L1)
+2. Are any active L1 items no longer relevant? (Demote L1 to L2)
+3. Did the conversation reveal a contradiction between user claims and known facts? (Flag as detectedTension)
+4. Did the agent succeed or struggle in a specific domain? (Update self-model)`;
+
+      const result = await generateObject({
+        model: options.model,
+        schema: ArbiterSchema,
+        prompt,
+      });
+
+      return result.object;
+    } catch {
+      // Return safe empty fallback on model failure so the cache remains stable
+      return {
+        promotions: [],
+        demotions: [],
+        pins: [],
+        detectedTensions: [],
+      };
+    }
+  };
+};

package/src/cognitive/fast-gate.ts

@@ -0,0 +1,63 @@
+/**
+ * Fast Heuristic Gate
+ * 
+ * Synchronous, sub-5ms gate running on the critical path before model invocation.
+ * Detects explicit user corrections/contradictions and significant domain pivots
+ * without triggering an LLM call.
+ */
+
+export interface FastGateResult {
+  action: "proceed" | "inject_caution";
+  cautionNote?: string;
+  detectedDomains?: string[];
+}
+
+const CONTRADICTION_PATTERNS = [
+  /actually,?\s+(?:we|i)\s+(?:switched|changed|moved|migrated|replaced|use|want|have)/i,
+  /that(?:'s|\s+is)\s+(?:wrong|incorrect|outdated|false|not\s+right|no\s+longer)/i,
+  /no,?\s+(?:it(?:'s|\s+is)|we\s+use|we\s+switched|it\s+should\s+be|don(?:'t|\s+not)\s+use)/i,
+  /stop\s+using\s+/i,
+  /instead\s+of\s+/i,
+  /disregard\s+(?:prior|previous|what\s+i\s+said)/i,
+];
+
+const DOMAIN_KEYWORDS: Record<string, RegExp[]> = {
+  auth: [/auth/i, /login/i, /session/i, /jwt/i, /oauth/i, /token/i, /password/i, /permission/i],
+  database: [/postgres/i, /sqlite/i, /sql/i, /schema/i, /migration/i, /prisma/i, /drizzle/i, /mongo/i, /redis/i],
+  frontend: [/css/i, /tailwind/i, /component/i, /jsx/i, /tsx/i, /layout/i, /ui/i, /render/i, /html/i],
+  build: [/vite/i, /webpack/i, /turbo/i, /tsconfig/i, /pnpm/i, /package\.json/i, /bundle/i],
+  api: [/rest/i, /graphql/i, /endpoint/i, /route/i, /fetch/i, /request/i, /response/i],
+  git: [/branch/i, /commit/i, /merge/i, /rebase/i, /worktree/i, /conflict/i],
+};
+
+export const runFastGate = (userMessage: string): FastGateResult => {
+  if (!userMessage || userMessage.trim().length === 0) {
+    return { action: "proceed" };
+  }
+
+  // 1. Check for explicit contradiction signals
+  for (const pattern of CONTRADICTION_PATTERNS) {
+    if (pattern.test(userMessage)) {
+      return {
+        action: "inject_caution",
+        cautionNote: "User appears to be explicitly correcting a prior premise or configuration. Verify current facts before proceeding with assumptions.",
+        detectedDomains: extractDomains(userMessage),
+      };
+    }
+  }
+
+  return {
+    action: "proceed",
+    detectedDomains: extractDomains(userMessage),
+  };
+};
+
+export const extractDomains = (text: string): string[] => {
+  const matched: string[] = [];
+  for (const [domain, patterns] of Object.entries(DOMAIN_KEYWORDS)) {
+    if (patterns.some((p) => p.test(text))) {
+      matched.push(domain);
+    }
+  }
+  return matched;
+};

package/src/cognitive/index.ts

@@ -0,0 +1,64 @@
+/**
+ * The cognitive layer.
+ *
+ * Everything that decides *what* to remember, *what* to put in front of a model,
+ * and *whether* a new statement says something new — with no database, no
+ * network, and no model in the retrieval path.
+ *
+ * That last part is the design constraint everything else follows from. A memory
+ * layer whose recall quality moves with provider availability is not a storage
+ * layer, it is a demo, so ranking, merge safety and index budgeting are all
+ * deterministic functions of the text in front of them.
+ *
+ * `CognitiveMemory` is the in-process implementation: four Maps, snapshots to
+ * and from JSON, no I/O beyond what you give it. The service is the same
+ * decisions with the tiers in a database, which is why the primitives below are
+ * shared rather than reimplemented.
+ */
+
+export { CognitiveMemory } from "./memory.js"
+
+export { runFastGate, extractDomains, type FastGateResult } from "./fast-gate.js"
+
+export {
+  extractDeterministic,
+  type DeterministicMemory
+} from "./rules.js"
+
+export {
+  CANDIDATE_FLOOR,
+  COLLAPSE_THRESHOLD,
+  MAX_CANDIDATES,
+  PROMOTE_THRESHOLD,
+  distinctiveTokens,
+  estimateTokens,
+  extractIdentifiers,
+  gistOf,
+  isInteractionScoped,
+  isLossyRewrite,
+  normalise,
+  overlapScore,
+  relevanceTokens,
+  similarity
+} from "./relevance.js"
+
+export type {
+  MemoryTier,
+  TensionStatus,
+  TensionImpact,
+  KnowledgeTension,
+  DomainCapability,
+  ProprioceptiveSelfModel,
+  MemoryMetadata,
+  MemoryItem,
+  TrajectoryPrediction,
+  MemoryInclusionReason,
+  MemoryInclusionReason as InclusionReason,
+  MemoryInjectionEntry,
+  MemoryInjectionReport,
+  MemoryReconciliation,
+  ArbiterEvaluationResult,
+  ArbiterFn,
+  CognitiveMemoryOptions,
+  CognitiveMemoryStateSnapshot
+} from "./types.js"