@pyxmate/memory 0.0.5-beta → 0.1.1-beta

package/README.md

@@ -10,6 +10,16 @@ Provides an HTTP client, shared types, and optional dashboard + React hooks for
 npm install @pyxmate/memory
 ```
 
+## Setup Claude Code Skills
+
+If you use [Claude Code](https://docs.anthropic.com/en/docs/claude-code), run this command to install pyx-memory integration skills:
+
+```bash
+npx @pyxmate/memory init
+```
+
+This copies skill files into `.claude/skills/pyx-memory-integration/` so Claude Code auto-discovers pyx-memory patterns, types, and API reference when working in your project.
+
 ## Usage
 
 ```ts

package/bin/init.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+import { cpSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const command = process.argv[2];
+
+if (command !== 'init') {
+  console.log(`Usage: pyxmate-memory init
+
+Commands:
+  init    Copy pyx-memory skill files into .claude/skills/ for Claude Code auto-discovery`);
+  process.exit(command ? 1 : 0);
+}
+
+const source = resolve(__dirname, '..', 'skills', 'pyx-memory-integration');
+const target = resolve(process.cwd(), '.claude', 'skills', 'pyx-memory-integration');
+
+if (!existsSync(source)) {
+  console.error('Error: Skills directory not found in package. Please reinstall @pyxmate/memory.');
+  process.exit(1);
+}
+
+// Ensure target parent exists
+mkdirSync(dirname(target), { recursive: true });
+
+// Copy skills (overwrites existing files for idempotency)
+cpSync(source, target, { recursive: true });
+
+// Count copied files
+function countFiles(dir) {
+  let count = 0;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      count += countFiles(join(dir, entry.name));
+    } else {
+      count++;
+    }
+  }
+  return count;
+}
+
+function listFiles(dir, prefix = '') {
+  const lines = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      lines.push(...listFiles(join(dir, entry.name), `${prefix}${entry.name}/`));
+    } else {
+      lines.push(`  ${prefix}${entry.name}`);
+    }
+  }
+  return lines;
+}
+
+const fileCount = countFiles(target);
+const fileList = listFiles(target);
+
+console.log(`Copied ${fileCount} skill files to .claude/skills/pyx-memory-integration/\n`);
+console.log(fileList.join('\n'));
+console.log('\nClaude Code will now auto-discover pyx-memory integration patterns.');

package/dist/{chunk-Q4QIILKH.mjs → chunk-JMXAZPDT.mjs}

