@aumos/agent-memory 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,121 @@
+/**
+ * HTTP client for the agent-memory API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentMemoryClient } from "@aumos/agent-memory";
+ *
+ * const client = createAgentMemoryClient({ baseUrl: "http://localhost:8060" });
+ *
+ * // Store a new memory in the semantic layer
+ * const stored = await client.store({
+ *   content: "The Eiffel Tower is located in Paris, France.",
+ *   layer: "semantic",
+ *   importance_score: 0.8,
+ *   source: "document",
+ * });
+ *
+ * if (stored.ok) {
+ *   console.log("Memory stored:", stored.data.memory_id);
+ * }
+ *
+ * // Hybrid retrieval across all layers
+ * const results = await client.search({ query: "Eiffel Tower", limit: 5 });
+ * if (results.ok) {
+ *   for (const result of results.data) {
+ *     console.log(`[${result.source}] score=${result.score} — ${result.content}`);
+ *   }
+ * }
+ * ```
+ */
+import type { ApiResult, CompactResult, ForgetQuery, ForgetResult, KnowledgeGraph, MemoryEntry, RetrievalResult, SearchQuery, StoreRequest } from "./types.js";
+/** Configuration options for the AgentMemoryClient. */
+export interface AgentMemoryClientConfig {
+    /** Base URL of the agent-memory server (e.g. "http://localhost:8060"). */
+    readonly baseUrl: string;
+    /** Optional request timeout in milliseconds (default: 30000). */
+    readonly timeoutMs?: number;
+    /** Optional extra HTTP headers sent with every request. */
+    readonly headers?: Readonly<Record<string, string>>;
+}
+/** Typed HTTP client for the agent-memory server. */
+export interface AgentMemoryClient {
+    /**
+     * Persist a new memory entry in the specified layer.
+     *
+     * The server assigns a unique memory_id and computes the initial
+     * freshness score. Returns the full MemoryEntry as stored.
+     *
+     * @param request - Content, layer, importance, source, and metadata.
+     * @returns The persisted MemoryEntry with server-assigned fields.
+     */
+    store(request: StoreRequest): Promise<ApiResult<MemoryEntry>>;
+    /**
+     * Retrieve a specific memory entry by its ID.
+     *
+     * Accessing a memory updates its last_accessed timestamp and
+     * increments access_count on the server.
+     *
+     * @param memoryId - The UUID of the memory entry to retrieve.
+     * @returns The MemoryEntry if found, or a 404 error result.
+     */
+    retrieve(memoryId: string): Promise<ApiResult<MemoryEntry>>;
+    /**
+     * Perform a hybrid (vector + graph + recency) search across memory layers.
+     *
+     * Combines semantic similarity, knowledge graph traversal, and recency
+     * signals, fusing results into a single ranked list.
+     *
+     * @param query - Query string, optional layer filter, and result limit.
+     * @returns Ranked RetrievalResult array from all active retrieval backends.
+     */
+    search(query: SearchQuery): Promise<ApiResult<readonly RetrievalResult[]>>;
+    /**
+     * Remove one or more memory entries matching the given criteria.
+     *
+     * When memoryId is provided, only that specific entry is removed.
+     * When layer is provided without memoryId, all entries in that layer
+     * are removed. When belowImportance is provided, entries with an
+     * importance_score below the threshold are candidates for removal.
+     *
+     * Safety-critical entries are never removed by automated forget calls.
+     *
+     * @param query - Removal criteria: by ID, layer, or importance threshold.
+     * @returns ForgetResult with removed count and IDs.
+     */
+    forget(query: ForgetQuery): Promise<ApiResult<ForgetResult>>;
+    /**
+     * Retrieve the current knowledge graph structure.
+     *
+     * Returns all nodes and directed edges from the semantic knowledge graph,
+     * including node labels, relation types, and edge weights.
+     *
+     * @returns KnowledgeGraph snapshot with nodes, edges, and counts.
+     */
+    getKnowledgeGraph(): Promise<ApiResult<KnowledgeGraph>>;
+    /**
+     * Trigger a memory compaction pass.
+     *
+     * Compaction removes stale low-importance entries, merges near-duplicate
+     * content, and refreshes freshness scores based on access patterns.
+     * The operation runs server-side and returns a summary of changes made.
+     *
+     * @param options - Optional compaction parameters.
+     * @returns CompactResult with before/after counts and duration.
+     */
+    compact(options?: {
+        layer?: import("./types.js").MemoryLayer;
+        importanceThreshold?: number;
+    }): Promise<ApiResult<CompactResult>>;
+}
+/**
+ * Create a typed HTTP client for the agent-memory server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentMemoryClient instance.
+ */
+export declare function createAgentMemoryClient(config: AgentMemoryClientConfig): AgentMemoryClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAEV,SAAS,EACT,aAAa,EACb,WAAW,EACX,YAAY,EACZ,cAAc,EACd,WAAW,EACX,eAAe,EACf,WAAW,EACX,YAAY,EACb,MAAM,YAAY,CAAC;AAMpB,uDAAuD;AACvD,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AA0DD,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IAE9D;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC;IAE5D;;;;;;;;OAQG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,SAAS,eAAe,EAAE,CAAC,CAAC,CAAC;IAE3E;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC;IAE7D;;;;;;;OAOG;IACH,iBAAiB,IAAI,OAAO,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC,CAAC;IAExD;;;;;;;;;OASG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE;QAChB,KAAK,CAAC,EAAE,OAAO,YAAY,EAAE,WAAW,CAAC;QACzC,mBAAmB,CAAC,EAAE,MAAM,CAAC;KAC9B,GAAG,OAAO,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC;CACvC;AAMD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,uBAAuB,GAC9B,iBAAiB,CAuFnB"}

