@pyxmate/memory 0.0.1-beta

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pyxmate
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,54 @@
+# @pyxmate/memory
+
+SDK for **pyx-memory** — Memory as a Service for AI agents.
+
+Provides an HTTP client, shared types, and optional dashboard + React hooks for interacting with a pyx-memory server.
+
+## Install
+
+```bash
+npm install @pyxmate/memory
+```
+
+## Usage
+
+```ts
+import { MemoryClient } from '@pyxmate/memory';
+import type { MemoryEntry } from '@pyxmate/memory';
+
+const client = new MemoryClient('http://localhost:7822');
+await client.initialize();
+
+// Store a memory
+await client.store({
+  content: 'The project deadline is March 15th',
+  agentId: 'my-agent',
+});
+
+// Search memories
+const results = await client.search({ query: 'deadline', limit: 5 });
+```
+
+## Entry Points
+
+| Import | Description |
+|--------|-------------|
+| `@pyxmate/memory` | Core SDK — `MemoryClient`, shared types, constants |
+| `@pyxmate/memory/dashboard` | Headless dashboard utilities — `DashboardClient`, aggregations, graph transforms (no React) |
+| `@pyxmate/memory/react` | React hooks — `useMemoryStats`, `useMemoryHealth`, `useKnowledgeGraph`, etc. (requires React >= 18) |
+
+## Running the Server
+
+```bash
+docker pull ghcr.io/fysoul17/pyx-memory:latest
+docker run -p 7822:7822 ghcr.io/fysoul17/pyx-memory:latest
+```
+
+## Requirements
+
+- ESM only (`"type": "module"`)
+- React >= 18 (optional, only for `@pyxmate/memory/react`)
+
+## License
+
+MIT

package/dist/chunk-EDIYGMT2.mjs

