@easynet/agent-memory 0.0.2 → 1.0.1

package/README.md

@@ -1,260 +1,125 @@
 # agent-memory
 
-一个简单易用的 Agent 记忆管理 SDK，支持长期记忆存储、文档记忆和多模态文档处理。
+**Source:** `git@github.com:easynet-world/agent-memory.git`
 
-## 快速开始
+**Agent 生态记忆组件**（**独立项目**：不依赖 agent-llm、agent-tool）。**Two APIs only:** `memorize` (store) and `recall` (retrieve).
 
-```bash
-npm install agent-memory
-```
-
-```typescript
-import { AgentMemory } from "agent-memory";
-
-const am = await AgentMemory.fromYaml("./agent-memory.yaml");
-
-// 记忆对话
-await am.remember({
-  messages: [
-    { role: "user", content: "发布流程：先 dc-dev-testing，再 dc-prod" }
-  ],
-  actor: { id: "U123", type: "user" },
-  scope: { projectId: "bds" },
-});
-
-// 记忆文档（支持多模态）
-await am.rememberDocument({
-  document: {
-    id: "doc_001",
-    type: "pdf",
-    text: "PDF提取的文本内容...",
-    metadata: { title: "技术文档", path: "/docs/tech.pdf" },
-  },
-  actor: { id: "system", type: "system" },
-  scope: { projectId: "main-project" },
-});
-
-// 召回
-const result = await am.recall({
-  query: "发布流程是什么？",
-  scope: { projectId: "bds" },
-});
-
-console.log(result.context);
-```
+Local or remote PDF, txt, HTML, and images: pass a `url` to ingest; recall by `query`.
 
-## 主要特性
+**Three memory types:**
 
-- ✅ **双模式支持**：Platform API 模式 和 In-Memory 模式（SQLite + 向量索引）
-- ✅ **文档记忆**：支持文本、PDF、图片、Markdown、HTML、代码等多种文档类型
-- ✅ **多模态支持**：图片OCR文本、PDF分页、代码文档等
-- ✅ **自动分块**：大文档自动分块，支持重叠窗口
-- ✅ **MemoryGate**：脱敏、抽取、过滤、去重
-- ✅ **向量检索**：基于 Embedding 的语义搜索
-- ✅ **YAML配置**：简单易用的配置文件
+| type | Description | Usage |
+|------|-------------|-------|
+| `thread` | Current session | This session only |
+| `cross_thread` | Cross-session | Cross-session preferences/settings |
+| `knowledge` | Docs/RAG | Documents or `memorize({ url })` |
 
-## 文档记忆
+When unsure about type: pass a `classifyMemory` callback and let the program decide.
 
-支持多种文档类型：
+---
 
-- `text` - 纯文本
-- `pdf` - PDF文档（支持分页）
-- `image` - 图片（支持OCR文本）
-- `markdown` - Markdown文档
-- `html` - HTML文档
-- `code` - 代码文件
+## Quick start
 
-```typescript
-// 记忆PDF文档（自动分块）
-await am.rememberDocument({
-  document: {
-    id: "pdf_001",
-    type: "pdf",
-    text: "PDF内容...",
-    page: 1,
-    metadata: { title: "文档", pageCount: 50 },
-  },
-  autoChunk: true,
-  chunkSize: 1000,
-  extractMetadata: true,
-});
-
-// 记忆图片（带OCR）
-await am.rememberDocument({
-  document: {
-    id: "img_001",
-    type: "image",
-    text: "图片描述",
-    extractedText: "OCR提取的文字",
-    imageUrl: "https://example.com/image.png",
-  },
-});
+```bash
+pnpm install && pnpm run build
+# SQLite persistence: pnpm add better-sqlite3
 ```
 
-详细文档请参考 [docs/DOCUMENT_MEMORY.md](./docs/DOCUMENT_MEMORY.md)
-
-## 配置
-
-创建 `agent-memory.yaml`：
-
-```yaml
-store:
-  mem0:
-    mode: in_memory  # 或 platform
-
-persistence:
-  sqlite:
-    path: ./data/memory.db
-
-embedding:
-  provider: ollama
-  model: embedding-gemma:latest
-
-memory:
-  gate:
-    enabled: true
-    redact:
-      enabled: true
-    dedupe:
-      enabled: true
-      similarity_threshold: 0.92
-```
+---
 
-## 两种运行模式
+## Examples
 
-### 1. Platform 模式（Mem0 Platform API）
+```ts
+import { createAgentMemory } from "@easynet/agent-memory";
 
