@keyoku/memory 1.0.0

package/dist/client.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Typed HTTP client for the Keyoku memory engine API
+ */
+import type { Memory, SearchResult, RememberResult, HeartbeatResult, HeartbeatContextResult, MemoryStats } from '@keyoku/types';
+export { type Memory, type SearchResult, type RememberResult, type HeartbeatResult, type HeartbeatContextResult, type MemoryStats } from '@keyoku/types';
+export declare class KeyokuError extends Error {
+    readonly status: number;
+    readonly path: string;
+    constructor(status: number, message: string, path: string);
+}
+export declare class KeyokuClient {
+    private baseUrl;
+    private timeout;
+    constructor(options: {
+        baseUrl?: string;
+        timeout?: number;
+    });
+    private request;
+    remember(entityId: string, content: string, options?: {
+        session_id?: string;
+        agent_id?: string;
+        source?: string;
+        team_id?: string;
+        visibility?: string;
+    }): Promise<RememberResult>;
+    search(entityId: string, query: string, options?: {
+        limit?: number;
+        mode?: string;
+        agent_id?: string;
+        team_aware?: boolean;
+        min_score?: number;
+    }): Promise<SearchResult[]>;
+    listMemories(entityId: string, limit?: number): Promise<Memory[]>;
+    getMemory(id: string): Promise<Memory>;
+    deleteMemory(id: string): Promise<{
+        status: string;
+    }>;
+    deleteAllMemories(entityId: string): Promise<{
+        status: string;
+    }>;
+    getStats(entityId: string): Promise<MemoryStats>;
+    heartbeatCheck(entityId: string, options?: {
+        deadline_window?: string;
+        decay_threshold?: number;
+        importance_floor?: number;
+        max_results?: number;
+        agent_id?: string;
+        team_id?: string;
+    }): Promise<HeartbeatResult>;
+    /** Combined heartbeat + context search in a single call, with optional LLM analysis. */
+    heartbeatContext(entityId: string, options?: {
+        query?: string;
+        top_k?: number;
+        min_score?: number;
+        deadline_window?: string;
+        max_results?: number;
+        agent_id?: string;
+        team_id?: string;
+        analyze?: boolean;
+        activity_summary?: string;
+        autonomy?: 'observe' | 'suggest' | 'act';
+    }): Promise<HeartbeatContextResult>;
+    createSchedule(entityId: string, agentId: string, content: string, cronTag: string): Promise<Memory>;
+    listSchedules(entityId: string, agentId?: string): Promise<Memory[]>;
+    ackSchedule(memoryId: string): Promise<{
+        status: string;
+        memory_id: string;
+    }>;
+    cancelSchedule(id: string): Promise<{
+        status: string;
+        memory_id: string;
+    }>;
+}
+//# 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":"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"}

package/dist/client.js