package/dist/client.js

@@ -0,0 +1,133 @@
+/**
+ * HTTP client for the agent-memory API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentMemoryClient } from "@aumos/agent-memory";
+ *
+ * const client = createAgentMemoryClient({ baseUrl: "http://localhost:8060" });
+ *
+ * // Store a new memory in the semantic layer
+ * const stored = await client.store({
+ *   content: "The Eiffel Tower is located in Paris, France.",
+ *   layer: "semantic",
+ *   importance_score: 0.8,
+ *   source: "document",
+ * });
+ *
+ * if (stored.ok) {
+ *   console.log("Memory stored:", stored.data.memory_id);
+ * }
+ *
+ * // Hybrid retrieval across all layers
+ * const results = await client.search({ query: "Eiffel Tower", limit: 5 });
+ * if (results.ok) {
+ *   for (const result of results.data) {
+ *     console.log(`[${result.source}] score=${result.score} — ${result.content}`);
+ *   }
+ * }
+ * ```
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+async function fetchJson(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url, { ...init, signal: controller.signal });
+        clearTimeout(timeoutId);
+        const body = await response.json();
+        if (!response.ok) {
+            const errorBody = body;
+            return {
+                ok: false,
+                error: {
+                    error: errorBody.error ?? "Unknown error",
+                    detail: errorBody.detail ?? "",
+                },
+                status: response.status,
+            };
+        }
+        return { ok: true, data: body };
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            error: { error: "Network error", detail: message },
+            status: 0,
+        };
+    }
+}
+function buildHeaders(extraHeaders) {
+    return {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...extraHeaders,
+    };
+}
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a typed HTTP client for the agent-memory server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentMemoryClient instance.
+ */
+export function createAgentMemoryClient(config) {
+    const { baseUrl, timeoutMs = 30_000, headers: extraHeaders } = config;
+    const baseHeaders = buildHeaders(extraHeaders);
+    return {
+        async store(request) {
+            return fetchJson(`${baseUrl}/memory`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify(request),
+            }, timeoutMs);
+        },
+        async retrieve(memoryId) {
+            return fetchJson(`${baseUrl}/memory/${encodeURIComponent(memoryId)}`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async search(query) {
+            const params = new URLSearchParams({ query: query.query });
+            if (query.layer !== undefined) {
+                params.set("layer", query.layer);
+            }
+            if (query.limit !== undefined) {
+                params.set("limit", String(query.limit));
+            }
+            return fetchJson(`${baseUrl}/memory/search?${params.toString()}`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async forget(query) {
+            return fetchJson(`${baseUrl}/memory/forget`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify({
+                    memory_id: query.memoryId,
+                    layer: query.layer,
+                    below_importance: query.belowImportance,
+                }),
+            }, timeoutMs);
+        },
+        async getKnowledgeGraph() {
+            return fetchJson(`${baseUrl}/memory/graph`, { method: "GET", headers: baseHeaders }, timeoutMs);
+        },
+        async compact(options = {}) {
+            return fetchJson(`${baseUrl}/memory/compact`, {
+                method: "POST",
+                headers: baseHeaders,
+                body: JSON.stringify({
+                    layer: options.layer,
+                    importance_threshold: options.importanceThreshold,
+                }),
+            }, timeoutMs);
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @aumos/agent-memory
+ *
+ * TypeScript client for the AumOS agent-memory framework.
+ * Provides multi-layer memory management, hybrid retrieval,
+ * knowledge graph access, and memory compaction.
+ */
+export type { AgentMemoryClient, AgentMemoryClientConfig } from "./client.js";
+export { createAgentMemoryClient } from "./client.js";
+export type { MemoryLayer, MemorySource, ImportanceLevel, MemoryEntry, KnowledgeNode, KnowledgeEdge, KnowledgeGraph, EpisodeRecord, RetrievalQuery, RetrievalResult, CompactResult, StoreRequest, SearchQuery, ForgetQuery, ForgetResult, ApiError, ApiResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAGtD,YAAY,EACV,WAAW,EACX,YAAY,EACZ,eAAe,EACf,WAAW,EACX,aAAa,EACb,aAAa,EACb,cAAc,EACd,aAAa,EACb,cAAc,EACd,eAAe,EACf,aAAa,EACb,YAAY,EACZ,WAAW,EACX,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @aumos/agent-memory
+ *
+ * TypeScript client for the AumOS agent-memory framework.
+ * Provides multi-layer memory management, hybrid retrieval,
+ * knowledge graph access, and memory compaction.
+ */
+export { createAgentMemoryClient } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,220 @@
+/**
+ * TypeScript interfaces for the agent-memory framework.
+ *
+ * Mirrors the Pydantic/dataclass models defined in:
+ *   agent_memory.memory.types          — MemoryLayer, MemoryEntry, MemorySource
+ *   agent_memory.retrieval.graph_retriever — RetrievalResult
+ *   agent_memory.memory.episodic        — EpisodicMemory
+ *
+ * All interfaces use readonly fields to match Python frozen models.
+ */
+/**
+ * The four cognitive memory layers supported by the framework.
+ * Maps to the MemoryLayer enum in agent_memory.memory.types.
+ *
+ *   - working    — short-lived, session-scoped scratchpad memory
+ *   - episodic   — time-ordered event log (what happened, when)
+ *   - semantic   — factual knowledge and learned concepts
+ *   - procedural — learned skills, workflows, and action templates
+ */
+export type MemoryLayer = "working" | "episodic" | "semantic" | "procedural";
+/**
+ * Origin of a memory entry.
+ * Maps to the MemorySource enum in agent_memory.memory.types.
+ */
+export type MemorySource = "user_input" | "tool_output" | "agent_inference" | "document" | "external_api";
+/**
+ * Qualitative importance tier for a memory entry.
+ * Maps to the ImportanceLevel enum in agent_memory.memory.types.
+ */
+export type ImportanceLevel = "critical" | "high" | "medium" | "low" | "trivial";
+/**
+ * A single memory record stored across any layer.
+ * Maps to MemoryEntry in agent_memory.memory.types.
+ */
+export interface MemoryEntry {
+    /** Unique identifier for this memory record (UUID v4). */
+    readonly memory_id: string;
+    /** The textual content of this memory. */
+    readonly content: string;
+    /** Which cognitive memory layer this entry belongs to. */
+    readonly layer: MemoryLayer;
+    /** Numeric importance score in [0, 1]. Higher is more important. */
+    readonly importance_score: number;
+    /** Numeric freshness score in [0, 1]. Decays over time. */
+    readonly freshness_score: number;
+    /** Origin of this memory entry. */
+    readonly source: MemorySource;
+    /** ISO-8601 UTC timestamp when this entry was first created. */
+    readonly created_at: string;
+    /** ISO-8601 UTC timestamp of the most recent access. */
+    readonly last_accessed: string;
+    /** Number of times this entry has been retrieved. */
+    readonly access_count: number;
+    /** When true this entry is protected from automated forgetting. */
+    readonly safety_critical: boolean;
+    /** Derived composite relevance score: importance_score * freshness_score. */
+    readonly composite_score: number;
+    /** Qualitative importance tier derived from importance_score. */
+    readonly importance_level: ImportanceLevel;
+    /** Arbitrary string key/value metadata. */
+    readonly metadata: Readonly<Record<string, string>>;
+}
+/**
+ * A single node in the knowledge graph.
+ */
+export interface KnowledgeNode {
+    /** Node label — also serves as the unique identifier within the graph. */
+    readonly label: string;
+    /** Outgoing edges from this node. */
+    readonly edges: readonly KnowledgeEdge[];
+}
+/**
+ * A directed, weighted edge in the knowledge graph.
+ */
+export interface KnowledgeEdge {
+    /** Relation type string (e.g. "capital_of", "knows", "related_to"). */
+    readonly relation: string;
+    /** Label of the target node. */
+    readonly target: string;
+    /** Edge weight in (0.0, 1.0]. Higher weight means greater relevance. */
+    readonly weight: number;
+}
+/**
+ * Snapshot of the knowledge graph structure.
+ */
+export interface KnowledgeGraph {
+    /** Total number of nodes in the graph. */
+    readonly node_count: number;
+    /** Total number of directed edges in the graph. */
+    readonly edge_count: number;
+    /** All nodes with their outgoing edges. */
+    readonly nodes: readonly KnowledgeNode[];
+}
+/**
+ * A time-bounded episode record returned from episodic memory queries.
+ * Groups temporally adjacent events into a named episode.
+ */
+export interface EpisodeRecord {
+    /** Unique identifier for this episode. */
+    readonly episode_id: string;
+    /** Human-readable title or label for this episode. */
+    readonly title: string;
+    /** ISO-8601 UTC timestamp when the episode started. */
+    readonly started_at: string;
+    /** ISO-8601 UTC timestamp when the episode ended (null if ongoing). */
+    readonly ended_at: string | null;
+    /** Memory entries that make up this episode. */
+    readonly entries: readonly MemoryEntry[];
+    /** Number of entries in this episode. */
+    readonly entry_count: number;
+    /** Arbitrary metadata attached to this episode. */
+    readonly metadata: Readonly<Record<string, string>>;
+}
+/**
+ * Query parameters for memory retrieval operations.
+ */
+export interface RetrievalQuery {
+    /** Free-text query string used to find relevant memories. */
+    readonly query: string;
+    /** Restrict retrieval to a specific memory layer (null = all layers). */
+    readonly layer?: MemoryLayer;
+    /** Maximum number of results to return (default 10). */
+    readonly top_k?: number;
+    /** Minimum composite score threshold for inclusion (0.0–1.0). */
+    readonly min_score?: number;
+}
+/**
+ * A single result from a retrieval or search operation.
+ * Maps to RetrievalResult in agent_memory.retrieval.graph_retriever.
+ */
+export interface RetrievalResult {
+    /** The retrieved text content or node label. */
+    readonly content: string;
+    /** Which backend produced this result: "vector", "graph", or "recency". */
+    readonly source: "vector" | "graph" | "recency";
+    /** Relevance score in [0.0, 1.0]. */
+    readonly score: number;
+    /** Arbitrary metadata from the retrieval backend. */
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+/**
+ * Result returned after a memory compaction operation.
+ */
+export interface CompactResult {
+    /** Total number of entries before compaction. */
+    readonly entries_before: number;
+    /** Total number of entries after compaction. */
+    readonly entries_after: number;
+    /** Number of entries that were removed. */
+    readonly entries_removed: number;
+    /** Number of entries that were merged or consolidated. */
+    readonly entries_merged: number;
+    /** Wall-clock milliseconds the compaction took. */
+    readonly duration_ms: number;
+    /** ISO-8601 UTC timestamp when compaction completed. */
+    readonly completed_at: string;
+}
+/**
+ * Request body for the store operation.
+ */
+export interface StoreRequest {
+    /** The textual content to store. */
+    readonly content: string;
+    /** Memory layer to store this entry in. */
+    readonly layer: MemoryLayer;
+    /** Importance score [0, 1] (default 0.5). */
+    readonly importance_score?: number;
+    /** Origin of this memory (default "agent_inference"). */
+    readonly source?: MemorySource;
+    /** Whether this entry is safety-critical (default false). */
+    readonly safety_critical?: boolean;
+    /** Arbitrary key/value metadata. */
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+/**
+ * Query parameters for the search endpoint.
+ */
+export interface SearchQuery {
+    /** Free-text search string. */
+    readonly query: string;
+    /** Restrict to a specific layer (omit for all layers). */
+    readonly layer?: MemoryLayer;
+    /** Maximum number of results (default 10). */
+    readonly limit?: number;
+}
+/**
+ * Query parameters for the forget endpoint.
+ */
+export interface ForgetQuery {
+    /** Specific memory ID to remove (takes precedence over other filters). */
+    readonly memoryId?: string;
+    /** Remove all entries in this layer. */
+    readonly layer?: MemoryLayer;
+    /** Remove entries below this importance score threshold. */
+    readonly belowImportance?: number;
+}
+/**
+ * Response from the forget operation.
+ */
+export interface ForgetResult {
+    /** Number of entries removed. */
+    readonly removed_count: number;
+    /** IDs of the removed entries. */
+    readonly removed_ids: readonly string[];
+}
+/** Standard error payload returned by the agent-memory API. */
+export interface ApiError {
+    readonly error: string;
+    readonly detail: string;
+}
+/** Result type for all client operations. */
+export type ApiResult<T> = {
+    readonly ok: true;
+    readonly data: T;
+} | {
+    readonly ok: false;
+    readonly error: ApiError;
+    readonly status: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * TypeScript interfaces for the agent-memory framework.
+ *
+ * Mirrors the Pydantic/dataclass models defined in:
+ *   agent_memory.memory.types          — MemoryLayer, MemoryEntry, MemorySource
+ *   agent_memory.retrieval.graph_retriever — RetrievalResult
+ *   agent_memory.memory.episodic        — EpisodicMemory
+ *
+ * All interfaces use readonly fields to match Python frozen models.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@aumos/agent-memory",
+  "version": "0.1.0",
+  "description": "TypeScript client for the AumOS agent-memory framework — multi-layer memory management, knowledge graphs, and hybrid retrieval",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "aumos",
+    "agent-memory",
+    "memory",
+    "knowledge-graph",
+    "retrieval",
+    "episodic-memory",
+    "semantic-memory",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aumos-ai/agent-memory"
+  }
+}

package/src/client.ts

@@ -0,0 +1,294 @@
+/**
+ * HTTP client for the agent-memory API.
+ *
+ * Uses the Fetch API (available natively in Node 18+, browsers, and Deno).
+ * No external dependencies required.
+ *
+ * @example
+ * ```ts
+ * import { createAgentMemoryClient } from "@aumos/agent-memory";
+ *
+ * const client = createAgentMemoryClient({ baseUrl: "http://localhost:8060" });
+ *
+ * // Store a new memory in the semantic layer
+ * const stored = await client.store({
+ *   content: "The Eiffel Tower is located in Paris, France.",
+ *   layer: "semantic",
+ *   importance_score: 0.8,
+ *   source: "document",
+ * });
+ *
+ * if (stored.ok) {
+ *   console.log("Memory stored:", stored.data.memory_id);
+ * }
+ *
+ * // Hybrid retrieval across all layers
+ * const results = await client.search({ query: "Eiffel Tower", limit: 5 });
+ * if (results.ok) {
+ *   for (const result of results.data) {
+ *     console.log(`[${result.source}] score=${result.score} — ${result.content}`);
+ *   }
+ * }
+ * ```
+ */
+
+import type {
+  ApiError,
+  ApiResult,
+  CompactResult,
+  ForgetQuery,
+  ForgetResult,
+  KnowledgeGraph,
+  MemoryEntry,
+  RetrievalResult,
+  SearchQuery,
+  StoreRequest,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Client configuration
+// ---------------------------------------------------------------------------
+
+/** Configuration options for the AgentMemoryClient. */
+export interface AgentMemoryClientConfig {
+  /** Base URL of the agent-memory server (e.g. "http://localhost:8060"). */
+  readonly baseUrl: string;
+  /** Optional request timeout in milliseconds (default: 30000). */
+  readonly timeoutMs?: number;
+  /** Optional extra HTTP headers sent with every request. */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+async function fetchJson<T>(
+  url: string,
+  init: RequestInit,
+  timeoutMs: number,
+): Promise<ApiResult<T>> {
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, { ...init, signal: controller.signal });
+    clearTimeout(timeoutId);
+
+    const body = await response.json() as unknown;
+
+    if (!response.ok) {
+      const errorBody = body as Partial<ApiError>;
+      return {
+        ok: false,
+        error: {
+          error: errorBody.error ?? "Unknown error",
+          detail: errorBody.detail ?? "",
+        },
+        status: response.status,
+      };
+    }
+
+    return { ok: true, data: body as T };
+  } catch (err: unknown) {
+    clearTimeout(timeoutId);
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      error: { error: "Network error", detail: message },
+      status: 0,
+    };
+  }
+}
+
+function buildHeaders(
+  extraHeaders: Readonly<Record<string, string>> | undefined,
+): Record<string, string> {
+  return {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+    ...extraHeaders,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Client interface
+// ---------------------------------------------------------------------------
+
+/** Typed HTTP client for the agent-memory server. */
+export interface AgentMemoryClient {
+  /**
+   * Persist a new memory entry in the specified layer.
+   *
+   * The server assigns a unique memory_id and computes the initial
+   * freshness score. Returns the full MemoryEntry as stored.
+   *
+   * @param request - Content, layer, importance, source, and metadata.
+   * @returns The persisted MemoryEntry with server-assigned fields.
+   */
+  store(request: StoreRequest): Promise<ApiResult<MemoryEntry>>;
+
+  /**
+   * Retrieve a specific memory entry by its ID.
+   *
+   * Accessing a memory updates its last_accessed timestamp and
+   * increments access_count on the server.
+   *
+   * @param memoryId - The UUID of the memory entry to retrieve.
+   * @returns The MemoryEntry if found, or a 404 error result.
+   */
+  retrieve(memoryId: string): Promise<ApiResult<MemoryEntry>>;
+
+  /**
+   * Perform a hybrid (vector + graph + recency) search across memory layers.
+   *
+   * Combines semantic similarity, knowledge graph traversal, and recency
+   * signals, fusing results into a single ranked list.
+   *
+   * @param query - Query string, optional layer filter, and result limit.
+   * @returns Ranked RetrievalResult array from all active retrieval backends.
+   */
+  search(query: SearchQuery): Promise<ApiResult<readonly RetrievalResult[]>>;
+
+  /**
+   * Remove one or more memory entries matching the given criteria.
+   *
+   * When memoryId is provided, only that specific entry is removed.
+   * When layer is provided without memoryId, all entries in that layer
+   * are removed. When belowImportance is provided, entries with an
+   * importance_score below the threshold are candidates for removal.
+   *
+   * Safety-critical entries are never removed by automated forget calls.
+   *
+   * @param query - Removal criteria: by ID, layer, or importance threshold.
+   * @returns ForgetResult with removed count and IDs.
+   */
+  forget(query: ForgetQuery): Promise<ApiResult<ForgetResult>>;
+
+  /**
+   * Retrieve the current knowledge graph structure.
+   *
+   * Returns all nodes and directed edges from the semantic knowledge graph,
+   * including node labels, relation types, and edge weights.
+   *
+   * @returns KnowledgeGraph snapshot with nodes, edges, and counts.
+   */
+  getKnowledgeGraph(): Promise<ApiResult<KnowledgeGraph>>;
+
+  /**
+   * Trigger a memory compaction pass.
+   *
+   * Compaction removes stale low-importance entries, merges near-duplicate
+   * content, and refreshes freshness scores based on access patterns.
+   * The operation runs server-side and returns a summary of changes made.
+   *
+   * @param options - Optional compaction parameters.
+   * @returns CompactResult with before/after counts and duration.
+   */
+  compact(options?: {
+    layer?: import("./types.js").MemoryLayer;
+    importanceThreshold?: number;
+  }): Promise<ApiResult<CompactResult>>;
+}
+
+// ---------------------------------------------------------------------------
+// Client factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a typed HTTP client for the agent-memory server.
+ *
+ * @param config - Client configuration including base URL.
+ * @returns An AgentMemoryClient instance.
+ */
+export function createAgentMemoryClient(
+  config: AgentMemoryClientConfig,
+): AgentMemoryClient {
+  const { baseUrl, timeoutMs = 30_000, headers: extraHeaders } = config;
+  const baseHeaders = buildHeaders(extraHeaders);
+
+  return {
+    async store(request: StoreRequest): Promise<ApiResult<MemoryEntry>> {
+      return fetchJson<MemoryEntry>(
+        `${baseUrl}/memory`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify(request),
+        },
+        timeoutMs,
+      );
+    },
+
+    async retrieve(memoryId: string): Promise<ApiResult<MemoryEntry>> {
+      return fetchJson<MemoryEntry>(
+        `${baseUrl}/memory/${encodeURIComponent(memoryId)}`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async search(
+      query: SearchQuery,
+    ): Promise<ApiResult<readonly RetrievalResult[]>> {
+      const params = new URLSearchParams({ query: query.query });
+      if (query.layer !== undefined) {
+        params.set("layer", query.layer);
+      }
+      if (query.limit !== undefined) {
+        params.set("limit", String(query.limit));
+      }
+
+      return fetchJson<readonly RetrievalResult[]>(
+        `${baseUrl}/memory/search?${params.toString()}`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async forget(query: ForgetQuery): Promise<ApiResult<ForgetResult>> {
+      return fetchJson<ForgetResult>(
+        `${baseUrl}/memory/forget`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify({
+            memory_id: query.memoryId,
+            layer: query.layer,
+            below_importance: query.belowImportance,
+          }),
+        },
+        timeoutMs,
+      );
+    },
+
+    async getKnowledgeGraph(): Promise<ApiResult<KnowledgeGraph>> {
+      return fetchJson<KnowledgeGraph>(
+        `${baseUrl}/memory/graph`,
+        { method: "GET", headers: baseHeaders },
+        timeoutMs,
+      );
+    },
+
+    async compact(
+      options: {
+        layer?: import("./types.js").MemoryLayer;
+        importanceThreshold?: number;
+      } = {},
+    ): Promise<ApiResult<CompactResult>> {
+      return fetchJson<CompactResult>(
+        `${baseUrl}/memory/compact`,
+        {
+          method: "POST",
+          headers: baseHeaders,
+          body: JSON.stringify({
+            layer: options.layer,
+            importance_threshold: options.importanceThreshold,
+          }),
+        },
+        timeoutMs,
+      );
+    },
+  };
+}
+

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @aumos/agent-memory
+ *
+ * TypeScript client for the AumOS agent-memory framework.
+ * Provides multi-layer memory management, hybrid retrieval,
+ * knowledge graph access, and memory compaction.
+ */
+
+// Client and configuration
+export type { AgentMemoryClient, AgentMemoryClientConfig } from "./client.js";
+export { createAgentMemoryClient } from "./client.js";
+
+// Core memory types
+export type {
+  MemoryLayer,
+  MemorySource,
+  ImportanceLevel,
+  MemoryEntry,
+  KnowledgeNode,
+  KnowledgeEdge,
+  KnowledgeGraph,
+  EpisodeRecord,
+  RetrievalQuery,
+  RetrievalResult,
+  CompactResult,
+  StoreRequest,
+  SearchQuery,
+  ForgetQuery,
+  ForgetResult,
+  ApiError,
+  ApiResult,
+} from "./types.js";

package/src/types.ts

@@ -0,0 +1,268 @@
+/**
+ * TypeScript interfaces for the agent-memory framework.
+ *
+ * Mirrors the Pydantic/dataclass models defined in:
+ *   agent_memory.memory.types          — MemoryLayer, MemoryEntry, MemorySource
+ *   agent_memory.retrieval.graph_retriever — RetrievalResult
+ *   agent_memory.memory.episodic        — EpisodicMemory
+ *
+ * All interfaces use readonly fields to match Python frozen models.
+ */
+
+// ---------------------------------------------------------------------------
+// Memory layer enumerations
+// ---------------------------------------------------------------------------
+
+/**
+ * The four cognitive memory layers supported by the framework.
+ * Maps to the MemoryLayer enum in agent_memory.memory.types.
+ *
+ *   - working    — short-lived, session-scoped scratchpad memory
+ *   - episodic   — time-ordered event log (what happened, when)
+ *   - semantic   — factual knowledge and learned concepts
+ *   - procedural — learned skills, workflows, and action templates
+ */
+export type MemoryLayer = "working" | "episodic" | "semantic" | "procedural";
+
+/**
+ * Origin of a memory entry.
+ * Maps to the MemorySource enum in agent_memory.memory.types.
+ */
+export type MemorySource =
+  | "user_input"
+  | "tool_output"
+  | "agent_inference"
+  | "document"
+  | "external_api";
+
+/**
+ * Qualitative importance tier for a memory entry.
+ * Maps to the ImportanceLevel enum in agent_memory.memory.types.
+ */
+export type ImportanceLevel = "critical" | "high" | "medium" | "low" | "trivial";
+
+// ---------------------------------------------------------------------------
+// Core memory entry
+// ---------------------------------------------------------------------------
+
+/**
+ * A single memory record stored across any layer.
+ * Maps to MemoryEntry in agent_memory.memory.types.
+ */
+export interface MemoryEntry {
+  /** Unique identifier for this memory record (UUID v4). */
+  readonly memory_id: string;
+  /** The textual content of this memory. */
+  readonly content: string;
+  /** Which cognitive memory layer this entry belongs to. */
+  readonly layer: MemoryLayer;
+  /** Numeric importance score in [0, 1]. Higher is more important. */
+  readonly importance_score: number;
+  /** Numeric freshness score in [0, 1]. Decays over time. */
+  readonly freshness_score: number;
+  /** Origin of this memory entry. */
+  readonly source: MemorySource;
+  /** ISO-8601 UTC timestamp when this entry was first created. */
+  readonly created_at: string;
+  /** ISO-8601 UTC timestamp of the most recent access. */
+  readonly last_accessed: string;
+  /** Number of times this entry has been retrieved. */
+  readonly access_count: number;
+  /** When true this entry is protected from automated forgetting. */
+  readonly safety_critical: boolean;
+  /** Derived composite relevance score: importance_score * freshness_score. */
+  readonly composite_score: number;
+  /** Qualitative importance tier derived from importance_score. */
+  readonly importance_level: ImportanceLevel;
+  /** Arbitrary string key/value metadata. */
+  readonly metadata: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Knowledge graph types
+// ---------------------------------------------------------------------------
+
+/**
+ * A single node in the knowledge graph.
+ */
+export interface KnowledgeNode {
+  /** Node label — also serves as the unique identifier within the graph. */
+  readonly label: string;
+  /** Outgoing edges from this node. */
+  readonly edges: readonly KnowledgeEdge[];
+}
+
+/**
+ * A directed, weighted edge in the knowledge graph.
+ */
+export interface KnowledgeEdge {
+  /** Relation type string (e.g. "capital_of", "knows", "related_to"). */
+  readonly relation: string;
+  /** Label of the target node. */
+  readonly target: string;
+  /** Edge weight in (0.0, 1.0]. Higher weight means greater relevance. */
+  readonly weight: number;
+}
+
+/**
+ * Snapshot of the knowledge graph structure.
+ */
+export interface KnowledgeGraph {
+  /** Total number of nodes in the graph. */
+  readonly node_count: number;
+  /** Total number of directed edges in the graph. */
+  readonly edge_count: number;
+  /** All nodes with their outgoing edges. */
+  readonly nodes: readonly KnowledgeNode[];
+}
+
+// ---------------------------------------------------------------------------
+// Episode record
+// ---------------------------------------------------------------------------
+
+/**
+ * A time-bounded episode record returned from episodic memory queries.
+ * Groups temporally adjacent events into a named episode.
+ */
+export interface EpisodeRecord {
+  /** Unique identifier for this episode. */
+  readonly episode_id: string;
+  /** Human-readable title or label for this episode. */
+  readonly title: string;
+  /** ISO-8601 UTC timestamp when the episode started. */
+  readonly started_at: string;
+  /** ISO-8601 UTC timestamp when the episode ended (null if ongoing). */
+  readonly ended_at: string | null;
+  /** Memory entries that make up this episode. */
+  readonly entries: readonly MemoryEntry[];
+  /** Number of entries in this episode. */
+  readonly entry_count: number;
+  /** Arbitrary metadata attached to this episode. */
+  readonly metadata: Readonly<Record<string, string>>;
+}
+
+// ---------------------------------------------------------------------------
+// Retrieval types
+// ---------------------------------------------------------------------------
+
+/**
+ * Query parameters for memory retrieval operations.
+ */
+export interface RetrievalQuery {
+  /** Free-text query string used to find relevant memories. */
+  readonly query: string;
+  /** Restrict retrieval to a specific memory layer (null = all layers). */
+  readonly layer?: MemoryLayer;
+  /** Maximum number of results to return (default 10). */
+  readonly top_k?: number;
+  /** Minimum composite score threshold for inclusion (0.0–1.0). */
+  readonly min_score?: number;
+}
+
+/**
+ * A single result from a retrieval or search operation.
+ * Maps to RetrievalResult in agent_memory.retrieval.graph_retriever.
+ */
+export interface RetrievalResult {
+  /** The retrieved text content or node label. */
+  readonly content: string;
+  /** Which backend produced this result: "vector", "graph", or "recency". */
+  readonly source: "vector" | "graph" | "recency";
+  /** Relevance score in [0.0, 1.0]. */
+  readonly score: number;
+  /** Arbitrary metadata from the retrieval backend. */
+  readonly metadata: Readonly<Record<string, unknown>>;
+}
+
+// ---------------------------------------------------------------------------
+// Compact operation result
+// ---------------------------------------------------------------------------
+
+/**
+ * Result returned after a memory compaction operation.
+ */
+export interface CompactResult {
+  /** Total number of entries before compaction. */
+  readonly entries_before: number;
+  /** Total number of entries after compaction. */
+  readonly entries_after: number;
+  /** Number of entries that were removed. */
+  readonly entries_removed: number;
+  /** Number of entries that were merged or consolidated. */
+  readonly entries_merged: number;
+  /** Wall-clock milliseconds the compaction took. */
+  readonly duration_ms: number;
+  /** ISO-8601 UTC timestamp when compaction completed. */
+  readonly completed_at: string;
+}
+
+// ---------------------------------------------------------------------------
+// Request/response payload types
+// ---------------------------------------------------------------------------
+
+/**
+ * Request body for the store operation.
+ */
+export interface StoreRequest {
+  /** The textual content to store. */
+  readonly content: string;
+  /** Memory layer to store this entry in. */
+  readonly layer: MemoryLayer;
+  /** Importance score [0, 1] (default 0.5). */
+  readonly importance_score?: number;
+  /** Origin of this memory (default "agent_inference"). */
+  readonly source?: MemorySource;
+  /** Whether this entry is safety-critical (default false). */
+  readonly safety_critical?: boolean;
+  /** Arbitrary key/value metadata. */
+  readonly metadata?: Readonly<Record<string, string>>;
+}
+
+/**
+ * Query parameters for the search endpoint.
+ */
+export interface SearchQuery {
+  /** Free-text search string. */
+  readonly query: string;
+  /** Restrict to a specific layer (omit for all layers). */
+  readonly layer?: MemoryLayer;
+  /** Maximum number of results (default 10). */
+  readonly limit?: number;
+}
+
+/**
+ * Query parameters for the forget endpoint.
+ */
+export interface ForgetQuery {
+  /** Specific memory ID to remove (takes precedence over other filters). */
+  readonly memoryId?: string;
+  /** Remove all entries in this layer. */
+  readonly layer?: MemoryLayer;
+  /** Remove entries below this importance score threshold. */
+  readonly belowImportance?: number;
+}
+
+/**
+ * Response from the forget operation.
+ */
+export interface ForgetResult {
+  /** Number of entries removed. */
+  readonly removed_count: number;
+  /** IDs of the removed entries. */
+  readonly removed_ids: readonly string[];
+}
+
+// ---------------------------------------------------------------------------
+// API result wrapper (shared pattern)
+// ---------------------------------------------------------------------------
+
+/** Standard error payload returned by the agent-memory API. */
+export interface ApiError {
+  readonly error: string;
+  readonly detail: string;
+}
+
+/** Result type for all client operations. */
+export type ApiResult<T> =
+  | { readonly ok: true; readonly data: T }
+  | { readonly ok: false; readonly error: ApiError; readonly status: number };

package/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "strict": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "exactOptionalPropertyTypes": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}