-使用 Mem0 Platform 作为后端：
+const memory = await createAgentMemory();
 
-```yaml
-store:
-  mem0:
-    mode: platform
-    api_key: ${MEM0_API_KEY}
-    base_url: https://api.mem0.ai
+await memory.memorize({ namespace: "user:123", type: "cross_thread", content: "Use Chinese." });
+await memory.memorize({ namespace: "project:docs", type: "knowledge", content: "API: Bearer token." });
+const { injectedText } = await memory.recall({ namespace: "user:123", query: "preferences", topK: 8 });
 ```
 
-### 2. In-Memory 模式（本地SQLite + 向量索引）
-
-完全本地运行，使用 SQLite 存储和内存向量索引：
-
-```yaml
-store:
-  mem0:
-    mode: in_memory
-
-persistence:
-  sqlite:
-    path: ./data/memory.db
+**URL ingest** (supported by `createAgentMemory()`; PDF requires `pdf-parse`):
 
-embedding:
-  provider: ollama
-  model: embedding-gemma:latest
+```ts
+import { createAgentMemory } from "@easynet/agent-memory";
+const memory = await createAgentMemory();
+await memory.memorize({ url: "./doc.pdf", namespace: "project:docs" });
+await memory.memorize({ url: "https://example.com/page.html", namespace: "project:docs" });
 ```
 
-## API
-
-### remember()
+**LangChain Agent** (inject memory before calling LLM; write memory after each turn):
 
-记忆对话或文本：
-
-```typescript
-await am.remember({
-  messages: [{ role: "user", content: "..." }],
-  // 或
-  text: "...",
-  actor: { id: "U123", type: "user" },
-  scope: { projectId: "bds" },
-  hint: { types: ["policy", "episodic"] },
-});
+```ts
+import { createAgentMemory, retrieveContextForLangChain, writeMemoryForLangChain } from "@easynet/agent-memory";
+const memory = await createAgentMemory();
+const ns = "user:alice";
+// Before LLM: retrieve relevant memory, inject into system or first user message
+const { injectedText } = await retrieveContextForLangChain(memory, { namespace: ns, query: "preferences and settings", topK: 8 });
+// After each turn/tool: write long-term memory
+await writeMemoryForLangChain(memory, { namespace: ns, type: "cross_thread", content: "User prefers Chinese and concise replies." });
 ```
 
-### rememberDocument()
-
-记忆文档（支持多模态）：
-
-```typescript
-await am.rememberDocument({
-  document: DocumentChunk | DocumentChunk[],
-  actor?: Actor,
-  scope?: Scope,
-  autoChunk?: boolean,
-  chunkSize?: number,
-  extractMetadata?: boolean,
-  tags?: string[],
+**DeepAgents** (agent-memory as long-term store under `/memories/`):
+
+```ts
+import { createAgentMemory, AgentMemoryStoreAdapter } from "@easynet/agent-memory";
+import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";
+const agentMemory = await createAgentMemory();
+const store = new AgentMemoryStoreAdapter({ agentMemory });
+const agent = createDeepAgent({
+  store,
+  backend: (c) => new CompositeBackend(new StateBackend(c), { "/memories/": new StoreBackend(c) }),
+  systemPrompt: "When users state preferences, save to /memories/user_preferences.txt",
 });
 ```
 
-### recall()
-
-召回记忆和文档：
-
-```typescript
-const result = await am.recall({
-  query: "发布流程是什么？",
-  actor: { id: "U123", type: "user" },
-  scope: { projectId: "bds" },
-  topK: 10,
-  includeMemory: true,
-  includeDocs: true,
-});
-```
+---
 
-## 项目结构
+## Config (YAML)
 
-```
-src/
-├── core/                   # 核心类
-│   └── agent-memory.ts     # 主类
-├── adapters/               # 适配器（Mem0, RAG HTTP）
-├── storage/               
-│   ├── persistence/        # SQLite持久化
-│   └── indexing/          # In-Memory向量索引
-├── processing/
-│   ├── gate/              # MemoryGate
-│   ├── embedding/         # Embedding计算
-│   ├── recall/            # 召回引擎
-│   ├── ranker/            # 排序器
-│   ├── context/           # Context构建
-│   └── document/          # 文档处理
-├── boot/                   # 启动回灌
-├── config/                 # 配置加载
-├── types/                  # 类型定义
-└── cli/                    # Chat Console
+Config file `config/agent-memory.yaml`; omit for in-memory default.
 
