@devxiyang/agent-memo 0.0.1 → 0.0.3

package/dist/plugins/resource/index.js

@@ -0,0 +1,123 @@
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { parseTtl, uriBasename, uriDirname } from '../utils.js';
+import { UrlFetcher } from './fetchers/url.js';
+export { UrlFetcher } from './fetchers/url.js';
+export { LocalFetcher } from './fetchers/local.js';
+function isExpired(meta) {
+    return !!meta.expiresAt && new Date(meta.expiresAt) < new Date();
+}
+// ─── AgentResource ───────────────────────────────────────────────────────────
+export class AgentResource {
+    memo;
+    fetchers;
+    constructor(memo, fetchers) {
+        this.memo = memo;
+        this.fetchers = fetchers ?? [new UrlFetcher()];
+    }
+    /**
+     * Fetch content from any source (URL, local path, or custom) and store at uri.
+     * The appropriate fetcher is selected via canHandle().
+     */
+    async fetch(source, uri, options = {}) {
+        const fetcher = this.fetchers.find(f => f.canHandle(source));
+        if (!fetcher)
+            throw new Error(`No fetcher found for source: "${source}"`);
+        const destPath = this.memo.toPath(uri);
+        await mkdir(dirname(destPath), { recursive: true });
+        const { contentType } = await fetcher.fetch(source, destPath, options);
+        const now = new Date();
+        await this._writeMeta(uri, {
+            source,
+            fetchedAt: now.toISOString(),
+            contentType,
+            expiresAt: options.ttl
+                ? new Date(now.getTime() + parseTtl(options.ttl)).toISOString()
+                : undefined,
+        });
+    }
+    /**
+     * Re-fetch a resource from its stored source.
+     * Throws if no metadata exists for the URI.
+     */
+    async refresh(uri, options = {}) {
+        const meta = await this.getMeta(uri);
+        if (!meta)
+            throw new Error(`No resource metadata found for "${uri}". Fetch it first.`);
+        await this.fetch(meta.source, uri, options);
+    }
+    /**
+     * Read cached text content. Returns null if not found or expired.
+     * For binary files, use toPath() to get the physical path instead.
+     */
+    async read(uri) {
+        const meta = await this.getMeta(uri);
+        if (!meta || isExpired(meta))
+            return null;
+        const content = await this.memo.read(uri);
+        if (content === null)
+            return null;
+        return { uri, content, meta };
+    }
+    /**
+     * Read cached binary content. Returns null if not found or expired.
+     * Use this for images, PDFs, audio, and other binary formats.
+     */
+    async readBinary(uri) {
+        const meta = await this.getMeta(uri);
+        if (!meta || isExpired(meta))
+            return null;
+        const content = await this.memo.readBinary(uri);
+        if (content === null)
+            return null;
+        return { uri, content, meta };
+    }
+    /**
+     * Get the physical filesystem path for direct binary file access.
+     * Useful for passing to external tools (PDF parsers, image processors, etc.).
+     */
+    toPath(uri) {
+        return this.memo.toPath(uri);
+    }
+    /**
+     * Remove the resource file and its metadata entry.
+     */
+    async delete(uri) {
+        await this.memo.delete(uri);
+        const dirUri = uriDirname(uri);
+        const name = uriBasename(uri);
+        const existing = await this.memo.readMeta(dirUri);
+        const files = existing.meta?._resource ?? {};
+        delete files[name];
+        await this.memo.writeMeta(dirUri, { meta: { ...existing.meta, _resource: files } });
+    }
+    /**
+     * Check whether a cached resource is missing or expired.
+     */
+    async isStale(uri) {
+        const meta = await this.getMeta(uri);
+        if (!meta)
+            return true;
+        return isExpired(meta);
+    }
+    /**
+     * Get metadata for a resource without reading its content.
+     */
+    async getMeta(uri) {
+        const dirUri = uriDirname(uri);
+        const name = uriBasename(uri);
+        const meta = await this.memo.readMeta(dirUri);
+        const files = meta.meta?._resource ?? {};
+        return files[name] ?? null;
+    }
+    // ── Private ────────────────────────────────────────────────────────────────
+    async _writeMeta(uri, resMeta) {
+        const dirUri = uriDirname(uri);
+        const name = uriBasename(uri);
+        const existing = await this.memo.readMeta(dirUri);
+        const files = existing.meta?._resource ?? {};
+        files[name] = resMeta;
+        await this.memo.writeMeta(dirUri, { meta: { ...existing.meta, _resource: files } });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/plugins/resource/index.js.map

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

package/dist/plugins/resource/types.d.ts

@@ -0,0 +1,39 @@
+import type { MemoUri } from '../../core/memo/types.js';
+export type FetchMeta = {
+    contentType?: string;
+};
+/**
+ * Pluggable fetcher interface. Implement this to support custom sources
+ * (S3, database, internal APIs, etc.).
+ */
+export interface ResourceFetcher {
+    /** Return true if this fetcher can handle the given source string. */
+    canHandle(source: string): boolean;
+    /** Fetch content from source and write it to destPath (physical path). */
+    fetch(source: string, destPath: string, options?: FetchOptions): Promise<FetchMeta>;
+}
+export type FetchOptions = {
+    /** Time-to-live for cached content, e.g. '1d', '7d'. Omit to cache indefinitely. */
+    ttl?: string;
+    /** Additional HTTP request headers (used by UrlFetcher). */
+    headers?: Record<string, string>;
+};
+export type ResourceMeta = {
+    source: string;
+    fetchedAt: string;
+    expiresAt?: string;
+    contentType?: string;
+};
+/** Text resource entry — returned by read(). */
+export type ResourceEntry = {
+    uri: MemoUri;
+    content: string;
+    meta: ResourceMeta;
+};
+/** Binary resource entry — returned by readBinary(). */
+export type BinaryResourceEntry = {
+    uri: MemoUri;
+    content: Uint8Array;
+    meta: ResourceMeta;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/plugins/resource/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/plugins/resource/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAIvD,MAAM,MAAM,SAAS,GAAG;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAA;IAClC,0EAA0E;IAC1E,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;CACpF;AAID,MAAM,MAAM,YAAY,GAAG;IACzB,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC,CAAA;AAID,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAQ,MAAM,CAAA;IACpB,SAAS,EAAK,MAAM,CAAA;IACpB,SAAS,CAAC,EAAI,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,CAAA;AAID,gDAAgD;AAChD,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAM,OAAO,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAK,YAAY,CAAA;CACtB,CAAA;AAED,wDAAwD;AACxD,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,EAAM,OAAO,CAAA;IAChB,OAAO,EAAE,UAAU,CAAA;IACnB,IAAI,EAAK,YAAY,CAAA;CACtB,CAAA"}

package/dist/plugins/resource/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/plugins/resource/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/plugins/resource/types.ts"],"names":[],"mappings":""}

package/dist/plugins/utils.d.ts

@@ -0,0 +1,5 @@
+import type { MemoUri } from '../core/memo/types.js';
+export declare function parseTtl(ttl: string): number;
+export declare function uriBasename(uri: MemoUri): string;
+export declare function uriDirname(uri: MemoUri): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/plugins/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/plugins/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAEpD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAS5C;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAEhD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAI/C"}

package/dist/plugins/utils.js

@@ -0,0 +1,20 @@
+export function parseTtl(ttl) {
+    const match = ttl.match(/^(\d+)([smhdwy])$/);
+    if (!match)
+        throw new Error(`Invalid TTL: "${ttl}". Expected format: 30d, 1h, 7d, etc.`);
+    const n = parseInt(match[1], 10);
+    const units = {
+        s: 1_000, m: 60_000, h: 3_600_000,
+        d: 86_400_000, w: 604_800_000, y: 31_536_000_000,
+    };
+    return n * units[match[2]];
+}
+export function uriBasename(uri) {
+    return uri.split('/').filter(Boolean).at(-1) ?? '';
+}
+export function uriDirname(uri) {
+    const parts = uri.replace('memo://', '').split('/').filter(Boolean);
+    parts.pop();
+    return parts.length ? `memo://${parts.join('/')}` : 'memo://';
+}
+//# sourceMappingURL=utils.js.map

package/dist/plugins/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/plugins/utils.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAA;IAC5C,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,iBAAiB,GAAG,uCAAuC,CAAC,CAAA;IACxF,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IAChC,MAAM,KAAK,GAA2B;QACpC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS;QACjC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,cAAc;KACjD,CAAA;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;AAC5B,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,OAAO,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;AACpD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAY;IACrC,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACnE,KAAK,CAAC,GAAG,EAAE,CAAA;IACX,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAA;AAC/D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devxiyang/agent-memo",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Agent memory and memo SDK",
   "license": "MIT",
   "repository": {
@@ -25,6 +25,14 @@
     "./memo": {
       "types": "./dist/core/memo/index.d.ts",
       "import": "./dist/core/memo/index.js"
+    },
+    "./memory": {
+      "types": "./dist/plugins/memory/index.d.ts",
+      "import": "./dist/plugins/memory/index.js"
+    },
+    "./resource": {
+      "types": "./dist/plugins/resource/index.d.ts",
+      "import": "./dist/plugins/resource/index.js"
     }
   },
   "files": [
@@ -45,6 +53,7 @@
   "dependencies": {
     "@vscode/ripgrep": ">=1.17.0",
     "chokidar": ">=5.0.0",
-    "file-type": ">=21.0.0"
+    "file-type": ">=21.0.0",
+    "gray-matter": "^4.0.3"
   }
 }

package/dist/core/memo/memo.d.ts

@@ -1 +0,0 @@
-//# sourceMappingURL=memo.d.ts.map

package/dist/core/memo/memo.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"memo.d.ts","sourceRoot":"","sources":["../../../src/core/memo/memo.ts"],"names":[],"mappings":""}

package/dist/core/memo/memo.js

@@ -1,3 +0,0 @@
-"use strict";
-// Superseded by FileMemoFS in ./file-fs.ts
-//# sourceMappingURL=memo.js.map

package/dist/core/memo/memo.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"memo.js","sourceRoot":"","sources":["../../../src/core/memo/memo.ts"],"names":[],"mappings":";AAAA,2CAA2C"}