@@ -0,0 +1,113 @@
+/**
+ * Typed HTTP client for the Keyoku memory engine API
+ */
+export class KeyokuError extends Error {
+    status;
+    path;
+    constructor(status, message, path) {
+        super(`Keyoku error (${status}) on ${path}: ${message}`);
+        this.status = status;
+        this.path = path;
+        this.name = 'KeyokuError';
+    }
+}
+export class KeyokuClient {
+    baseUrl;
+    timeout;
+    constructor(options) {
+        this.baseUrl = (options.baseUrl ?? 'http://localhost:18900').replace(/\/$/, '');
+        this.timeout = options.timeout ?? 10000;
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const headers = {};
+            if (body)
+                headers['Content-Type'] = 'application/json';
+            const res = await fetch(url, {
+                method,
+                headers: Object.keys(headers).length > 0 ? headers : undefined,
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const errBody = await res.json().catch(() => ({}));
+                throw new KeyokuError(res.status, errBody.error || res.statusText, path);
+            }
+            return await res.json();
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // === Memory ===
+    async remember(entityId, content, options) {
+        return this.request('POST', '/api/v1/remember', {
+            entity_id: entityId,
+            content,
+            ...options,
+        });
+    }
+    async search(entityId, query, options) {
+        return this.request('POST', '/api/v1/search', {
+            entity_id: entityId,
+            query,
+            ...options,
+        });
+    }
+    async listMemories(entityId, limit = 100) {
+        return this.request('GET', `/api/v1/memories?entity_id=${entityId}&limit=${limit}`);
+    }
+    async getMemory(id) {
+        return this.request('GET', `/api/v1/memories/${id}`);
+    }
+    async deleteMemory(id) {
+        return this.request('DELETE', `/api/v1/memories/${id}`);
+    }
+    async deleteAllMemories(entityId) {
+        return this.request('DELETE', '/api/v1/memories', { entity_id: entityId });
+    }
+    async getStats(entityId) {
+        return this.request('GET', `/api/v1/stats/${entityId}`);
+    }
+    // === Heartbeat ===
+    async heartbeatCheck(entityId, options) {
+        return this.request('POST', '/api/v1/heartbeat/check', {
+            entity_id: entityId,
+            ...options,
+        });
+    }
+    /** Combined heartbeat + context search in a single call, with optional LLM analysis. */
+    async heartbeatContext(entityId, options) {
+        return this.request('POST', '/api/v1/heartbeat/context', {
+            entity_id: entityId,
+            ...options,
+        });
+    }
+    // === Schedules ===
+    async createSchedule(entityId, agentId, content, cronTag) {
+        return this.request('POST', '/api/v1/schedule', {
+            entity_id: entityId,
+            agent_id: agentId,
+            content,
+            cron_tag: cronTag,
+        });
+    }
+    async listSchedules(entityId, agentId) {
+        const params = new URLSearchParams({ entity_id: entityId });
+        if (agentId)
+            params.set('agent_id', agentId);
+        return this.request('GET', `/api/v1/scheduled?${params}`);
+    }
+    async ackSchedule(memoryId) {
+        return this.request('POST', '/api/v1/schedule/ack', {
+            memory_id: memoryId,
+        });
+    }
+    async cancelSchedule(id) {
+        return this.request('DELETE', `/api/v1/schedule/${id}`);
+    }
+}
+//# 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,3 @@
+export { KeyokuClient, KeyokuError } from './client.js';
+export type { Memory, SearchResult, RememberResult, HeartbeatResult, MemoryStats } from './client.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,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { KeyokuClient, KeyokuError } 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,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@keyoku/memory",
+  "version": "1.0.0",
+  "description": "Keyoku memory engine HTTP client",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "dependencies": {
+    "@keyoku/types": "1.0.0"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/client.ts

@@ -0,0 +1,174 @@
+/**
+ * Typed HTTP client for the Keyoku memory engine API
+ */
+
+import type {
+  Memory,
+  SearchResult,
+  RememberResult,
+  HeartbeatResult,
+  HeartbeatContextResult,
+  MemoryStats,
+} from '@keyoku/types';
+
+export { type Memory, type SearchResult, type RememberResult, type HeartbeatResult, type HeartbeatContextResult, type MemoryStats } from '@keyoku/types';
+
+export class KeyokuError extends Error {
+  constructor(
+    public readonly status: number,
+    message: string,
+    public readonly path: string,
+  ) {
+    super(`Keyoku error (${status}) on ${path}: ${message}`);
+    this.name = 'KeyokuError';
+  }
+}
+
+export class KeyokuClient {
+  private baseUrl: string;
+  private timeout: number;
+
+  constructor(options: { baseUrl?: string; timeout?: number }) {
+    this.baseUrl = (options.baseUrl ?? 'http://localhost:18900').replace(/\/$/, '');
+    this.timeout = options.timeout ?? 10000;
+  }
+
+  private async request<T>(method: string, path: string, body?: unknown): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const headers: Record<string, string> = {};
+      if (body) headers['Content-Type'] = 'application/json';
+
+      const res = await fetch(url, {
+        method,
+        headers: Object.keys(headers).length > 0 ? headers : undefined,
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      if (!res.ok) {
+        const errBody = await res.json().catch(() => ({}));
+        throw new KeyokuError(res.status, (errBody as Record<string, string>).error || res.statusText, path);
+      }
+
+      return await res.json() as T;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // === Memory ===
+
+  async remember(entityId: string, content: string, options?: {
+    session_id?: string;
+    agent_id?: string;
+    source?: string;
+    team_id?: string;
+    visibility?: string;
+  }): Promise<RememberResult> {
+    return this.request<RememberResult>('POST', '/api/v1/remember', {
+      entity_id: entityId,
+      content,
+      ...options,
+    });
+  }
+
+  async search(entityId: string, query: string, options?: {
+    limit?: number;
+    mode?: string;
+    agent_id?: string;
+    team_aware?: boolean;
+    min_score?: number;
+  }): Promise<SearchResult[]> {
+    return this.request<SearchResult[]>('POST', '/api/v1/search', {
+      entity_id: entityId,
+      query,
+      ...options,
+    });
+  }
+
+  async listMemories(entityId: string, limit = 100): Promise<Memory[]> {
+    return this.request<Memory[]>('GET', `/api/v1/memories?entity_id=${entityId}&limit=${limit}`);
+  }
+
+  async getMemory(id: string): Promise<Memory> {
+    return this.request<Memory>('GET', `/api/v1/memories/${id}`);
+  }
+
+  async deleteMemory(id: string): Promise<{ status: string }> {
+    return this.request<{ status: string }>('DELETE', `/api/v1/memories/${id}`);
+  }
+
+  async deleteAllMemories(entityId: string): Promise<{ status: string }> {
+    return this.request<{ status: string }>('DELETE', '/api/v1/memories', { entity_id: entityId });
+  }
+
+  async getStats(entityId: string): Promise<MemoryStats> {
+    return this.request<MemoryStats>('GET', `/api/v1/stats/${entityId}`);
+  }
+
+  // === Heartbeat ===
+
+  async heartbeatCheck(entityId: string, options?: {
+    deadline_window?: string;
+    decay_threshold?: number;
+    importance_floor?: number;
+    max_results?: number;
+    agent_id?: string;
+    team_id?: string;
+  }): Promise<HeartbeatResult> {
+    return this.request<HeartbeatResult>('POST', '/api/v1/heartbeat/check', {
+      entity_id: entityId,
+      ...options,
+    });
+  }
+
+  /** Combined heartbeat + context search in a single call, with optional LLM analysis. */
+  async heartbeatContext(entityId: string, options?: {
+    query?: string;
+    top_k?: number;
+    min_score?: number;
+    deadline_window?: string;
+    max_results?: number;
+    agent_id?: string;
+    team_id?: string;
+    analyze?: boolean;
+    activity_summary?: string;
+    autonomy?: 'observe' | 'suggest' | 'act';
+  }): Promise<HeartbeatContextResult> {
+    return this.request<HeartbeatContextResult>('POST', '/api/v1/heartbeat/context', {
+      entity_id: entityId,
+      ...options,
+    });
+  }
+
+  // === Schedules ===
+
+  async createSchedule(entityId: string, agentId: string, content: string, cronTag: string): Promise<Memory> {
+    return this.request<Memory>('POST', '/api/v1/schedule', {
+      entity_id: entityId,
+      agent_id: agentId,
+      content,
+      cron_tag: cronTag,
+    });
+  }
+
+  async listSchedules(entityId: string, agentId?: string): Promise<Memory[]> {
+    const params = new URLSearchParams({ entity_id: entityId });
+    if (agentId) params.set('agent_id', agentId);
+    return this.request<Memory[]>('GET', `/api/v1/scheduled?${params}`);
+  }
+
+  async ackSchedule(memoryId: string): Promise<{ status: string; memory_id: string }> {
+    return this.request<{ status: string; memory_id: string }>('POST', '/api/v1/schedule/ack', {
+      memory_id: memoryId,
+    });
+  }
+
+  async cancelSchedule(id: string): Promise<{ status: string; memory_id: string }> {
+    return this.request<{ status: string; memory_id: string }>('DELETE', `/api/v1/schedule/${id}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { KeyokuClient, KeyokuError } from './client.js';
+export type { Memory, SearchResult, RememberResult, HeartbeatResult, MemoryStats } from './client.js';

package/test/client.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { KeyokuClient, KeyokuError } from '../src/client.js';
+
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+function jsonResponse(data: unknown, status = 200) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status === 200 ? 'OK' : 'Error',
+    json: () => Promise.resolve(data),
+  };
+}
+
+describe('KeyokuClient', () => {
+  let client: KeyokuClient;
+
+  beforeEach(() => {
+    client = new KeyokuClient({ baseUrl: 'http://localhost:18900' });
+    mockFetch.mockReset();
+  });
+
+  describe('constructor', () => {
+    it('defaults to localhost:18900', () => {
+      const c = new KeyokuClient({});
+      mockFetch.mockResolvedValue(jsonResponse([]));
+      c.listMemories('entity-1');
+
+      const url = mockFetch.mock.calls[0][0];
+      expect(url).toContain('http://localhost:18900');
+    });
+
+    it('strips trailing slash', () => {
+      const c = new KeyokuClient({ baseUrl: 'http://example.com/' });
+      mockFetch.mockResolvedValue(jsonResponse([]));
+      c.listMemories('e1');
+
+      const url = mockFetch.mock.calls[0][0];
+      expect(url.startsWith('http://example.com/api')).toBe(true);
+    });
+  });
+
+  describe('remember', () => {
+    it('calls POST /api/v1/remember with content', async () => {
+      mockFetch.mockResolvedValue(jsonResponse({
+        memories_created: 1,
+        memories_updated: 0,
+        memories_deleted: 0,
+        skipped: 0,
+      }));
+
+      const result = await client.remember('entity-1', 'Important fact', {
+        agent_id: 'agent-1',
+        team_id: 'team-1',
+      });
+
+      expect(result.memories_created).toBe(1);
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.entity_id).toBe('entity-1');
+      expect(body.content).toBe('Important fact');
+      expect(body.agent_id).toBe('agent-1');
+    });
+  });
+
+  describe('search', () => {
+    it('calls POST /api/v1/search', async () => {
+      mockFetch.mockResolvedValue(jsonResponse([
+        { memory: { id: 'm1', content: 'test' }, similarity: 0.9, score: 0.85 },
+      ]));
+
+      const results = await client.search('entity-1', 'test query', { limit: 5 });
+
+      expect(results).toHaveLength(1);
+      expect(results[0].similarity).toBe(0.9);
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.query).toBe('test query');
+      expect(body.limit).toBe(5);
+    });
+  });
+
+  describe('listMemories', () => {
+    it('calls GET with entity_id and limit', async () => {
+      mockFetch.mockResolvedValue(jsonResponse([]));
+
+      await client.listMemories('entity-1', 50);
+
+      const url = mockFetch.mock.calls[0][0];
+      expect(url).toContain('entity_id=entity-1');
+      expect(url).toContain('limit=50');
+    });
+
+    it('defaults limit to 100', async () => {
+      mockFetch.mockResolvedValue(jsonResponse([]));
+      await client.listMemories('entity-1');
+
+      const url = mockFetch.mock.calls[0][0];
+      expect(url).toContain('limit=100');
+    });
+  });
+
+  describe('getMemory', () => {
+    it('calls GET /api/v1/memories/:id', async () => {
+      const memory = { id: 'm1', content: 'test', entity_id: 'e1' };
+      mockFetch.mockResolvedValue(jsonResponse(memory));
+
+      const result = await client.getMemory('m1');
+      expect(result.id).toBe('m1');
+      expect(mockFetch).toHaveBeenCalledWith(
+        'http://localhost:18900/api/v1/memories/m1',
+        expect.anything(),
+      );
+    });
+  });
+
+  describe('deleteMemory', () => {
+    it('calls DELETE /api/v1/memories/:id', async () => {
+      mockFetch.mockResolvedValue(jsonResponse({ status: 'deleted' }));
+
+      const result = await client.deleteMemory('m1');
+      expect(result.status).toBe('deleted');
+      expect(mockFetch.mock.calls[0][1].method).toBe('DELETE');
+    });
+  });
+
+  describe('deleteAllMemories', () => {
+    it('calls DELETE with entity_id body', async () => {
+      mockFetch.mockResolvedValue(jsonResponse({ status: 'deleted' }));
+
+      await client.deleteAllMemories('entity-1');
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.entity_id).toBe('entity-1');
+    });
+  });
+
+  describe('getStats', () => {
+    it('calls GET /api/v1/stats/:entityId', async () => {
+      const stats = { total_memories: 42, active_memories: 30, by_type: {}, by_state: {} };
+      mockFetch.mockResolvedValue(jsonResponse(stats));
+
+      const result = await client.getStats('entity-1');
+      expect(result.total_memories).toBe(42);
+    });
+  });
+
+  describe('heartbeatCheck', () => {
+    it('calls POST /api/v1/heartbeat/check', async () => {
+      mockFetch.mockResolvedValue(jsonResponse({
+        should_act: false,
+        pending_work: [],
+        deadlines: [],
+        scheduled: [],
+        decaying: [],
+        conflicts: [],
+        stale_monitors: [],
+        summary: 'All clear',
+      }));
+
+      const result = await client.heartbeatCheck('entity-1', {
+        deadline_window: '1h',
+        max_results: 10,
+      });
+
+      expect(result.should_act).toBe(false);
+      expect(result.summary).toBe('All clear');
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.entity_id).toBe('entity-1');
+      expect(body.deadline_window).toBe('1h');
+    });
+  });
+
+  describe('schedules', () => {
+    it('createSchedule sends correct body', async () => {
+      mockFetch.mockResolvedValue(jsonResponse({ id: 's1' }));
+
+      await client.createSchedule('entity-1', 'agent-1', 'Daily standup', 'daily');
+
+      const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+      expect(body.entity_id).toBe('entity-1');
+      expect(body.agent_id).toBe('agent-1');
+      expect(body.content).toBe('Daily standup');
+      expect(body.cron_tag).toBe('daily');
+    });
+
+    it('listSchedules filters by agent', async () => {
+      mockFetch.mockResolvedValue(jsonResponse([]));
+
+      await client.listSchedules('entity-1', 'agent-1');
+
+      const url = mockFetch.mock.calls[0][0];
+      expect(url).toContain('entity_id=entity-1');
+      expect(url).toContain('agent_id=agent-1');
+    });
+
+    it('ackSchedule calls POST', async () => {
+      mockFetch.mockResolvedValue(jsonResponse({ status: 'acknowledged', memory_id: 'm1' }));
+
+      const result = await client.ackSchedule('m1');
+      expect(result.status).toBe('acknowledged');
+    });
+
+    it('cancelSchedule calls DELETE', async () => {
+      mockFetch.mockResolvedValue(jsonResponse({ status: 'cancelled', memory_id: 's1' }));
+
+      const result = await client.cancelSchedule('s1');
+      expect(result.status).toBe('cancelled');
+      expect(mockFetch.mock.calls[0][1].method).toBe('DELETE');
+    });
+  });
+
+  describe('error handling', () => {
+    it('throws KeyokuError on non-OK response', async () => {
+      mockFetch.mockResolvedValue(jsonResponse({ error: 'Not found' }, 404));
+
+      await expect(client.getMemory('bad-id')).rejects.toThrow(KeyokuError);
+    });
+
+    it('includes status and path in error', async () => {
+      mockFetch.mockResolvedValue(jsonResponse({ error: 'Server error' }, 500));
+
+      try {
+        await client.getStats('e1');
+      } catch (err) {
+        expect(err).toBeInstanceOf(KeyokuError);
+        expect((err as KeyokuError).status).toBe(500);
+        expect((err as KeyokuError).path).toContain('/api/v1/stats/e1');
+      }
+    });
+  });
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{"extends":"../../tsconfig.json","compilerOptions":{"outDir":"dist","rootDir":"src"},"include":["src"]}