-test-configs/               # 测试配置文件
+```yaml
+providers:
+  - id: default
+    type: sqlite
+    options:
+      dbPath: ./data/agent-memory.db
+  - id: rag
+    type: rag
+  - id: mem0
+    type: mem0
+router:
+  defaultProvider: default
+  rules:
+    - types: [knowledge]
+      providerId: rag
+    - types: [cross_thread]
+      providerId: mem0
+policy:
+  allowedWriteTypes: [thread, cross_thread, knowledge]
+  maxItemsPerType: 20
+observability:
+  trace: true
+privacy:
+  forbiddenMetadataKeys: [password, api_key, secret, token]
+  redactSecrets: false
+vlm:
+  captionUrl: http://localhost:8000/caption
+  captionPrompt: "Extract key information from the image..."
+  timeoutMs: 30000
 ```
 
-**代码规范**:
-- ✅ 所有文件不超过 500 行
-- ✅ 文件命名使用 kebab-case
-- ✅ 清晰的模块职责分离
-
-详细结构说明请参考 [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md)
-
-## 开发
-
-```bash
-# 安装依赖
-npm install
-
-# 构建
-npm run build
-
-# 测试
-npm test
-
-# Chat Console
-npm run chat
-npm run chat:split
-```
+- **Namespace:** `user:{id}` / `project:{id}` / `org:{id}`
+- **SQLite:** `type: sqlite` + `options.dbPath`; requires `pnpm add better-sqlite3`; optional `options.embed` for vector search
+- **Mem0:** `type: mem0`; in code use `createAgentMemory({ overrides: { mem0 } })`
+- **VLM:** image→caption written as knowledge; `loadConfigFromYaml()` yields `config.vlm`
 
-## 示例
+---
 
-- `examples/basic-usage.ts` - 基本用法
-- `examples/document-memory.ts` - 文档记忆示例
-- `examples/chat-example.ts` - Chat Console 示例
+**Trace / Privacy:** `recall()` returns `traceId`; configurable TraceRecorder and PrivacyGuard.
 
-## License
+**Layout:** 根目录主包（src/、test/、docs/、examples/）· `examples/pdf-text-rag` · `examples/deepagents-memory`
 
-MIT
+**License:** MIT

package/dist/src/core/agent-memory.d.ts

@@ -0,0 +1,41 @@
+/**
+ * AgentMemory: unified facade. Primary APIs: memorize (store), recall (retrieve).
+ * write / retrieveForPrompt kept as aliases for compatibility.
+ */
+import type { MemoryItem, MemoryQueryRequest, MemoryType, MemoryWriteRequest, MemorizeRequest, RecallResult, RetrieveResult } from "./types.js";
+import { PolicyEngine } from "./policy.js";
+import type { TraceRecorder } from "./observability.js";
+import { PrivacyGuard } from "./privacy.js";
+import { MemoryRouter } from "./router.js";
+/** When type is omitted: infer thread/cross_thread/knowledge from content; if not provided, default cross_thread. */
+export type ClassifyMemoryFn = (content: string, metadata?: Record<string, unknown>) => Promise<MemoryType>;
+export interface AgentMemoryOptions {
+    router: MemoryRouter;
+    policy?: PolicyEngine;
+    traceRecorder?: TraceRecorder;
+    privacyGuard?: PrivacyGuard;
+    /** When type omitted: used to decide type; otherwise default cross_thread. */
+    classifyMemory?: ClassifyMemoryFn;
+}
+export declare class AgentMemory {
+    private router;
+    private policy;
+    private traceRecorder?;
+    private privacy;
+    private classifyMemory?;
+    constructor(options: AgentMemoryOptions);
+    /** Store one memory (primary API). Type from classifyMemory or default cross_thread when omitted. */
+    memorize(req: MemorizeRequest): Promise<MemoryItem>;
+    /** @deprecated Use memorize */
+    write(req: MemoryWriteRequest): Promise<MemoryItem>;
+    /** Retrieve memories for query and build injectable text (primary API). Default types: knowledge, cross_thread. */
+    recall(req: MemoryQueryRequest): Promise<RecallResult>;
+    /** @deprecated Use recall */
+    retrieveForPrompt(req: MemoryQueryRequest): Promise<RetrieveResult>;
+    deleteByNamespace(namespace: string): Promise<void>;
+    /** Get one item by namespace and key (e.g. path). Requires provider to support getByKey. */
+    getByKey(namespace: string, key: string): Promise<MemoryItem | null>;
+    /** Delete item by namespace and key. */
+    deleteByKey(namespace: string, key: string): Promise<void>;
+}
+//# sourceMappingURL=agent-memory.d.ts.map