@@ -0,0 +1,385 @@
+import {
+  MemoryClient
+} from "./chunk-Q4QIILKH.mjs";
+
+// ../dashboard/src/aggregations/consolidation-analytics.ts
+function analyzeConsolidationLog(entries) {
+  const totalRuns = entries.length;
+  if (totalRuns === 0) {
+    return {
+      entries,
+      totalRuns: 0,
+      avgDurationMs: 0,
+      avgEntriesProcessed: 0,
+      avgEntriesMerged: 0,
+      avgEntriesArchived: 0,
+      lastRunAt: null,
+      consolidationTrend: "insufficient_data"
+    };
+  }
+  const avgDurationMs = Math.round(entries.reduce((sum, e) => sum + e.durationMs, 0) / totalRuns);
+  const avgEntriesProcessed = Math.round(entries.reduce((sum, e) => sum + e.entriesProcessed, 0) / totalRuns * 100) / 100;
+  const avgEntriesMerged = Math.round(entries.reduce((sum, e) => sum + e.entriesMerged, 0) / totalRuns * 100) / 100;
+  const avgEntriesArchived = Math.round(entries.reduce((sum, e) => sum + e.entriesArchived, 0) / totalRuns * 100) / 100;
+  const lastRunAt = entries[0]?.runAt ?? null;
+  const consolidationTrend = computeTrend(entries);
+  return {
+    entries,
+    totalRuns,
+    avgDurationMs,
+    avgEntriesProcessed,
+    avgEntriesMerged,
+    avgEntriesArchived,
+    lastRunAt,
+    consolidationTrend
+  };
+}
+function computeTrend(entries) {
+  if (entries.length < 3) return "insufficient_data";
+  const mid = Math.floor(entries.length / 2);
+  const recentHalf = entries.slice(0, mid);
+  const olderHalf = entries.slice(mid);
+  const recentAvg = recentHalf.reduce((sum, e) => sum + e.entriesMerged, 0) / recentHalf.length;
+  const olderAvg = olderHalf.reduce((sum, e) => sum + e.entriesMerged, 0) / olderHalf.length;
+  const diff = recentAvg - olderAvg;
+  const threshold = Math.max(olderAvg * 0.2, 1);
+  if (diff > threshold) return "increasing";
+  if (diff < -threshold) return "decreasing";
+  return "stable";
+}
+
+// ../dashboard/src/aggregations/health-enrichment.ts
+function formatUptime(seconds) {
+  const days = Math.floor(seconds / 86400);
+  const hours = Math.floor(seconds % 86400 / 3600);
+  const minutes = Math.floor(seconds % 3600 / 60);
+  const parts = [];
+  if (days > 0) parts.push(`${days}d`);
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0 || parts.length === 0) parts.push(`${minutes}m`);
+  return parts.join(" ");
+}
+function formatBytes(bytes) {
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(1024));
+  const value = bytes / 1024 ** i;
+  return `${Math.round(value * 100) / 100} ${units[i]}`;
+}
+function enrichHealth(raw) {
+  const storageMB = raw.stats ? Math.round(raw.stats.storageUsedBytes / (1024 * 1024) * 100) / 100 : 0;
+  return {
+    status: raw.status === "ok" ? "ok" : "degraded",
+    uptime: raw.uptime,
+    uptimeFormatted: formatUptime(raw.uptime),
+    storageMB,
+    isHealthy: raw.status === "ok",
+    embeddingProvider: raw.embeddingProvider,
+    stats: raw.stats
+  };
+}
+function unreachableHealth(_error) {
+  return {
+    status: "unreachable",
+    uptime: 0,
+    uptimeFormatted: "0m",
+    storageMB: 0,
+    isHealthy: false,
+    embeddingProvider: "unknown",
+    stats: void 0
+  };
+}
+
+// ../dashboard/src/aggregations/metrics.ts
+var STALE_DAYS = 30;
+function computeMetrics(stats, entries) {
+  const storageMB = Math.round(stats.storageUsedBytes / (1024 * 1024) * 100) / 100;
+  let importanceSum = 0;
+  let importanceCount = 0;
+  let staleCandidates = 0;
+  const staleThreshold = /* @__PURE__ */ new Date();
+  staleThreshold.setDate(staleThreshold.getDate() - STALE_DAYS);
+  const staleThresholdStr = staleThreshold.toISOString();
+  for (const entry of entries) {
+    if (entry.importance != null) {
+      importanceSum += entry.importance;
+      importanceCount++;
+    }
+    const lastAccess = entry.lastAccessed ?? entry.createdAt;
+    if (lastAccess < staleThresholdStr && (entry.importance ?? 0.5) < 0.3) {
+      staleCandidates++;
+    }
+  }
+  const avgImportance = importanceCount > 0 ? Math.round(importanceSum / importanceCount * 1e3) / 1e3 : 0;
+  return {
+    totalEntries: stats.totalEntries,
+    vectorCount: stats.vectorCount,
+    storageUsedBytes: stats.storageUsedBytes,
+    storageMB,
+    avgImportance,
+    staleCandidates,
+    graphNodeCount: stats.graphNodeCount ?? 0,
+    graphEdgeCount: stats.graphEdgeCount ?? 0
+  };
+}
+
+// ../dashboard/src/aggregations/type-distribution.ts
+function computeTypeDistribution(entries) {
+  const counts = {};
+  for (const entry of entries) {
+    counts[entry.type] = (counts[entry.type] ?? 0) + 1;
+  }
+  const total = entries.length;
+  const percentages = {};
+  for (const [type, count] of Object.entries(counts)) {
+    percentages[type] = total > 0 ? Math.round(count / total * 1e4) / 100 : 0;
+  }
+  let dominant = "";
+  let maxCount = 0;
+  for (const [type, count] of Object.entries(counts)) {
+    if (count > maxCount) {
+      maxCount = count;
+      dominant = type;
+    }
+  }
+  return { counts, percentages, total, dominant };
+}
+
+// ../dashboard/src/client/dashboard-client.ts
+var DashboardClient = class extends MemoryClient {
+  async consolidationLog(limit = 10) {
+    return this.fetchApi(`/api/memory/consolidation-log?limit=${limit}`);
+  }
+  async listEntriesPaginated(filters = {}) {
+    const params = new URLSearchParams();
+    if (filters.page) params.set("page", String(filters.page));
+    if (filters.limit) params.set("limit", String(filters.limit));
+    if (filters.type) params.set("type", filters.type);
+    if (filters.agentId) params.set("agentId", filters.agentId);
+    if (filters.query) params.set("query", filters.query);
+    const qs = params.toString();
+    const raw = await this.fetchApi(`/api/memory/entries${qs ? `?${qs}` : ""}`);
+    return {
+      ...raw,
+      totalPages: Math.ceil(raw.totalCount / raw.limit),
+      hasNextPage: raw.page * raw.limit < raw.totalCount,
+      hasPreviousPage: raw.page > 1
+    };
+  }
+  async graphRelationships(limit = 200) {
+    return this.fetchApi(
+      `/api/memory/graph/relationships?limit=${limit}`
+    );
+  }
+  async graphFull(limit = 50) {
+    const [nodesResponse, relsResponse] = await Promise.all([
+      this.fetchApi(
+        `/api/memory/graph/nodes?limit=${limit}`
+      ),
+      this.graphRelationships(limit * 4).catch(() => ({
+        relationships: [],
+        totalCount: 0
+      }))
+    ]);
+    return {
+      nodes: nodesResponse.nodes,
+      relationships: relsResponse.relationships
+    };
+  }
+  async fetchHealthRaw() {
+    return this.fetchApi("/health");
+  }
+};
+
+// ../dashboard/src/graph/transform.ts
+function transformGraphData(nodes, relationships, opts = {}) {
+  const { minWeight = 0, maxNodes } = opts;
+  const degreeMap = /* @__PURE__ */ new Map();
+  for (const rel of relationships) {
+    degreeMap.set(rel.sourceId, (degreeMap.get(rel.sourceId) ?? 0) + 1);
+    degreeMap.set(rel.targetId, (degreeMap.get(rel.targetId) ?? 0) + 1);
+  }
+  let vizNodes = nodes.map((node) => ({
+    id: node.id,
+    label: node.name,
+    type: node.type,
+    memoryCount: node.memoryEntryIds.length,
+    degree: degreeMap.get(node.id) ?? 0,
+    properties: node.properties
+  }));
+  if (maxNodes && vizNodes.length > maxNodes) {
+    vizNodes.sort((a, b) => b.degree - a.degree);
+    vizNodes = vizNodes.slice(0, maxNodes);
+  }
+  const nodeIdSet = new Set(vizNodes.map((n) => n.id));
+  const filteredRels = relationships.filter(
+    (rel) => nodeIdSet.has(rel.sourceId) && nodeIdSet.has(rel.targetId) && (rel.properties?.weight ?? 1) >= minWeight
+  );
+  const vizEdges = filteredRels.map((rel) => ({
+    id: rel.id,
+    source: rel.sourceId,
+    target: rel.targetId,
+    label: rel.type,
+    weight: rel.properties?.weight ?? 1
+  }));
+  const nodeTypes = {};
+  for (const node of vizNodes) {
+    nodeTypes[node.type] = (nodeTypes[node.type] ?? 0) + 1;
+  }
+  const edgeTypes = {};
+  for (const edge of vizEdges) {
+    edgeTypes[edge.label] = (edgeTypes[edge.label] ?? 0) + 1;
+  }
+  return {
+    nodes: vizNodes,
+    edges: vizEdges,
+    nodeCount: vizNodes.length,
+    edgeCount: vizEdges.length,
+    nodeTypes,
+    edgeTypes
+  };
+}
+
+// ../dashboard/src/graph/types.ts
+function toGraphologyFormat(data) {
+  const nodes = data.nodes.map((node) => ({
+    key: node.id,
+    attributes: {
+      label: node.label,
+      type: node.type,
+      memoryCount: node.memoryCount,
+      degree: node.degree,
+      ...node.properties
+    }
+  }));
+  const edges = data.edges.map((edge) => ({
+    key: edge.id,
+    source: edge.source,
+    target: edge.target,
+    attributes: {
+      label: edge.label,
+      weight: edge.weight
+    }
+  }));
+  return { nodes, edges };
+}
+function toD3ForceFormat(data) {
+  const nodes = data.nodes.map((node) => ({
+    id: node.id,
+    label: node.label,
+    type: node.type,
+    memoryCount: node.memoryCount,
+    degree: node.degree
+  }));
+  const links = data.edges.map((edge) => ({
+    source: edge.source,
+    target: edge.target,
+    label: edge.label,
+    weight: edge.weight
+  }));
+  return { nodes, links };
+}
+
+// ../dashboard/src/polling/poller.ts
+var Poller = class {
+  fetcher;
+  options;
+  timer = null;
+  state = {
+    data: null,
+    error: null,
+    isLoading: false,
+    lastUpdated: null
+  };
+  updateListeners = [];
+  errorListeners = [];
+  constructor(fetcher, options) {
+    this.fetcher = fetcher;
+    this.options = {
+      intervalMs: options.intervalMs,
+      immediate: options.immediate ?? true
+    };
+  }
+  on(event, listener) {
+    if (event === "update") {
+      this.updateListeners.push(listener);
+    } else if (event === "error") {
+      this.errorListeners.push(listener);
+    }
+    return this;
+  }
+  off(event, listener) {
+    if (event === "update") {
+      this.updateListeners = this.updateListeners.filter((l) => l !== listener);
+    } else if (event === "error") {
+      this.errorListeners = this.errorListeners.filter((l) => l !== listener);
+    }
+    return this;
+  }
+  async start() {
+    if (this.timer) return;
+    if (this.options.immediate) {
+      await this.poll();
+    }
+    this.timer = setInterval(() => {
+      void this.poll();
+    }, this.options.intervalMs);
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  getState() {
+    return { ...this.state };
+  }
+  isRunning() {
+    return this.timer !== null;
+  }
+  async poll() {
+    this.state = { ...this.state, isLoading: true };
+    this.emit("update", this.state);
+    try {
+      const data = await this.fetcher();
+      this.state = {
+        data,
+        error: null,
+        isLoading: false,
+        lastUpdated: /* @__PURE__ */ new Date()
+      };
+      this.emit("update", this.state);
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.state = { ...this.state, error, isLoading: false };
+      this.emit("update", this.state);
+      this.emit("error", error);
+    }
+  }
+  emit(event, payload) {
+    if (event === "update") {
+      for (const listener of this.updateListeners) {
+        listener(payload);
+      }
+    } else if (event === "error") {
+      for (const listener of this.errorListeners) {
+        listener(payload);
+      }
+    }
+  }
+};
+
+export {
+  analyzeConsolidationLog,
+  formatUptime,
+  formatBytes,
+  enrichHealth,
+  unreachableHealth,
+  computeMetrics,
+  computeTypeDistribution,
+  DashboardClient,
+  transformGraphData,
+  toGraphologyFormat,
+  toD3ForceFormat,
+  Poller
+};

package/dist/chunk-Q4QIILKH.mjs

@@ -0,0 +1,190 @@
+// ../client/src/memory-client.ts
+var MemoryServerError = class extends Error {
+  status;
+  constructor(message, status) {
+    super(message);
+    this.name = "MemoryServerError";
+    this.status = status;
+  }
+  /** True when the server returned HTTP 404 (not found). */
+  get isNotFound() {
+    return this.status === 404;
+  }
+};
+var MemoryClient = class {
+  baseUrl;
+  constructor(memoryUrl) {
+    this.baseUrl = memoryUrl.replace(/\/$/, "");
+  }
+  /** Encode a path segment to prevent URL injection */
+  encodePathSegment(segment) {
+    return encodeURIComponent(segment);
+  }
+  async initialize() {
+    const response = await fetch(`${this.baseUrl}/health`);
+    if (!response.ok) {
+      throw new Error(`Memory server not reachable at ${this.baseUrl}: ${response.status}`);
+    }
+  }
+  async store(entry) {
+    return this.fetchApi("/api/memory/ingest", {
+      method: "POST",
+      body: JSON.stringify({
+        content: entry.content,
+        type: entry.type,
+        metadata: entry.metadata,
+        agentId: entry.agentId,
+        sessionId: entry.sessionId
+      })
+    });
+  }
+  async search(params) {
+    const searchParams = new URLSearchParams({ query: params.query });
+    if (params.limit) searchParams.set("limit", String(params.limit));
+    if (params.type) searchParams.set("type", params.type);
+    if (params.agentId) searchParams.set("agentId", params.agentId);
+    if (params.strategy) searchParams.set("strategy", params.strategy);
+    return this.fetchApi(`/api/memory/search?${searchParams}`);
+  }
+  async get(id) {
+    try {
+      return await this.fetchApi(`/api/memory/entries/${this.encodePathSegment(id)}`);
+    } catch (error) {
+      if (error instanceof MemoryServerError && error.isNotFound) return null;
+      throw error;
+    }
+  }
+  async delete(id) {
+    try {
+      await this.fetchApi(`/api/memory/entries/${this.encodePathSegment(id)}`, {
+        method: "DELETE"
+      });
+      return true;
+    } catch (error) {
+      if (error instanceof MemoryServerError && error.isNotFound) return false;
+      throw error;
+    }
+  }
+  async clearSession(sessionId) {
+    const result = await this.fetchApi(
+      `/api/memory/sessions/${this.encodePathSegment(sessionId)}`,
+      { method: "DELETE" }
+    );
+    return result.cleared;
+  }
+  async stats() {
+    const stats = await this.fetchApi("/api/memory/stats");
+    return { ...stats, connected: true };
+  }
+  async shutdown() {
+  }
+  async list(params = {}) {
+    const searchParams = new URLSearchParams();
+    if (params.page != null) searchParams.set("page", String(params.page));
+    if (params.limit != null) searchParams.set("limit", String(params.limit));
+    if (params.type) searchParams.set("type", params.type);
+    if (params.agentId) searchParams.set("agentId", params.agentId);
+    const qs = searchParams.toString();
+    return this.fetchApi(`/api/memory/entries${qs ? `?${qs}` : ""}`);
+  }
+  // --- Additional endpoints ---
+  async ingestFile(file) {
+    const formData = new FormData();
+    formData.append("file", file);
+    const res = await fetch(`${this.baseUrl}/api/memory/ingest/file`, {
+      method: "POST",
+      body: formData
+    });
+    const body = await res.json();
+    if (!body.success || body.data === void 0) {
+      throw new Error(body.error ?? `Memory server error: ${res.status}`);
+    }
+    return body.data;
+  }
+  /** @deprecated Use {@link list} instead. Kept for backwards compatibility. */
+  async listEntries(params) {
+    const result = await this.list(params);
+    return result.entries;
+  }
+  async graphNodes() {
+    const result = await this.fetchApi(
+      "/api/memory/graph/nodes"
+    );
+    return result.nodes;
+  }
+  async graphEdges() {
+    return this.fetchApi(
+      "/api/memory/graph/edges"
+    );
+  }
+  async graphQuery(query) {
+    return this.fetchApi("/api/memory/graph/query", {
+      method: "POST",
+      body: JSON.stringify(query)
+    });
+  }
+  // --- ExtendedMemoryInterface methods ---
+  async consolidate() {
+    return this.fetchApi("/api/memory/consolidate", {
+      method: "POST"
+    });
+  }
+  async forget(id, reason) {
+    try {
+      await this.fetchApi(`/api/memory/forget/${this.encodePathSegment(id)}`, {
+        method: "POST",
+        body: JSON.stringify({ reason })
+      });
+      return true;
+    } catch (error) {
+      if (error instanceof MemoryServerError && error.isNotFound) return false;
+      throw error;
+    }
+  }
+  async summarizeSession(sessionId) {
+    try {
+      return await this.fetchApi(
+        `/api/memory/sessions/${this.encodePathSegment(sessionId)}/summarize`,
+        { method: "POST" }
+      );
+    } catch (error) {
+      if (error instanceof MemoryServerError && error.isNotFound) return null;
+      throw error;
+    }
+  }
+  async runDecay() {
+    const result = await this.fetchApi("/api/memory/decay", {
+      method: "POST"
+    });
+    return result.archived;
+  }
+  async reindex() {
+    await this.fetchApi("/api/memory/reindex", { method: "POST" });
+  }
+  async deleteBySource(source) {
+    const result = await this.fetchApi(
+      `/api/memory/source/${this.encodePathSegment(source)}`,
+      { method: "DELETE" }
+    );
+    return result.deleted;
+  }
+  async fetchApi(path, options) {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        ...options?.headers
+      }
+    });
+    const body = await res.json();
+    if (!body.success || body.data === void 0) {
+      throw new MemoryServerError(body.error ?? `Memory server error: ${res.status}`, res.status);
+    }
+    return body.data;
+  }
+};
+
+export {
+  MemoryServerError,
+  MemoryClient
+};