@noetic-tools/core 0.1.1 → 0.2.0

package/dist/harness/agent-harness.js

@@ -50,6 +50,19 @@ function createClient(config) {
     if (!apiKey) {
         return undefined;
     }
+    if (config?.cache) {
+        // Inject `X-OpenRouter-Cache: true` on every request so OpenRouter serves
+        // identical model calls from cache without re-billing (deterministic re-runs).
+        return new OpenRouter({
+            apiKey,
+            hooks: {
+                beforeRequest: (_ctx, request) => {
+                    request.headers.set('X-OpenRouter-Cache', 'true');
+                    return request;
+                },
+            },
+        });
+    }
     return new OpenRouter({
         apiKey,
     });

package/dist/index.d.ts

@@ -75,6 +75,10 @@ export { staticContent } from './memory/layers/static-content.js';
 /** @public */
 export { steering } from './memory/layers/steering.js';
 /** @public */
+export type { FactExtractor, FactSearcher, TemporalFact, TemporalMemoryConfig, TemporalSearchResult, } from './memory/layers/temporal.js';
+/** @public */
+export { temporalMemory } from './memory/layers/temporal.js';
+/** @public */
 export { toolMemoryLayer } from './memory/layers/tool-memory-layer.js';
 /** @public */
 export type { WorkingMemoryConfig, WorkingMemoryState } from './memory/layers/working-memory.js';

package/dist/index.js

@@ -66,6 +66,8 @@ export { staticContent } from './memory/layers/static-content.js';
 /** @public */
 export { steering } from './memory/layers/steering.js';
 /** @public */
+export { temporalMemory } from './memory/layers/temporal.js';
+/** @public */
 export { toolMemoryLayer } from './memory/layers/tool-memory-layer.js';
 /** @public */
 export { workingMemory } from './memory/layers/working-memory.js';

package/dist/memory/layers/temporal.d.ts

@@ -0,0 +1,91 @@
+import type { MemoryLayer, MemoryScope } from '../../types/memory.js';
+/**
+ * A single remembered fact tied to an instant.
+ * @public
+ */
+export interface TemporalFact {
+    /** ISO-8601 timestamp the fact is associated with (when it happened / was stated). */
+    ts: string;
+    /** The fact, stated tersely. */
+    fact: string;
+}
+/**
+ * Result of a temporal memory search.
+ * @public
+ */
+export interface TemporalSearchResult {
+    /** Matching facts, most relevant first. */
+    facts: string[];
+    /** A resolved date for the query, when one applies (ISO-8601 or a natural phrase). */
+    date?: string;
+    /** True when `date` is approximate ("around March", "a few weeks ago"). */
+    fuzzy?: boolean;
+}
+/**
+ * Extracts timestamped facts from a batch of conversation text. Host-injected so
+ * the layer stays LLM-agnostic and tree-shakable (mirrors `observationalMemory`'s
+ * `observer`). When omitted, the layer only buffers — it never fabricates facts.
+ * @public
+ */
+export type FactExtractor = (input: {
+    transcript: string;
+    now: string;
+}) => Promise<TemporalFact[]>;
+/**
+ * Searches the stored fact ledger for a query, optionally resolving a date.
+ * Host-injected. When omitted, search falls back to returning the raw ledger.
+ * @public
+ */
+export type FactSearcher = (input: {
+    query: string;
+    facts: ReadonlyArray<TemporalFact>;
+    now: string;
+}) => Promise<TemporalSearchResult>;
+/**
+ * Configuration for {@link temporalMemory}.
+ * @public
+ */
+export interface TemporalMemoryConfig {
+    /** Returns "now" for date grounding/extraction. Defaults to the system clock. */
+    now?: () => Date;
+    /** Memory scope. Defaults to `'resource'` (long-term, cross-session). */
+    scope?: MemoryScope;
+    /** LLM-backed fact extractor. Without it, `store` only buffers (no extraction). */
+    extract?: FactExtractor;
+    /** LLM-backed fact searcher. Without it, `searchMemory` returns the raw ledger. */
+    search?: FactSearcher;
+    /** Buffered output tokens that trigger an extraction pass. Default 2000. */
+    bufferThreshold?: number;
+    /** Maximum facts retained (oldest dropped beyond this). Default 200. */
+    maxFacts?: number;
+    /** Inject a `<current_datetime>` grounding block on recall. Default true. */
+    groundDateTime?: boolean;
+    /** Inject the fact ledger on recall (vs. on-demand via the search tool). Default false. */
+    injectLedger?: boolean;
+}
+interface TemporalState {
+    /** ISO timestamp → facts recorded at that instant. */
+    facts: Record<string, string[]>;
+    /** Accumulated output text awaiting extraction. */
+    buffer: string[];
+    bufferTokens: number;
+    version: number;
+}
+/**
+ * A non-atomic, LLM-backed memory layer that extracts timestamped facts from the
+ * conversation into a key-value ledger (key = ISO timestamp) and exposes a
+ * `temporal/searchMemory` tool for relative-time recall — given a fact/query it
+ * returns matching facts and, when applicable, a resolved (possibly fuzzy) date.
+ *
+ * The layer is LLM-agnostic: the host injects `extract` and `search` callbacks
+ * (mirrors `observationalMemory`'s `observer`), keeping `memory/` tree-shakable.
+ * Without them, the layer still buffers text and the search tool returns the raw
+ * ledger — it never fabricates facts. A `<current_datetime>` grounding block is
+ * injected on recall by default to anchor relative-time reasoning.
+ *
+ * @public
+ * @param config - Clock, scope, injected LLM callbacks, and tuning knobs.
+ * @returns A `MemoryLayer` with a fact-ledger store + `searchMemory` tool.
+ */
+export declare function temporalMemory(config?: TemporalMemoryConfig): MemoryLayer<TemporalState>;
+export {};

package/dist/memory/layers/temporal.js

@@ -0,0 +1,245 @@
+import { z } from 'zod';
+import { Slot } from '../../types/memory.js';
+import { createMessage, estimateTokens, isOutputText } from '../../util/message-helpers.js';
+import { layerFn } from '../layer-provides.js';
+function emptyState() {
+    return {
+        facts: {},
+        buffer: [],
+        bufferTokens: 0,
+        version: 0,
+    };
+}
+const DEFAULT_BUFFER_THRESHOLD_TOKENS = 2_000;
+const DEFAULT_MAX_FACTS = 200;
+//#endregion
+//#region Date grounding
+const WEEKDAYS = [
+    'Sun',
+    'Mon',
+    'Tue',
+    'Wed',
+    'Thu',
+    'Fri',
+    'Sat',
+];
+/** Formats an instant as `YYYY/MM/DD (Ddd) HH:MM` using local fields. */
+function formatNow(date) {
+    const yyyy = date.getFullYear();
+    const mm = String(date.getMonth() + 1).padStart(2, '0');
+    const dd = String(date.getDate()).padStart(2, '0');
+    const day = WEEKDAYS[date.getDay()];
+    const hh = String(date.getHours()).padStart(2, '0');
+    const min = String(date.getMinutes()).padStart(2, '0');
+    return `${yyyy}/${mm}/${dd} (${day}) ${hh}:${min}`;
+}
+function renderDateTimeBlock(date) {
+    return [
+        '<current_datetime>',
+        `Now: ${formatNow(date)}`,
+        'Resolve relative time ("N days/weeks/months ago", "last/next <weekday>",',
+        '"before/after", "first/earliest/most recent", "how long since/until") against',
+        'Now above and compute the difference explicitly before answering. Use the',
+        'temporal/searchMemory tool to look up when something happened.',
+        '</current_datetime>',
+    ].join('\n');
+}
+//#endregion
+//#region Ledger helpers
+/** Flattens the KV ledger into a flat, chronologically sorted fact list. */
+function ledgerToFacts(state) {
+    const out = [];
+    for (const [ts, facts] of Object.entries(state.facts)) {
+        for (const fact of facts) {
+            out.push({
+                ts,
+                fact,
+            });
+        }
+    }
+    out.sort((a, b) => (a.ts < b.ts ? -1 : a.ts > b.ts ? 1 : 0));
+    return out;
+}
+/** Merges new facts into the KV ledger, capping total facts to `maxFacts` (oldest dropped). */
+function mergeFacts(state, incoming, maxFacts) {
+    const facts = {};
+    for (const [ts, list] of Object.entries(state.facts)) {
+        facts[ts] = [
+            ...list,
+        ];
+    }
+    for (const { ts, fact } of incoming) {
+        const list = facts[ts] ?? [];
+        if (!list.includes(fact)) {
+            list.push(fact);
+        }
+        facts[ts] = list;
+    }
+    // Cap: drop oldest timestamps until under maxFacts.
+    let total = 0;
+    for (const list of Object.values(facts)) {
+        total += list.length;
+    }
+    if (total <= maxFacts) {
+        return facts;
+    }
+    const sortedTs = Object.keys(facts).sort();
+    for (const ts of sortedTs) {
+        if (total <= maxFacts) {
+            break;
+        }
+        total -= facts[ts].length;
+        delete facts[ts];
+    }
+    return facts;
+}
+/** Extracts assistant/output text from newly appended items for buffering. */
+function collectText(newItems) {
+    return newItems
+        .filter((i) => i.type === 'message')
+        .map((i) => i.content
+        .filter(isOutputText)
+        .map((c) => c.text)
+        .join(''))
+        .filter((t) => t.length > 0);
+}
+//#endregion
+//#region Layer
+/**
+ * A non-atomic, LLM-backed memory layer that extracts timestamped facts from the
+ * conversation into a key-value ledger (key = ISO timestamp) and exposes a
+ * `temporal/searchMemory` tool for relative-time recall — given a fact/query it
+ * returns matching facts and, when applicable, a resolved (possibly fuzzy) date.
+ *
+ * The layer is LLM-agnostic: the host injects `extract` and `search` callbacks
+ * (mirrors `observationalMemory`'s `observer`), keeping `memory/` tree-shakable.
+ * Without them, the layer still buffers text and the search tool returns the raw
+ * ledger — it never fabricates facts. A `<current_datetime>` grounding block is
+ * injected on recall by default to anchor relative-time reasoning.
+ *
+ * @public
+ * @param config - Clock, scope, injected LLM callbacks, and tuning knobs.
+ * @returns A `MemoryLayer` with a fact-ledger store + `searchMemory` tool.
+ */
+export function temporalMemory(config) {
+    const now = config?.now ?? (() => new Date());
+    const threshold = config?.bufferThreshold ?? DEFAULT_BUFFER_THRESHOLD_TOKENS;
+    const maxFacts = config?.maxFacts ?? DEFAULT_MAX_FACTS;
+    const groundDateTime = config?.groundDateTime ?? true;
+    const injectLedger = config?.injectLedger ?? false;
+    const extract = config?.extract;
+    const search = config?.search;
+    return {
+        id: 'temporal',
+        name: 'Temporal Memory',
+        // Grounding sits near the top of the window, before reasoning content.
+        slot: Slot.REMINDER,
+        scope: config?.scope ?? 'resource',
+        budget: {
+            min: 0,
+            max: injectLedger ? 800 : 200,
+        },
+        timeouts: {
+            store: 60_000,
+        },
+        provides: {
+            searchMemory: layerFn({
+                description: 'Search remembered facts about the user by topic or fact, and resolve relative time. Returns matching facts and, when the query implies a time, a resolved date (which may be approximate).',
+                input: z.object({
+                    query: z.string(),
+                }),
+                output: z.object({
+                    facts: z.array(z.string()),
+                    date: z.string().optional(),
+                    fuzzy: z.boolean().optional(),
+                }),
+                execute: async (args, state) => {
+                    const facts = ledgerToFacts(state ?? emptyState());
+                    if (!search) {
+                        return {
+                            result: {
+                                facts: facts.map((f) => `[${f.ts}] ${f.fact}`),
+                            },
+                        };
+                    }
+                    const result = await search({
+                        query: args.query,
+                        facts,
+                        now: formatNow(now()),
+                    });
+                    return {
+                        result,
+                    };
+                },
+            }),
+        },
+        hooks: {
+            async init({ storage }) {
+                const saved = await storage.get('state');
+                return {
+                    state: saved ?? emptyState(),
+                };
+            },
+            async recall({ state }) {
+                const blocks = [];
+                if (groundDateTime) {
+                    blocks.push(renderDateTimeBlock(now()));
+                }
+                if (injectLedger) {
+                    const facts = ledgerToFacts(state ?? emptyState());
+                    if (facts.length > 0) {
+                        const lines = facts.map((f) => `- [${f.ts}] ${f.fact}`).join('\n');
+                        blocks.push(`<remembered_facts>\n${lines}\n</remembered_facts>`);
+                    }
+                }
+                if (blocks.length === 0) {
+                    return null;
+                }
+                const text = blocks.join('\n\n');
+                return {
+                    items: [
+                        createMessage(text, 'developer'),
+                    ],
+                    tokenCount: estimateTokens(text),
+                };
+            },
+            async store({ newItems, state }) {
+                const s = state ?? emptyState();
+                const texts = collectText(newItems);
+                const newBuffer = [
+                    ...s.buffer,
+                    ...texts,
+                ];
+                const newTokens = texts.reduce((sum, t) => sum + estimateTokens(t), 0);
+                const totalBufferTokens = s.bufferTokens + newTokens;
+                if (extract && totalBufferTokens >= threshold && newBuffer.length > 0) {
+                    const extracted = await extract({
+                        transcript: newBuffer.join('\n'),
+                        now: formatNow(now()),
+                    });
+                    return {
+                        state: {
+                            facts: mergeFacts(s, extracted, maxFacts),
+                            buffer: [],
+                            bufferTokens: 0,
+                            version: s.version + 1,
+                        },
+                    };
+                }
+                return {
+                    state: {
+                        ...s,
+                        buffer: newBuffer,
+                        bufferTokens: totalBufferTokens,
+                    },
+                };
+            },
+            async onSpawn({ parentState }) {
+                return {
+                    childState: structuredClone(parentState),
+                };
+            },
+        },
+    };
+}
+//#endregion

package/dist/portable/memory-layers.d.ts

@@ -7,6 +7,8 @@ export { observationalMemory } from '../memory/layers/observational-memory.js';
 /** @public */
 export { planMemory } from '../memory/layers/plan.js';
 /** @public */
+export { temporalMemory } from '../memory/layers/temporal.js';
+/** @public */
 export { toolMemoryLayer } from '../memory/layers/tool-memory-layer.js';
 /** @public */
 export { workingMemory } from '../memory/layers/working-memory.js';

package/dist/portable/memory-layers.js

@@ -7,6 +7,8 @@ export { observationalMemory } from '../memory/layers/observational-memory.js';
 /** @public */
 export { planMemory } from '../memory/layers/plan.js';
 /** @public */
+export { temporalMemory } from '../memory/layers/temporal.js';
+/** @public */
 export { toolMemoryLayer } from '../memory/layers/tool-memory-layer.js';
 /** @public */
 export { workingMemory } from '../memory/layers/working-memory.js';

package/dist/types/common.d.ts

@@ -59,4 +59,10 @@ export interface LLMResponse {
 export interface LlmProviderConfig {
     provider: 'openrouter';
     apiKey?: string;
+    /**
+     * When true, sends the `X-OpenRouter-Cache: true` request header on every
+     * model call. OpenRouter then serves identical requests from cache without
+     * re-billing — useful for deterministic re-runs (evals, regression suites).
+     */
+    cache?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noetic-tools/core",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "Step primitives, interpreter, runtime, and memory layer contract for Noetic agents.",
   "license": "Apache-2.0",