package/dist/src/core/agent-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-memory.d.ts","sourceRoot":"","sources":["../../../src/core/agent-memory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,cAAc,EACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,qHAAqH;AACrH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC/B,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,8EAA8E;IAC9E,cAAc,CAAC,EAAE,gBAAgB,CAAC;CACnC;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,cAAc,CAAC,CAAmB;gBAE9B,OAAO,EAAE,kBAAkB;IAQvC,qGAAqG;IAC/F,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IAmCzD,+BAA+B;IACzB,KAAK,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC;IAIzD,mHAAmH;IAC7G,MAAM,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IA+C5D,6BAA6B;IACvB,iBAAiB,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;IAInE,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYzD,4FAA4F;IACtF,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAI1E,wCAAwC;IAClC,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGjE"}

package/dist/src/core/agent-memory.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * AgentMemory: unified facade. Primary APIs: memorize (store), recall (retrieve).
+ * write / retrieveForPrompt kept as aliases for compatibility.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentMemory = void 0;
+const policy_js_1 = require("./policy.js");
+const observability_js_1 = require("./observability.js");
+const privacy_js_1 = require("./privacy.js");
+const node_crypto_1 = require("node:crypto");
+class AgentMemory {
+    router;
+    policy;
+    traceRecorder;
+    privacy;
+    classifyMemory;
+    constructor(options) {
+        this.router = options.router;
+        this.policy = options.policy ?? new policy_js_1.PolicyEngine();
+        this.traceRecorder = options.traceRecorder;
+        this.privacy = options.privacyGuard ?? new privacy_js_1.PrivacyGuard();
+        this.classifyMemory = options.classifyMemory;
+    }
+    /** Store one memory (primary API). Type from classifyMemory or default cross_thread when omitted. */
+    async memorize(req) {
+        let type = req.type;
+        if (type === undefined) {
+            if (this.classifyMemory && req.content) {
+                type = await this.classifyMemory(req.content, req.metadata);
+            }
+            else {
+                type = "cross_thread";
+            }
+        }
+        const writeReq = { ...req, type };
+        const allowed = this.policy.shouldWrite({
+            namespace: writeReq.namespace,
+            type: writeReq.type,
+            content: writeReq.content,
+            metadata: writeReq.metadata,
+        });
+        if (!allowed) {
+            throw new Error(`Write not allowed by policy for type: ${writeReq.type}`);
+        }
+        const raw = writeReq.metadata;
+        const metadata = raw
+            ? this.privacy.sanitizeMetadata(raw)
+            : {};
+        const now = new Date().toISOString();
+        const finalReq = {
+            ...writeReq,
+            metadata: {
+                ...metadata,
+                created_at: metadata.created_at ?? now,
+                updated_at: now,
+            },
+        };
+        return this.router.write(finalReq);
+    }
+    /** @deprecated Use memorize */
+    async write(req) {
+        return this.memorize(req);
+    }
+    /** Retrieve memories for query and build injectable text (primary API). Default types: knowledge, cross_thread. */
+    async recall(req) {
+        const traceId = (0, node_crypto_1.randomUUID)();
+        const start = Date.now();
+        const topK = req.topK ?? 8;
+        const budgetTokens = req.budgetTokens ?? 1200;
+        const types = req.types ?? ["knowledge", "cross_thread"];
+        const items = await this.router.query({
+            ...req,
+            types: [...types],
+            topK: Math.max(topK, Math.ceil(budgetTokens / 50)),
+        });
+        const { items: merged, estimatedTokens } = this.policy.mergeAndRank(items, budgetTokens);
+        const injectedText = merged
+            .map((i) => `[${i.type}] ${i.content}`)
+            .join("\n\n");
+        const latencyMs = Date.now() - start;
+        if (this.traceRecorder) {
+            const backendDistribution = {};
+            for (const item of merged) {
+                backendDistribution[item.type] = (backendDistribution[item.type] ?? 0) + 1;
+            }
+            this.traceRecorder.record((0, observability_js_1.createTrace)(traceId, req.namespace, {
+                query: req.query,
+                hitIds: merged.map((i) => i.id),
+                hitTypes: merged.map((i) => i.type),
+                injectedTokens: estimatedTokens,
+                latencyMs,
+                backendDistribution,
+            }));
+        }
+        return {
+            items: merged,
+            injectedText,
+            traceId,
+        };
+    }
+    /** @deprecated Use recall */
+    async retrieveForPrompt(req) {
+        return this.recall(req);
+    }
+    async deleteByNamespace(namespace) {
+        const req = {
+            namespace,
+            query: "",
+            topK: 10_000,
+        };
+        const items = await this.router.query(req);
+        for (const item of items) {
+            await this.router.delete(item.id, namespace);
+        }
+    }
+    /** Get one item by namespace and key (e.g. path). Requires provider to support getByKey. */
+    async getByKey(namespace, key) {
+        return this.router.getByKey(namespace, key);
+    }
+    /** Delete item by namespace and key. */
+    async deleteByKey(namespace, key) {
+        return this.router.deleteByKey(namespace, key);
+    }
+}
+exports.AgentMemory = AgentMemory;
+//# sourceMappingURL=agent-memory.js.map