@@ -13,15 +13,20 @@ var MemoryServerError = class extends Error {
 };
 var MemoryClient = class {
   baseUrl;
-  constructor(memoryUrl) {
+  _authHeaders;
+  constructor(memoryUrl, apiKey) {
     this.baseUrl = memoryUrl.replace(/\/$/, "");
+    const trimmed = apiKey?.trim();
+    this._authHeaders = trimmed ? { Authorization: `Bearer ${trimmed}` } : {};
   }
   /** Encode a path segment to prevent URL injection */
   encodePathSegment(segment) {
     return encodeURIComponent(segment);
   }
   async initialize() {
-    const response = await fetch(`${this.baseUrl}/health`);
+    const response = await fetch(`${this.baseUrl}/health`, {
+      headers: this._authHeaders
+    });
     if (!response.ok) {
       throw new Error(`Memory server not reachable at ${this.baseUrl}: ${response.status}`);
     }
@@ -29,13 +34,7 @@ var MemoryClient = class {
   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
-      })
+      body: JSON.stringify(entry)
     });
   }
   async search(params) {
@@ -44,6 +43,11 @@ var MemoryClient = class {
     if (params.type) searchParams.set("type", params.type);
     if (params.agentId) searchParams.set("agentId", params.agentId);
     if (params.strategy) searchParams.set("strategy", params.strategy);
+    if (params.eventTimeRange) {
+      searchParams.set("eventTimeStart", params.eventTimeRange[0]);
+      searchParams.set("eventTimeEnd", params.eventTimeRange[1]);
+    }
+    if (params.asOf) searchParams.set("asOf", params.asOf);
     return this.fetchApi(`/api/memory/search?${searchParams}`);
   }
   async get(id) {
@@ -93,7 +97,8 @@ var MemoryClient = class {
     formData.append("file", file);
     const res = await fetch(`${this.baseUrl}/api/memory/ingest/file`, {
       method: "POST",
-      body: formData
+      body: formData,
+      headers: this._authHeaders
     });
     const body = await res.json();
     if (!body.success || body.data === void 0) {
@@ -168,12 +173,35 @@ var MemoryClient = class {
     );
     return result.deleted;
   }
+  async queryAsOf(asOfDate, filters = {}) {
+    const params = new URLSearchParams({ asOf: asOfDate });
+    if (filters.type) params.set("type", filters.type);
+    if (filters.agentId) params.set("agentId", filters.agentId);
+    if (filters.source) params.set("source", filters.source);
+    if (filters.limit) params.set("limit", String(filters.limit));
+    const result = await this.fetchApi(
+      `/api/memory/query-as-of?${params}`
+    );
+    return result.entries;
+  }
+  async queryByEventTime(startTime, endTime, filters = {}) {
+    const params = new URLSearchParams({ startTime, endTime });
+    if (filters.type) params.set("type", filters.type);
+    if (filters.agentId) params.set("agentId", filters.agentId);
+    if (filters.source) params.set("source", filters.source);
+    if (filters.limit) params.set("limit", String(filters.limit));
+    const result = await this.fetchApi(
+      `/api/memory/query-by-event-time?${params}`
+    );
+    return result.entries;
+  }
   async fetchApi(path, options) {
     const res = await fetch(`${this.baseUrl}${path}`, {
       ...options,
       headers: {
         "Content-Type": "application/json",
-        ...options?.headers
+        ...options?.headers,
+        ...this._authHeaders
       }
     });
     const body = await res.json();

package/dist/{chunk-EDIYGMT2.mjs → chunk-XNKO7F3P.mjs}

@@ -1,6 +1,6 @@
 import {
   MemoryClient
-} from "./chunk-Q4QIILKH.mjs";
+} from "./chunk-JMXAZPDT.mjs";
 
 // ../dashboard/src/aggregations/consolidation-analytics.ts
 function analyzeConsolidationLog(entries) {

package/dist/dashboard.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-EDIYGMT2.mjs";
-import "./chunk-Q4QIILKH.mjs";
+} from "./chunk-XNKO7F3P.mjs";
+import "./chunk-JMXAZPDT.mjs";
 export {
   DashboardClient,
   Poller,

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { MemoryEntry as MemoryEntry$1, MemorySearchParams as MemorySearchParams$1, MemorySearchResult as MemorySearchResult$1, MemoryType as MemoryType$1, MemoryStats as MemoryStats$1, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1 } from '@pyx-memory/shared';
+import { StoreInput as StoreInput$1, MemoryEntry as MemoryEntry$1, MemorySearchParams as MemorySearchParams$1, MemorySearchResult as MemorySearchResult$1, MemoryType as MemoryType$1, MemoryStats as MemoryStats$1, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1 } from '@pyx-memory/shared';
 
 /** Parameters for paginated entry listing. */
 interface MemoryListParams {
@@ -18,13 +18,17 @@ interface MemoryListResult {
     page: number;
     limit: number;
 }
+/** Filters for temporal queries (queryAsOf, queryByEventTime). */
+interface TemporalQueryFilters {
+    type?: MemoryType$1;
+    agentId?: string;
+    source?: string;
+    limit?: number;
+}
 /** Abstract interface for memory systems (local or remote). */
 interface MemoryInterface {
     initialize(): Promise<void>;
-    store(entry: Omit<MemoryEntry$1, 'id' | 'createdAt'> & {
-        id?: string;
-        createdAt?: string;
-    }): Promise<MemoryEntry$1>;
+    store(entry: StoreInput$1): Promise<MemoryEntry$1>;
     search(params: MemorySearchParams$1): Promise<MemorySearchResult$1>;
     /** List entries with SQL LIMIT/OFFSET pagination. */
     list(params?: MemoryListParams): Promise<MemoryListResult>;
@@ -32,6 +36,10 @@ interface MemoryInterface {
     delete(id: string): Promise<boolean>;
     clearSession(sessionId: string): Promise<number>;
     stats(): Promise<MemoryStats$1>;
+    /** Query entries as they existed at a point in time (by ingest time). */
+    queryAsOf(asOfDate: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
+    /** Query entries by event time range (when things actually happened). */
+    queryByEventTime(startTime: string, endTime: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
     shutdown(): Promise<void>;
 }
 /** Consolidation run result. */
@@ -59,7 +67,9 @@ interface ExtendedMemoryInterface extends MemoryInterface {
 
 interface IngestionResult {
     filename: string;
+    fileType: string;
     chunks: number;
+    entryIds: string[];
     totalCharacters: number;
 }
 
@@ -72,14 +82,12 @@ declare class MemoryServerError extends Error {
 }
 declare class MemoryClient implements ExtendedMemoryInterface {
     protected baseUrl: string;
-    constructor(memoryUrl: string);
+    private readonly _authHeaders;
+    constructor(memoryUrl: string, apiKey?: string);
     /** Encode a path segment to prevent URL injection */
     private encodePathSegment;
     initialize(): Promise<void>;
-    store(entry: Omit<MemoryEntry$1, 'id' | 'createdAt'> & {
-        id?: string;
-        createdAt?: string;
-    }): Promise<MemoryEntry$1>;
+    store(entry: StoreInput$1): Promise<MemoryEntry$1>;
     search(params: MemorySearchParams$1): Promise<MemorySearchResult$1>;
     get(id: string): Promise<MemoryEntry$1 | null>;
     delete(id: string): Promise<boolean>;
@@ -110,13 +118,14 @@ declare class MemoryClient implements ExtendedMemoryInterface {
     runDecay(): Promise<number>;
     reindex(): Promise<void>;
     deleteBySource(source: string): Promise<number>;
+    queryAsOf(asOfDate: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
+    queryByEventTime(startTime: string, endTime: string, filters?: TemporalQueryFilters): Promise<MemoryEntry$1[]>;
     protected fetchApi<T>(path: string, options?: RequestInit): Promise<T>;
 }
 
 declare const DEFAULTS: {
     readonly DATA_DIR: "./data";
     readonly VECTOR_PROVIDER: "lancedb";
-    readonly EMBEDDING_PROVIDER: "stub";
     readonly MEMORY_SERVER_PORT: 7822;
 };
 
@@ -148,12 +157,13 @@ declare const RAGStrategy: {
 type RAGStrategy = (typeof RAGStrategy)[keyof typeof RAGStrategy];
 declare const VectorProvider: {
     readonly LANCEDB: "lancedb";
-    readonly QDRANT: "qdrant";
 };
 type VectorProvider = (typeof VectorProvider)[keyof typeof VectorProvider];
 declare const EmbeddingProviderName: {
     readonly STUB: "stub";
+    /** @deprecated Vestigial — pyx-memory uses internal BGE-M3 embeddings. */
     readonly ANTHROPIC: "anthropic";
+    /** @deprecated Vestigial — pyx-memory uses internal BGE-M3 embeddings. */
     readonly OPENAI: "openai";
     readonly LOCAL: "local";
 };
@@ -165,6 +175,7 @@ interface MemoryEntry {
     agentId?: AgentId;
     sessionId?: string;
     metadata: Record<string, unknown>;
+    /** @deprecated Vestigial — embeddings are managed internally by the vector store. */
     embedding?: number[];
     createdAt: Timestamp;
     /** SHA-256 hash of content for deduplication. */
@@ -184,30 +195,16 @@ interface MemoryEntry {
     /** When this entry was ingested into the system. */
     ingestTime?: string;
 }
-interface SearchFilters {
-    /** Filter by source identifier. */
-    source?: string;
-    /** Minimum importance score. */
-    importanceMin?: number;
-    /** Event time range [start, end] as ISO timestamps. */
-    eventTimeRange?: [string, string];
-    /** Filter by parent entry ID. */
-    parentId?: string;
-    /** Filter by content type in metadata. */
-    contentType?: string;
-}
 interface MemorySearchParams {
     query: string;
     type?: MemoryType;
     agentId?: AgentId;
     limit?: number;
     strategy?: RAGStrategy;
-    /** Extended filters for Phase 1+ features. */
-    filters?: SearchFilters;
-    /** Enable Hypothetical Document Embedding for query expansion. */
-    enableHyDE?: boolean;
-    /** Enable reranking of results. */
-    enableRerank?: boolean;
+    /** Filter results to entries whose eventTime falls within [start, end] (ISO 8601). */
+    eventTimeRange?: [string, string];
+    /** Filter results to entries ingested before this cutoff (ISO 8601). Falls back to createdAt when ingestTime is null. */
+    asOf?: string;
 }
 interface MemorySearchResult {
     entries: MemoryEntry[];
@@ -219,11 +216,67 @@ interface MemorySearchResult {
         score: number;
     }>;
 }
+declare const StoreTarget: {
+    readonly SQLITE: "sqlite";
+    readonly VECTOR: "vector";
+    readonly GRAPH: "graph";
+};
+type StoreTarget = (typeof StoreTarget)[keyof typeof StoreTarget];
+/** Agent-provided entity for graph storage. */
+interface IngestEntity {
+    /** Entity name (e.g., "Alice", "TypeScript"). */
+    name: string;
+    /** Entity type — freeform, agent decides (e.g., "PERSON", "TOOL"). */
+    type: string;
+    /** Optional properties to attach to the graph node. */
+    properties?: Record<string, unknown>;
+}
+/** Agent-provided relationship for graph storage. */
+interface IngestRelationship {
+    /** Source entity name (must match an entity in the entities array). */
+    source: string;
+    /** Target entity name (must match an entity in the entities array). */
+    target: string;
+    /** Relationship type — freeform, agent decides (e.g., "WORKS_AT", "USES"). */
+    type: string;
+    /** Optional properties to attach to the graph edge. */
+    properties?: Record<string, unknown>;
+}
+/** Store input: what the agent sends to Memory.store(). */
+type StoreInput = Omit<MemoryEntry, 'id' | 'createdAt'> & {
+    id?: string;
+    createdAt?: string;
+    /** Storage targets. Default: ["sqlite", "vector"]. */
+    targets?: StoreTarget[];
+    /** Agent-provided entities for graph storage. Required when targets includes "graph". */
+    entities?: IngestEntity[];
+    /** Agent-provided relationships for graph storage. */
+    relationships?: IngestRelationship[];
+};
 interface MemoryIngestRequest {
     content?: string;
     type?: MemoryType;
-    fileType?: 'pdf' | 'csv' | 'txt';
     metadata?: Record<string, unknown>;
+    agentId?: string;
+    sessionId?: string;
+    /** Storage targets. Default: ["sqlite", "vector"]. */
+    targets?: StoreTarget[];
+    /** Agent-provided entities for graph storage. Required when targets includes "graph". */
+    entities?: IngestEntity[];
+    /** Agent-provided relationships for graph storage. */
+    relationships?: IngestRelationship[];
+    /** Importance score (1-10). */
+    importance?: number;
+    /** Source identifier (e.g., filename, URL). */
+    source?: string;
+    /** When the event occurred (ISO timestamp). */
+    eventTime?: string;
+    /** Optional deterministic ID for the entry (agent-provided). */
+    id?: string;
+    /** Parent entry ID for hierarchical storage (e.g., doc → section → chunk). */
+    parentId?: string;
+    /** When this entry was ingested (ISO timestamp). Default: now. */
+    ingestTime?: string;
 }
 interface MemoryStats {
     totalEntries: number;
@@ -235,14 +288,6 @@ interface MemoryStats {
     /** Whether the memory service is connected. False when using DisabledMemory. */
     connected?: boolean;
 }
-interface GraphEdge {
-    id: string;
-    sourceEntity: string;
-    targetEntity: string;
-    relation: string;
-    weight: number;
-    memoryEntryId: string;
-}
 interface GraphNode {
     id: string;
     name: string;
@@ -267,4 +312,4 @@ interface GraphTraversalResult {
     }>;
 }
 
-export { type AgentId, type ApiResponse, type ConsolidationRunResult, DEFAULTS, EmbeddingProviderName, type ExtendedMemoryInterface, type GraphEdge, type GraphNode, type GraphRelationship, type GraphTraversalResult, type IngestionResult, MemoryClient, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, RAGStrategy, type SearchFilters, type Timestamp, VectorProvider };
+export { type AgentId, type ApiResponse, type ConsolidationRunResult, DEFAULTS, EmbeddingProviderName, type ExtendedMemoryInterface, type GraphNode, type GraphRelationship, type GraphTraversalResult, type IngestEntity, type IngestRelationship, type IngestionResult, MemoryClient, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, RAGStrategy, type StoreInput, StoreTarget, type TemporalQueryFilters, type Timestamp, VectorProvider };

package/dist/index.mjs

@@ -1,13 +1,12 @@
 import {
   MemoryClient,
   MemoryServerError
-} from "./chunk-Q4QIILKH.mjs";
+} from "./chunk-JMXAZPDT.mjs";
 
 // ../shared/src/constants/defaults.ts
 var DEFAULTS = {
   DATA_DIR: "./data",
   VECTOR_PROVIDER: "lancedb",
-  EMBEDDING_PROVIDER: "stub",
   MEMORY_SERVER_PORT: 7822
 };
 
@@ -26,15 +25,21 @@ var RAGStrategy = {
   HYBRID: "hybrid"
 };
 var VectorProvider = {
-  LANCEDB: "lancedb",
-  QDRANT: "qdrant"
+  LANCEDB: "lancedb"
 };
 var EmbeddingProviderName = {
   STUB: "stub",
+  /** @deprecated Vestigial — pyx-memory uses internal BGE-M3 embeddings. */
   ANTHROPIC: "anthropic",
+  /** @deprecated Vestigial — pyx-memory uses internal BGE-M3 embeddings. */
   OPENAI: "openai",
   LOCAL: "local"
 };
+var StoreTarget = {
+  SQLITE: "sqlite",
+  VECTOR: "vector",
+  GRAPH: "graph"
+};
 export {
   DEFAULTS,
   EmbeddingProviderName,
@@ -42,5 +47,6 @@ export {
   MemoryServerError,
   MemoryType,
   RAGStrategy,
+  StoreTarget,
   VectorProvider
 };

package/dist/react.mjs

@@ -11,8 +11,8 @@ import {
   toGraphologyFormat,
   transformGraphData,
   unreachableHealth
-} from "./chunk-EDIYGMT2.mjs";
-import "./chunk-Q4QIILKH.mjs";
+} from "./chunk-XNKO7F3P.mjs";
+import "./chunk-JMXAZPDT.mjs";
 
 // ../dashboard/src/hooks/use-consolidation-log.ts
 import { useCallback as useCallback2, useMemo } from "react";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "0.0.5-beta",
+  "version": "0.1.1-beta",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",
@@ -33,15 +33,21 @@
       "types": "./dist/react.d.ts"
     }
   },
+  "bin": {
+    "pyxmate-memory": "./bin/init.mjs"
+  },
   "files": [
     "dist",
+    "bin",
+    "skills",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup",
+    "copy-skills": "rm -rf skills/pyx-memory-integration && mkdir -p skills && cp -r ../../.claude/skills/pyx-memory-integration skills/pyx-memory-integration && rm -rf skills/pyx-memory-integration/scripts",
+    "build": "bun run copy-skills && tsup",
     "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist node_modules .turbo"
+    "clean": "rm -rf dist skills node_modules .turbo"
   },
   "peerDependencies": {
     "react": ">=18.0.0"