@nexalab/agent-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,518 @@
+# Nexa Agent SDK
+
+`@nexalab/agent-sdk` is a composable TypeScript SDK for building agentic assistants, workers, CLIs, app backends, durable workflows, and multi-agent systems.
+
+It is designed around a small happy path for quick integration, plus production hooks for providers, tools, approvals, storage, telemetry, memory, evals, replay, routing, policy, and evidence-backed runs.
+
+## Install
+
+```bash
+pnpm add @nexalab/agent-sdk
+```
+
+For local workspace use:
+
+```json
+{
+  "dependencies": {
+    "@nexalab/agent-sdk": "workspace:*"
+  }
+}
+```
+
+## Quick Start
+
+### Premium `agent({...})` Kernel API
+
+Five minutes from `npm install` to a running agent, with a single config object. `model` accepts a `"provider:model"` string resolved against the built-in provider presets (API key read from the matching env var, e.g. `OPENAI_API_KEY`):
+
+```ts
+import { agent } from "@nexalab/agent-sdk";
+import { z } from "zod";
+
+const assistant = await agent({
+  name: "sales-agent",
+  model: "openai:gpt-4o-mini",
+  instructions: "Eres un agente comercial. Ayudas al cliente a cotizar productos.",
+  memory: true
+});
+
+const result = await assistant.run("Cotizale 20 tanques a Abraham");
+console.log(result.text);
+```
+
+Grows into the full Kernel surface without changing shape — context engine, guardrails, hooks, sessions, structured outputs, and tools all compose onto the same object:
+
+```ts
+const result = await assistant.run("Analiza este prospecto", {
+  outputSchema: z.object({ score: z.number(), reason: z.string(), nextAction: z.string() })
+});
+result.output; // typed { score, reason, nextAction }
+
+const session = assistant.session("customer-38273");
+await session.run("Hola");
+await session.run("Recuerdas mi pedido?");
+
+const asTool = assistant.asTool(); // callable from another agent's native tool loop
+```
+
+See [Public Modules](#public-modules) below (`context`, `sessions`, `guardrails`, `hooks`, `structured-output`, `kernel`) for the building blocks this composes.
+
+### Builder API
+
+The lower-level fluent builder remains fully supported for cases that need explicit control over provider wiring, storage, and tracing:
+
+```ts
+import {
+  createAgent,
+  defineSdkTool,
+  openaiProvider,
+  createInMemoryStorage,
+  createTelemetry
+} from "@nexalab/agent-sdk";
+import { z } from "zod";
+
+const getTime = defineSdkTool({
+  id: "system.read_time",
+  capability: "system.time.read",
+  description: "Read the current system time.",
+  inputSchema: z.object({}),
+  handler: async () => ({
+    status: "ok",
+    output: { iso: new Date().toISOString() }
+  })
+});
+
+const builderAgent = await createAgent()
+  .useProvider(openaiProvider({
+    apiKey: process.env.OPENAI_API_KEY,
+    model: "gpt-4o-mini"
+  }))
+  .useTool(getTime)
+  .useStorage(createInMemoryStorage())
+  .useTelemetry(createTelemetry())
+  .useConsoleTrace()
+  .build();
+
+const result = await builderAgent.runMessage("puedes decirme que hora es?");
+console.log(result.text);
+```
+
+## Core Capabilities
+
+- Agentic task/run runtime
+- Mission runtime
+- Goal interpretation contracts
+- Success criteria and evidence model
+- Executable plan model
+- Plan validation
+- Completion gate
+- Loop guard
+- Normalized runtime events
+- Permission-aware tool registry
+- Zod-friendly tool factory
+- Local tool executor
+- Approval manager
+- Human-in-the-loop approval primitives
+- Multi-round transparent tool loop
+- Native model-requested tool-call loop
+- Async `runStream(...)` event stream
+- In-memory event bus
+- In-memory memory store
+- Advanced memory with dedupe, recency boost, and contextual retrieval
+- Vector memory with pluggable embeddings
+- JSON file storage
+- SQLite storage adapter contract
+- Postgres storage adapter contract
+- Redis storage adapter contract
+- Pluggable storage interfaces
+- Queue adapter and in-memory queue
+- OpenAI-compatible provider registry
+- Provider presets for OpenAI, OpenRouter, Ollama, and custom OpenAI-compatible APIs
+- OpenAI-compatible `/v1/models` lookup
+- OpenAI-compatible chat completions and streaming
+- Model routing and budget accounting
+- Telemetry hooks for events, tool traces, and spans
+- OpenTelemetry-compatible sink bridge
+- Agent eval harness
+- HTTP request handler
+- Checkpointed workflow runtime
+- Replay/debug timeline helpers
+- Tool policy helpers for deny/approval rules
+- Multi-agent coordinator and delegation helpers
+- Premium `agent({...})` Kernel config API on top of the builder/runtime
+- Context Engine (user/tenant/conversation/knowledge/dynamic sections, token budget, compression)
+- Sessions/threads with history, compact, reset, and fork
+- Structured outputs (real Zod -> JSON Schema conversion, typed `result.output`)
+- Guardrails (declarative input/output checks, distinct from policy/approvals)
+- Lifecycle hooks (beforeRun/afterRun/beforeModel/afterModel/beforeTool/afterTool/onError/...)
+- Skills (instructions + tool subsets injected into an agent's context and native tool loop)
+- Typed artifacts surfaced from tool evidence (`result.artifacts`)
+- Multimodal message content (text/image/file parts) across OpenAI, Anthropic, and Gemini formats
+- Native MCP client (stdio and streamable-HTTP transports, real JSON-RPC handshake and tool discovery)
+- Agent-to-agent primitives: `agent.asTool()`, `agentAsTool()`, `handoffs`, and `createTeam()` (supervisor/router/parallel strategies)
+- Knowledge/RAG (`createKnowledge`, text/file/directory sources, chunking, retrieval over the existing vector memory store)
+- Provider capability registry (vision/tools/structuredOutputs/reasoning per provider) and adaptive model routing (`strategy: "adaptive"`)
+- Pluggable response cache (`createInMemoryCache`) wired into `agent.run()`
+- Execution guarantees: real per-step retries with backoff, `WAITING_FOR_APPROVAL`/`WAITING_FOR_RETRY` states, resumable runs that skip already-completed steps
+- Secrets (`secret()` references resolved only inside tool execution, never placed into model-visible messages)
+- Tenancy: `agent.run(text, { tenant: { tenantId, userId } })` namespaces memory/cache; `config.permissions` filters tools at agent construction
+- Node-process-level workspace sandbox (`createWorkspace`, `workspaceTools`) — jailed fs root, timeout/output-capped `exec`, snapshot/restore
+- YAML agent manifests (`loadAgentManifest`) and a `nexa` CLI (`nexa run <manifest.yaml> "message"`, `nexa inspect <manifest.yaml>`)
+- `ModelHarness` — a public, overridable contract for the agent's model/tool-calling strategy (`basicHarness()` ships as the OSS reference; third parties can implement their own)
+
+## Public Modules
+
+```ts
+import { createAgent, agent } from "@nexalab/agent-sdk";
+import { openaiProvider, openRouterProvider, ollamaProvider, anthropicProvider, geminiProvider } from "@nexalab/agent-sdk/providers";
+import { defineSdkTool, toOpenAIChatTool } from "@nexalab/agent-sdk/tools";
+import { AgentRuntime } from "@nexalab/agent-sdk/runtime";
+import { createInMemoryStorage } from "@nexalab/agent-sdk/storage";
+import { createJsonFileStorage } from "@nexalab/agent-sdk/storage/file";
+import { createSqliteStorage } from "@nexalab/agent-sdk/storage/sqlite";
+import { createPostgresStorage } from "@nexalab/agent-sdk/storage/postgres";
+import { createRedisStorage } from "@nexalab/agent-sdk/storage/redis";
+import { createTelemetry } from "@nexalab/agent-sdk/telemetry";
+import { createOpenTelemetrySink } from "@nexalab/agent-sdk/telemetry/otel";
+import { runAgentEvals } from "@nexalab/agent-sdk/evals";
+import { createAgentRequestHandler } from "@nexalab/agent-sdk/http";
+import { runNativeToolLoop } from "@nexalab/agent-sdk/native-tool-loop";
+import { createWorkflowRuntime } from "@nexalab/agent-sdk/workflow";
+import { replayRun, replayEvents } from "@nexalab/agent-sdk/replay";
+import { createToolPolicy } from "@nexalab/agent-sdk/policy";
+import { createModelRouter } from "@nexalab/agent-sdk/model-router";
+import { createMultiAgentCoordinator } from "@nexalab/agent-sdk/multi-agent";
+import { createAdvancedMemoryStore } from "@nexalab/agent-sdk/advanced-memory";
+import { createVectorMemoryStore } from "@nexalab/agent-sdk/vector-memory";
+import { createInMemoryQueue } from "@nexalab/agent-sdk/queue";
+import { runHarness } from "@nexalab/agent-sdk/harness";
+import { agent, resolveModelString } from "@nexalab/agent-sdk/kernel";
+import { createContextEngine } from "@nexalab/agent-sdk/context";
+import { createSession, loadSession } from "@nexalab/agent-sdk/sessions";
+import { defineGuardrail, runInputGuardrails, runOutputGuardrails } from "@nexalab/agent-sdk/guardrails";
+import { createHookDispatcher } from "@nexalab/agent-sdk/hooks";
+import { zodSchemaToJsonSchema, parseStructuredOutput } from "@nexalab/agent-sdk/structured-output";
+```
+
+## Agent Manifests + CLI
+
+Agents can be declared as YAML and run without writing code for the identity/model/instructions surface:
+
+```yaml
+# agent.yaml
+name: nexa
+model: openai:gpt-4o-mini
+instructions: Eres un agente comercial. Ayudas al cliente a cotizar productos.
+memory: true
+```
+
+```bash
+nexa run agent.yaml "Cotizale 20 tanques a Abraham"
+nexa inspect agent.yaml
+```
+
+Tools/skills/guardrails/storage are code objects, not YAML-expressible — wire them in via `loadAgentManifest(path, extend)`:
+
+```ts
+import { loadAgentManifest } from "@nexalab/agent-sdk/manifest";
+
+const app = await loadAgentManifest("./agent.yaml", { tools: [myTool], guardrails: [myGuardrail] });
+```
+
+## Model Harness
+
+`ModelHarness` is the pluggable strategy behind `agent.run()`'s tool-calling loop — how many rounds to run, when to stop, how to react to tool results:
+
+```ts
+import { agent } from "@nexalab/agent-sdk";
+import { basicHarness, type ModelHarness } from "@nexalab/agent-sdk/model-harness";
+
+const assistant = await agent({
+  model: "openai:gpt-4o-mini",
+  name: "assistant",
+  tools: [...],
+  harness: basicHarness() // default if omitted; wraps the built-in native tool loop unchanged
+});
+```
+
+Implement `ModelHarness` directly to swap in a custom orchestration strategy:
+
+```ts
+class MyHarness implements ModelHarness {
+  async run(ctx) {
+    // ctx.client / ctx.messages / ctx.tools — same shape basicHarness() receives
+    return { text: "...", messages: ctx.messages, toolCalls: [], toolResults: [], rounds: 1 };
+  }
+}
+```
+
+Supplying any explicit harness (including `basicHarness()`) switches the loop to this Promise-based contract, which does not emit the granular `native-tool` events `agent.runStream()` emits by default — that streaming behavior is unchanged when no harness is configured. See [docs/architecture/open-core-target.md](./docs/architecture/open-core-target.md) for the design rationale.
+
+**Not to be confused with** `src/harness.ts`'s `runHarness`/`assertHarness` — an unrelated CI/release-check runner (`pnpm harness`) used to smoke-test the package before publishing. Same word, two different concepts; see the architecture docs for why they aren't merged.
+
+## Architecture
+
+The SDK is adapter-driven:
+
+- **Providers**: bring OpenAI, OpenRouter, Ollama, Anthropic, Gemini, local gateways, or any OpenAI-compatible API.
+- **Tools**: define metadata, capability, schema, and handler independently.
+- **Runtime**: create runs, plans, observations, evidence, completion decisions, and events.
+- **Storage**: persist runs, events, memory, approvals, and workflow checkpoints.
+- **Policy**: allow, deny, or require approval based on tool id/capability/name.
+- **Telemetry**: capture events, tool traces, spans, and bridge them to OpenTelemetry.
+- **Workflows**: run checkpointed DAGs for durable background jobs.
+- **Evals**: regression-test agent behavior with simple or custom judges.
+- **Replay**: turn stored run/events into a timeline for debugging and audit.
+- **Multi-agent**: delegate tasks to specialized workers by capability.
+- **Routing**: select models under priority, tag, input-size, and budget constraints.
+
+## Native Tool Loop
+
+When tools are registered, `runMessage(...)` can execute model-requested tool calls:
+
+```ts
+const result = await agent.runMessage("Read the time and answer in Spanish.");
+
+console.log(result.nativeToolTurn?.toolCalls);
+console.log(result.nativeToolTurn?.toolResults);
+```
+
+For UI and worker integrations, use the structured event stream:
+
+```ts
+for await (const event of agent.runStream("do the task")) {
+  if (event.type === "status") console.log(event.label, event.detail);
+  if (event.type === "token") process.stdout.write(event.token);
+  if (event.type === "native-tool") console.log(event.event.type);
+  if (event.type === "final") console.log(event.result.text);
+}
+```
+
+## Provider Compatibility
+
+The SDK supports three provider formats:
+
+- `openai`: OpenAI-compatible chat-completions APIs such as OpenAI, OpenRouter, Groq, Ollama, LM Studio, and compatible gateways.
+- `anthropic`: Anthropic Messages API, normalized into the SDK chat/tool-call result shape.
+- `gemini`: Gemini `generateContent`, normalized into the SDK chat/tool-call result shape.
+
+Use presets:
+
+```ts
+const openai = openaiProvider({ apiKey, model: "gpt-4o-mini" });
+const anthropic = anthropicProvider({ apiKey, model: "claude-3-5-sonnet-latest" });
+const gemini = geminiProvider({ apiKey, model: "gemini-1.5-pro" });
+```
+
+OpenAI-compatible providers support native SSE streaming. Anthropic and Gemini currently normalize non-streaming responses through the same `complete(...)` contract and expose a final stream chunk through `stream(...)`.
+
+## Storage
+
+In-memory storage is useful for tests and demos:
+
+```ts
+const storage = createInMemoryStorage();
+```
+
+JSON file storage is useful for local durable workers:
+
+```ts
+const storage = createJsonFileStorage("./.nexa");
+```
+
+SQLite is exposed as a driver adapter, so the SDK does not force a native dependency:
+
+```ts
+const storage = createSqliteStorage(db);
+```
+
+Postgres and Redis are also exposed as driver adapters:
+
+```ts
+const postgresStorage = createPostgresStorage(pgClient);
+await postgresStorage.migrate();
+
+const redisStorage = createRedisStorage(redisClient, "my-app:nexa");
+```
+
+## Workflows
+
+```ts
+const workflow = createWorkflowRuntime({ storage });
+
+const run = workflow.create({
+  name: "ship-report",
+  nodes: [
+    { id: "collect", title: "Collect", run: () => ({ ok: true }) },
+    { id: "verify", title: "Verify", dependsOn: ["collect"], run: () => ({ verified: true }) }
+  ]
+});
+
+await workflow.run({ runId: run.id, nodes });
+```
+
+## Policy And Approvals
+
+```ts
+const policy = createToolPolicy([
+  ...requireApprovalForCapabilities(["filesystem.write"], "LOCAL_WRITE"),
+  ...denyCapabilities(["system.delete"])
+]);
+
+const risk = policy.approvalRiskFor(tool);
+```
+
+## Evals
+
+```ts
+const report = await runAgentEvals({
+  agent,
+  cases: [
+    { id: "time-es", input: "que hora es?", expected: ["hora"] }
+  ]
+});
+```
+
+## Model Routing
+
+```ts
+const router = createModelRouter([
+  { id: "fast", providerId: "openai", model: "gpt-4o-mini", priority: 10, tags: ["fast"] },
+  { id: "deep", providerId: "openai", model: "gpt-4.1", priority: 5, tags: ["deep"] }
+], {
+  maxCalls: 100,
+  maxEstimatedCost: 5
+});
+
+const decision = router.select({ prompt: "summarize this", requiredTags: ["fast"] });
+router.record(decision);
+```
+
+## Multi-Agent
+
+```ts
+const coordinator = createMultiAgentCoordinator([
+  {
+    id: "builder",
+    description: "Builds SDK integrations",
+    capabilities: ["code", "examples"],
+    run: async ({ task }) => agent.runMessage(task)
+  }
+]);
+
+const delegated = await coordinator.delegate({
+  task: "build an integration example",
+  requiredCapabilities: ["examples"]
+});
+```
+
+## Examples
+
+The examples are documented in `examples/README.md`.
+
+Run the full offline frontier v3 tour:
+
+```bash
+pnpm demo:v3
+```
+
+That example walks through:
+
+- JSON storage
+- Telemetry
+- Advanced memory
+- Tool definitions
+- Policy and approvals
+- Checkpointed workflows
+- Multi-agent coordination
+- Model routing and budget accounting
+- Evals
+- HTTP adapter
+- Replay/debug timeline
+
+Other useful demos:
+
+```bash
+pnpm demo:message
+pnpm demo:chain
+pnpm demo:chat
+pnpm demo:native-loop
+pnpm demo:stream
+pnpm demo:storage
+pnpm demo:evals
+pnpm demo:http
+pnpm demo:workflow
+pnpm demo:policy
+pnpm demo:telemetry
+```
+
+## Environment
+
+For real provider calls:
+
+```bash
+NEXA_BASE_URL=https://api.openai.com
+NEXA_API_KEY=...
+NEXA_MODEL=gpt-4o-mini
+NEXA_TRACE=1
+```
+
+PowerShell example:
+
+```powershell
+$env:NEXA_BASE_URL="https://api.openai.com"
+$env:NEXA_API_KEY="..."
+$env:NEXA_MODEL="gpt-4o-mini"
+pnpm demo:chat
+```
+
+OpenRouter example:
+
+```powershell
+$env:NEXA_BASE_URL="https://openrouter.ai/api"
+$env:NEXA_API_KEY="..."
+$env:NEXA_MODEL="openai/gpt-4o-mini"
+pnpm demo:chat
+```
+
+## Current Status
+
+This package currently targets Node.js `>=22.19.0`, TypeScript, ESM, and OpenAI-compatible chat APIs.
+
+The package is designed to stay dependency-light. Optional production integrations such as SQLite drivers, OpenTelemetry SDKs, web frameworks, vector databases, and queues are expected to be provided by the host app through adapters.
+
+## Production Checks
+
+```bash
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm smoke
+pnpm harness
+pnpm pack:check
+```
+
+Recommended production wiring:
+
+- Use `createPostgresStorage(...)` or `createRedisStorage(...)` for app backends.
+- Use `createJsonFileStorage(...)` for local workers and desktop apps.
+- Use `createOpenTelemetrySink(...)` for traces.
+- Use `createToolPolicy(...)` plus `ApprovalManager` for risky tools.
+- Use `runStream(...)` for UI or server-sent-event style integration.
+- Use `runAgentEvals(...)` in CI for regression protection.
+- Use `createVectorMemoryStore(...)` with your embedding provider for semantic memory.
+- Use `pnpm harness` as the production readiness gate.
+- Use `pnpm smoke` and `pnpm pack:check` before publishing.
+
+## Is It Frontier?
+
+Yes, this is now a frontier-style agent SDK architecture: native tool calling, structured streaming, durable storage adapters, policy/approvals, evals, telemetry, replay, workflows, routing, multi-agent coordination, vector memory, queue contracts, package smoke checks, and a production harness.
+
+The SDK intentionally stays dependency-light. Production apps still provide their actual infrastructure drivers and deployment policy through adapters.
+
+## Open-core architecture
+
+This package is designed as the fully-capable public half of an open-core split — see [docs/architecture/open-core-audit.md](./docs/architecture/open-core-audit.md), [open-core-target.md](./docs/architecture/open-core-target.md), and [open-core-migration.md](./docs/architecture/open-core-migration.md) for the module-by-module classification, target architecture, and phased plan. In short: everything in this repository is public and production-capable; strategic/proprietary intelligence (e.g. a future `FrontierHarness`) is designed to live in a separate private repository that *implements* this SDK's public contracts (`ModelHarness`, `ModelRoute`, `ContextEngineConfig`, ...) rather than forking or being vendored into it.
+
+`pnpm verify:boundaries`, `pnpm verify:secrets`, and `pnpm verify:publish-safety` (all folded into `pnpm prepublish:check`) guard against private code or secrets ever entering an npm-published tarball from this repo.

package/bin/nexa.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { loadAgentManifest } from "../dist/manifest.js";
+
+const [, , command, manifestPath, ...rest] = process.argv;
+
+function usage() {
+  console.error("Usage: nexa <run|inspect> <manifest.yaml> [message...]");
+  process.exit(1);
+}
+
+if (!command || !manifestPath || !["run", "inspect"].includes(command)) usage();
+
+try {
+  const agent = await loadAgentManifest(manifestPath);
+
+  if (command === "inspect") {
+    console.log(JSON.stringify({ name: agent.name, model: agent.underlying.model }, null, 2));
+    process.exit(0);
+  }
+
+  const message = rest.join(" ");
+  if (!message) {
+    console.error("nexa run requires a message, e.g.: nexa run agent.yaml \"hola\"");
+    process.exit(1);
+  }
+
+  const result = await agent.run(message);
+  console.log(result.text);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

package/dist/advanced-memory.d.ts

@@ -0,0 +1,32 @@
+import { MemoryStore, type MemoryKind, type MemoryRecord, type MemorySearchResult } from "./memory.js";
+import type { JsonObject } from "./types.js";
+export type AdvancedMemoryOptions = {
+    duplicateThreshold?: number;
+    decayHalfLifeDays?: number;
+};
+export declare class AdvancedMemoryStore extends MemoryStore {
+    private readonly advancedOptions;
+    constructor(advancedOptions?: AdvancedMemoryOptions);
+    writeUnique(input: {
+        kind: MemoryKind;
+        content: string;
+        source?: string;
+        tags?: string[];
+        confidence?: number;
+        importance?: number;
+        metadata?: JsonObject;
+    }): MemoryRecord;
+    contextualSearch(input: {
+        query: string;
+        tags?: string[];
+        kind?: MemoryKind;
+        limit?: number;
+        now?: Date;
+    }): MemorySearchResult[];
+    compact(input: {
+        maxRecords: number;
+    }): MemoryRecord[];
+    private findDuplicate;
+}
+export declare function createAdvancedMemoryStore(options?: AdvancedMemoryOptions): AdvancedMemoryStore;
+//# sourceMappingURL=advanced-memory.d.ts.map

package/dist/advanced-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced-memory.d.ts","sourceRoot":"","sources":["../src/advanced-memory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACvG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,qBAAqB,GAAG;IAClC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,qBAAa,mBAAoB,SAAQ,WAAW;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe;gBAAf,eAAe,GAAE,qBAA0B;IAIxE,WAAW,CAAC,KAAK,EAAE;QACjB,IAAI,EAAE,UAAU,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,UAAU,CAAC;KACvB,GAAG,YAAY;IAMhB,gBAAgB,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,IAAI,CAAC,EAAE,UAAU,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,IAAI,CAAA;KAAE,GAAG,kBAAkB,EAAE;IAUhI,OAAO,CAAC,KAAK,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,YAAY,EAAE;IAOtD,OAAO,CAAC,aAAa;CAItB;AAED,wBAAgB,yBAAyB,CAAC,OAAO,GAAE,qBAA0B,GAAG,mBAAmB,CAElG"}

package/dist/advanced-memory.js

@@ -0,0 +1,54 @@
+import { MemoryStore } from "./memory.js";
+export class AdvancedMemoryStore extends MemoryStore {
+    advancedOptions;
+    constructor(advancedOptions = {}) {
+        super();
+        this.advancedOptions = advancedOptions;
+    }
+    writeUnique(input) {
+        const duplicate = this.findDuplicate(input.content);
+        if (duplicate)
+            return duplicate;
+        return this.write(input);
+    }
+    contextualSearch(input) {
+        const now = input.now ?? new Date();
+        return this.search(input.query, Math.max(input.limit ?? 10, 25))
+            .filter((record) => !input.kind || record.kind === input.kind)
+            .filter((record) => !input.tags?.length || input.tags.every((tag) => record.tags.includes(tag)))
+            .map((record) => ({ ...record, score: record.score + record.importance + recencyBoost(record, now, this.advancedOptions.decayHalfLifeDays ?? 30) }))
+            .sort((a, b) => b.score - a.score)
+            .slice(0, input.limit ?? 10);
+    }
+    compact(input) {
+        const records = this.list()
+            .sort((a, b) => b.importance - a.importance || b.confidence - a.confidence)
+            .slice(0, input.maxRecords);
+        return records;
+    }
+    findDuplicate(content) {
+        const threshold = this.advancedOptions.duplicateThreshold ?? 0.9;
+        return this.list().find((record) => similarity(record.content, content) >= threshold);
+    }
+}
+export function createAdvancedMemoryStore(options = {}) {
+    return new AdvancedMemoryStore(options);
+}
+function recencyBoost(record, now, halfLifeDays) {
+    const ageMs = Math.max(0, now.getTime() - new Date(record.createdAt).getTime());
+    const ageDays = ageMs / 86_400_000;
+    return Math.pow(0.5, ageDays / halfLifeDays);
+}
+function similarity(a, b) {
+    const left = new Set(tokens(a));
+    const right = new Set(tokens(b));
+    if (!left.size || !right.size)
+        return 0;
+    const intersection = [...left].filter((term) => right.has(term)).length;
+    const union = new Set([...left, ...right]).size;
+    return intersection / union;
+}
+function tokens(value) {
+    return value.toLowerCase().split(/[^a-z0-9_áéíóúñ]+/i).filter(Boolean);
+}
+//# sourceMappingURL=advanced-memory.js.map

package/dist/advanced-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced-memory.js","sourceRoot":"","sources":["../src/advanced-memory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAA+D,MAAM,aAAa,CAAC;AAQvG,MAAM,OAAO,mBAAoB,SAAQ,WAAW;IACrB;IAA7B,YAA6B,kBAAyC,EAAE;QACtE,KAAK,EAAE,CAAC;QADmB,oBAAe,GAAf,eAAe,CAA4B;IAExE,CAAC;IAED,WAAW,CAAC,KAQX;QACC,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACpD,IAAI,SAAS;YAAE,OAAO,SAAS,CAAC;QAChC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;IAED,gBAAgB,CAAC,KAAwF;QACvG,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;QACpC,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;aAC7D,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI,CAAC;aAC7D,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;aAC/F,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,UAAU,GAAG,YAAY,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,eAAe,CAAC,iBAAiB,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;aACnJ,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;aACjC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,CAAC,KAA6B;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE;aACxB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;aAC1E,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QAC9B,OAAO,OAAO,CAAC;IACjB,CAAC;IAEO,aAAa,CAAC,OAAe;QACnC,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,CAAC,kBAAkB,IAAI,GAAG,CAAC;QACjE,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,SAAS,CAAC,CAAC;IACxF,CAAC;CACF;AAED,MAAM,UAAU,yBAAyB,CAAC,UAAiC,EAAE;IAC3E,OAAO,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,YAAY,CAAC,MAAoB,EAAE,GAAS,EAAE,YAAoB;IACzE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAChF,MAAM,OAAO,GAAG,KAAK,GAAG,UAAU,CAAC;IACnC,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,GAAG,YAAY,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,UAAU,CAAC,CAAS,EAAE,CAAS;IACtC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI;QAAE,OAAO,CAAC,CAAC;IACxC,MAAM,YAAY,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;IACxE,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IAChD,OAAO,YAAY,GAAG,KAAK,CAAC;AAC9B,CAAC;AAED,SAAS,MAAM,CAAC,KAAa;IAC3B,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACzE,CAAC"}