package/dist/src/core/agent-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-memory.js","sourceRoot":"","sources":["../../../src/core/agent-memory.ts"],"names":[],"mappings":"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"}

package/dist/src/core/config.d.ts

@@ -0,0 +1,78 @@
+/**
+ * YAML config types and loader. Config-driven; no use-case hardcoding.
+ */
+import type { MemoryType } from "./types.js";
+export interface AgentMemoryProviderConfig {
+    id: string;
+    type: "in_memory" | "rag" | "mem0" | "sqlite";
+    /** sqlite: dbPath, etc.; rag: embed/search; mem0: pass instance via overrides at runtime */
+    options?: Record<string, unknown>;
+}
+export interface AgentMemoryRouterConfig {
+    defaultProvider: string;
+    /** Which types/namespacePrefix go to which providerId; no use-case keywords. */
+    rules?: Array<{
+        types?: string[];
+        namespacePrefix?: string;
+        providerId: string;
+    }>;
+}
+export interface AgentMemoryPolicyConfig {
+    allowedWriteTypes?: MemoryType[];
+    maxItemsPerType?: number;
+    budgetPerType?: Partial<Record<MemoryType, number>>;
+}
+export interface AgentMemoryObservabilityConfig {
+    trace?: boolean;
+}
+export interface AgentMemoryPrivacyConfig {
+    /** Metadata keys to strip before storing. Omit to use built-in defaults; set [] to allow all. */
+    forbiddenMetadataKeys?: string[];
+    /** If true, redact content that looks like secrets before storing (when implemented). */
+    redactSecrets?: boolean;
+}
+/** mem0ai Memory options (same shape as mem0ai/oss Memory config; can be in YAML) */
+export interface Mem0Config {
+    version?: string;
+    embedder?: {
+        provider?: string;
+        config?: Record<string, unknown>;
+    };
+    vectorStore?: {
+        provider?: string;
+        config?: Record<string, unknown>;
+    };
+    llm?: {
+        provider?: string;
+        config?: Record<string, unknown>;
+    };
+    historyStore?: {
+        provider?: string;
+        config?: Record<string, unknown>;
+    };
+    historyDbPath?: string;
+    disableHistory?: boolean;
+    customPrompt?: string;
+    [key: string]: unknown;
+}
+/** VLM config for image→caption at index time (can be in YAML) */
+export interface VlmConfig {
+    captionUrl?: string;
+    captionPrompt?: string;
+    timeoutMs?: number;
+    [key: string]: unknown;
+}
+export interface AgentMemoryConfig {
+    providers: AgentMemoryProviderConfig[];
+    router: AgentMemoryRouterConfig;
+    policy?: AgentMemoryPolicyConfig;
+    observability?: AgentMemoryObservabilityConfig;
+    privacy?: AgentMemoryPrivacyConfig;
+    mem0?: Mem0Config;
+    vlm?: VlmConfig;
+}
+/**
+ * Load config from YAML file; returns default if file not found.
+ */
+export declare function loadConfigFromYaml(configPath: string): Promise<AgentMemoryConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/src/core/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/core/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC9C,4FAA4F;IAC5F,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,uBAAuB;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,KAAK,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACnF;AAED,MAAM,WAAW,uBAAuB;IACtC,iBAAiB,CAAC,EAAE,UAAU,EAAE,CAAC;IACjC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,8BAA8B;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,iGAAiG;IACjG,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,yFAAyF;IACzF,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,qFAAqF;AACrF,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IACnE,WAAW,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IACtE,GAAG,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAC9D,YAAY,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,yBAAyB,EAAE,CAAC;IACvC,MAAM,EAAE,uBAAuB,CAAC;IAChC,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,aAAa,CAAC,EAAE,8BAA8B,CAAC;IAC/C,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,GAAG,CAAC,EAAE,SAAS,CAAC;CACjB;AAYD;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CASvF"}

package/dist/src/core/config.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * YAML config types and loader. Config-driven; no use-case hardcoding.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfigFromYaml = loadConfigFromYaml;
+const DEFAULT_CONFIG = {
+    providers: [{ id: "default", type: "in_memory" }],
+    router: { defaultProvider: "default", rules: [] },
+    policy: {},
+    observability: { trace: false },
+    privacy: {},
+    mem0: undefined,
+    vlm: undefined,
+};
+/**
+ * Load config from YAML file; returns default if file not found.
+ */
+async function loadConfigFromYaml(configPath) {
+    const path = await import("node:path");
+    const { loadYamlFile } = await import("@easynet/agent-common");
+    const resolved = path.resolve(configPath);
+    const parsed = await loadYamlFile(resolved, {
+        substituteEnv: false,
+    });
+    if (!parsed)
+        return DEFAULT_CONFIG;
+    return mergeConfig(DEFAULT_CONFIG, parsed);
+}
+function mergeConfig(base, overrides) {
+    return {
+        providers: overrides.providers ?? base.providers,
+        router: overrides.router ?? base.router,
+        policy: { ...base.policy, ...overrides.policy },
+        observability: { ...base.observability, ...overrides.observability },
+        privacy: { ...base.privacy, ...overrides.privacy },
+        mem0: overrides.mem0 ?? base.mem0,
+        vlm: overrides.vlm ?? base.vlm,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/src/core/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/core/config.ts"],"names":[],"mappings":";AAAA;;GAEG;;AA8EH,gDASC;AAtBD,MAAM,cAAc,GAAsB;IACxC,SAAS,EAAE,CAAC,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IACjD,MAAM,EAAE,EAAE,eAAe,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE;IACjD,MAAM,EAAE,EAAE;IACV,aAAa,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;IAC/B,OAAO,EAAE,EAAE;IACX,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,SAAS;CACf,CAAC;AAEF;;GAEG;AACI,KAAK,UAAU,kBAAkB,CAAC,UAAkB;IACzD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;IACvC,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,uBAAuB,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,MAAM,YAAY,CAA6B,QAAQ,EAAE;QACtE,aAAa,EAAE,KAAK;KACrB,CAAC,CAAC;IACH,IAAI,CAAC,MAAM;QAAE,OAAO,cAAc,CAAC;IACnC,OAAO,WAAW,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED,SAAS,WAAW,CAClB,IAAuB,EACvB,SAAqC;IAErC,OAAO;QACL,SAAS,EAAE,SAAS,CAAC,SAAS,IAAI,IAAI,CAAC,SAAS;QAChD,MAAM,EAAE,SAAS,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM;QACvC,MAAM,EAAE,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE;QAC/C,aAAa,EAAE,EAAE,GAAG,IAAI,CAAC,aAAa,EAAE,GAAG,SAAS,CAAC,aAAa,EAAE;QACpE,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,GAAG,SAAS,CAAC,OAAO,EAAE;QAClD,IAAI,EAAE,SAAS,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI;QACjC,GAAG,EAAE,SAAS,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG;KAC/B,CAAC;AACJ,CAAC"}