cogmemai-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HiFriendbot
+
+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,108 @@
+# CogmemAi JavaScript/TypeScript SDK
+
+Persistent memory for AI coding assistants. Give your AI tools memory that persists across sessions.
+
+## Install
+
+```bash
+npm install cogmemai-sdk
+```
+
+## Quick Start
+
+```typescript
+import { CogmemAi } from "cogmemai-sdk";
+
+const client = new CogmemAi({ apiKey: "cm_your_api_key_here" });
+
+// Save a memory
+await client.saveMemory({
+  content: "This project uses React with TypeScript",
+  memory_type: "architecture",
+  category: "frontend",
+  importance: 8,
+});
+
+// Search memories
+const results = await client.recallMemories({
+  query: "what framework does this project use?",
+});
+
+// Load project context
+const context = await client.getProjectContext({
+  projectId: "my-project",
+});
+
+// Extract memories from conversation
+await client.extractMemories({
+  user_message: "Let's use PostgreSQL for the database",
+  assistant_response: "Good choice. I'll set up the schema with...",
+});
+```
+
+## All Methods
+
+### Core Memory
+- `saveMemory(options)` — Save a memory
+- `recallMemories(options)` — Semantic search
+- `extractMemories(options)` — Ai extracts facts from conversation
+- `getProjectContext(options?)` — Load top memories with smart ranking
+- `listMemories(options?)` — Browse with filters
+- `updateMemory(memoryId, options)` — Edit a memory
+- `deleteMemory(memoryId)` — Delete permanently
+- `getUsage()` — Check usage stats and tier
+
+### Documents & Sessions
+- `ingestDocument(options)` — Extract memories from docs
+- `saveSessionSummary(options)` — Capture session accomplishments
+
+### Import / Export
+- `exportMemories()` — Back up memories as JSON
+- `importMemories(memories)` — Bulk import from JSON
+- `getMemoryVersions(memoryId)` — Version history
+
+### Team & Collaboration
+- `getTeamMembers(projectId?)` — List team members
+- `inviteTeamMember(email, projectId, role?)` — Invite a member
+- `removeTeamMember(memberId)` — Remove a member
+
+### Memory Relationships & Promotion
+- `linkMemories(memoryId, relatedMemoryId, relationshipType)` — Link related memories
+- `getMemoryLinks(memoryId)` — Get linked memories
+- `getPromotionCandidates()` — Find cross-project patterns
+- `promoteToGlobal(memoryId)` — Promote to global scope
+
+## Error Handling
+
+```typescript
+import { CogmemAi, CogmemAiError } from "cogmemai-sdk";
+
+try {
+  await client.saveMemory({ content: "test" });
+} catch (err) {
+  if (err instanceof CogmemAiError) {
+    console.error(`Error ${err.statusCode}: ${err.message}`);
+  }
+}
+```
+
+## TypeScript
+
+Full type definitions included. All request options and response types are exported:
+
+```typescript
+import type { Memory, SaveMemoryOptions, RecallResult } from "cogmemai-sdk";
+```
+
+## Get an API Key
+
+1. Sign up at [hifriendbot.com/developer/](https://hifriendbot.com/developer/)
+2. Generate an API key
+3. Start saving memories
+
+## Links
+
+- [Developer Dashboard](https://hifriendbot.com/developer/)
+- [MCP Server (npm)](https://www.npmjs.com/package/cogmemai-mcp)
+- [Python SDK (PyPI)](https://pypi.org/project/cogmemai/)
+- [GitHub](https://github.com/hifriendbot/cogmemai-sdk)

package/dist/index.d.ts

@@ -0,0 +1,98 @@
+import type { CogmemAiOptions, SaveMemoryOptions, SaveMemoryResult, RecallOptions, RecallResult, ExtractOptions, ExtractResult, ContextOptions, ListOptions, UpdateMemoryOptions, IngestOptions, IngestResult, SessionSummaryOptions, ExportResult, ImportResult, MemoryVersion, UsageStats, TeamMember, MemoryLink, PromotionCandidate, Memory } from "./types.js";
+export type { CogmemAiOptions, SaveMemoryOptions, SaveMemoryResult, RecallOptions, RecallResult, ExtractOptions, ExtractResult, ContextOptions, ListOptions, UpdateMemoryOptions, IngestOptions, IngestResult, SessionSummaryOptions, ExportResult, ImportResult, MemoryVersion, UsageStats, TeamMember, MemoryLink, PromotionCandidate, Memory, };
+/** Error thrown by CogmemAi API calls. */
+export declare class CogmemAiError extends Error {
+    statusCode: number | undefined;
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * CogmemAi SDK client.
+ *
+ * @example
+ * ```ts
+ * import { CogmemAi } from "cogmemai-sdk";
+ *
+ * const client = new CogmemAi({ apiKey: "cm_your_key" });
+ *
+ * await client.saveMemory({
+ *   content: "This project uses React with TypeScript",
+ *   memory_type: "architecture",
+ *   importance: 8,
+ * });
+ *
+ * const results = await client.recallMemories({ query: "what framework?" });
+ * ```
+ */
+export declare class CogmemAi {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    constructor(options: CogmemAiOptions);
+    private request;
+    private get;
+    private post;
+    private patch;
+    private del;
+    /** Save a memory. */
+    saveMemory(options: SaveMemoryOptions): Promise<SaveMemoryResult>;
+    /** Semantic search across memories. */
+    recallMemories(options: RecallOptions): Promise<RecallResult>;
+    /** Extract memories from a conversation exchange using Ai. */
+    extractMemories(options: ExtractOptions): Promise<ExtractResult>;
+    /** Load project context with smart ranking. */
+    getProjectContext(options?: ContextOptions): Promise<RecallResult>;
+    /** List memories with filters. */
+    listMemories(options?: ListOptions): Promise<{
+        memories: Memory[];
+    }>;
+    /** Update a memory. */
+    updateMemory(memoryId: number, options: UpdateMemoryOptions): Promise<{
+        updated: boolean;
+    }>;
+    /** Delete a memory permanently. */
+    deleteMemory(memoryId: number): Promise<{
+        deleted: boolean;
+    }>;
+    /** Get usage stats and tier info. */
+    getUsage(): Promise<UsageStats>;
+    /** Extract memories from a document. */
+    ingestDocument(options: IngestOptions): Promise<IngestResult>;
+    /** Save a session summary. */
+    saveSessionSummary(options: SessionSummaryOptions): Promise<SaveMemoryResult>;
+    /** Export all memories as JSON. */
+    exportMemories(): Promise<ExportResult>;
+    /** Bulk import memories. */
+    importMemories(memories: SaveMemoryOptions[]): Promise<ImportResult>;
+    /** Get version history for a memory. */
+    getMemoryVersions(memoryId: number): Promise<{
+        versions: MemoryVersion[];
+    }>;
+    /** List team members. Requires Team or Enterprise tier. */
+    getTeamMembers(projectId?: string): Promise<{
+        members: TeamMember[];
+    }>;
+    /** Invite a team member. Requires Team or Enterprise tier. */
+    inviteTeamMember(email: string, projectId: string, role?: string): Promise<{
+        success: boolean;
+    }>;
+    /** Remove a team member. */
+    removeTeamMember(memberId: number): Promise<{
+        success: boolean;
+    }>;
+    /** Link two related memories. */
+    linkMemories(memoryId: number, relatedMemoryId: number, relationshipType: string): Promise<{
+        success: boolean;
+    }>;
+    /** Get linked memories. */
+    getMemoryLinks(memoryId: number): Promise<{
+        links: MemoryLink[];
+    }>;
+    /** Find cross-project patterns eligible for global promotion. */
+    getPromotionCandidates(): Promise<{
+        candidates: PromotionCandidate[];
+    }>;
+    /** Promote a project memory to global scope. */
+    promoteToGlobal(memoryId: number): Promise<{
+        success: boolean;
+    }>;
+}

package/dist/index.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CogmemAi = exports.CogmemAiError = void 0;
+/** Error thrown by CogmemAi API calls. */
+class CogmemAiError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.name = "CogmemAiError";
+        this.statusCode = statusCode;
+    }
+}
+exports.CogmemAiError = CogmemAiError;
+const DEFAULT_BASE_URL = "https://hifriendbot.com/wp-json/hifriendbot/v1";
+/**
+ * CogmemAi SDK client.
+ *
+ * @example
+ * ```ts
+ * import { CogmemAi } from "cogmemai-sdk";
+ *
+ * const client = new CogmemAi({ apiKey: "cm_your_key" });
+ *
+ * await client.saveMemory({
+ *   content: "This project uses React with TypeScript",
+ *   memory_type: "architecture",
+ *   importance: 8,
+ * });
+ *
+ * const results = await client.recallMemories({ query: "what framework?" });
+ * ```
+ */
+class CogmemAi {
+    apiKey;
+    baseUrl;
+    timeout;
+    constructor(options) {
+        if (!options.apiKey || !options.apiKey.startsWith("cm_")) {
+            throw new Error("API key must start with 'cm_'");
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+        this.timeout = options.timeout || 30000;
+    }
+    // ── Internal helpers ───────────────────────────────
+    async request(method, path, body, params) {
+        let url = `${this.baseUrl}/cogmemai/${path}`;
+        if (params) {
+            const qs = new URLSearchParams(params).toString();
+            if (qs)
+                url += `?${qs}`;
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const resp = await fetch(url, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    "Content-Type": "application/json",
+                },
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            let data;
+            try {
+                data = await resp.json();
+            }
+            catch {
+                throw new CogmemAiError(`Invalid JSON response`, resp.status);
+            }
+            if (!resp.ok) {
+                const msg = data?.error || data?.message || `HTTP ${resp.status}`;
+                throw new CogmemAiError(msg, resp.status);
+            }
+            return data;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    get(path, params) {
+        return this.request("GET", path, undefined, params);
+    }
+    post(path, body) {
+        return this.request("POST", path, body);
+    }
+    patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+    del(path) {
+        return this.request("DELETE", path);
+    }
+    // ── Core Memory ────────────────────────────────────
+    /** Save a memory. */
+    async saveMemory(options) {
+        return this.post("store", {
+            content: options.content,
+            memory_type: options.memory_type || "context",
+            category: options.category || "general",
+            subject: options.subject || "",
+            importance: options.importance ?? 5,
+            scope: options.scope || "project",
+            project_id: options.project_id || "",
+        });
+    }
+    /** Semantic search across memories. */
+    async recallMemories(options) {
+        const body = {
+            query: options.query,
+            limit: options.limit || 10,
+            scope: options.scope || "all",
+        };
+        if (options.memory_type)
+            body.memory_type = options.memory_type;
+        return this.post("recall", body);
+    }
+    /** Extract memories from a conversation exchange using Ai. */
+    async extractMemories(options) {
+        const body = { user_message: options.user_message };
+        if (options.assistant_response)
+            body.assistant_response = options.assistant_response;
+        if (options.previous_context)
+            body.previous_context = options.previous_context;
+        return this.post("extract", body);
+    }
+    /** Load project context with smart ranking. */
+    async getProjectContext(options = {}) {
+        const params = {
+            include_global: String(options.include_global ?? true),
+        };
+        if (options.project_id)
+            params.project_id = options.project_id;
+        if (options.context)
+            params.context = options.context;
+        return this.get("context", params);
+    }
+    /** List memories with filters. */
+    async listMemories(options = {}) {
+        const params = {
+            limit: String(options.limit || 50),
+            offset: String(options.offset || 0),
+            scope: options.scope || "all",
+        };
+        if (options.memory_type)
+            params.memory_type = options.memory_type;
+        if (options.category)
+            params.category = options.category;
+        return this.get("memories", params);
+    }
+    /** Update a memory. */
+    async updateMemory(memoryId, options) {
+        return this.patch(`memory/${memoryId}`, options);
+    }
+    /** Delete a memory permanently. */
+    async deleteMemory(memoryId) {
+        return this.del(`memory/${memoryId}`);
+    }
+    /** Get usage stats and tier info. */
+    async getUsage() {
+        return this.get("usage");
+    }
+    // ── Documents & Sessions ───────────────────────────
+    /** Extract memories from a document. */
+    async ingestDocument(options) {
+        const body = { text: options.text };
+        if (options.document_type)
+            body.document_type = options.document_type;
+        if (options.project_id)
+            body.project_id = options.project_id;
+        return this.post("ingest", body);
+    }
+    /** Save a session summary. */
+    async saveSessionSummary(options) {
+        const body = { summary: options.summary };
+        if (options.project_id)
+            body.project_id = options.project_id;
+        return this.post("session-summary", body);
+    }
+    // ── Import / Export / Versions ─────────────────────
+    /** Export all memories as JSON. */
+    async exportMemories() {
+        return this.get("export");
+    }
+    /** Bulk import memories. */
+    async importMemories(memories) {
+        return this.post("import", { memories });
+    }
+    /** Get version history for a memory. */
+    async getMemoryVersions(memoryId) {
+        return this.get(`memory/${memoryId}/versions`);
+    }
+    // ── Team & Collaboration ──────────────────────────
+    /** List team members. Requires Team or Enterprise tier. */
+    async getTeamMembers(projectId) {
+        const params = {};
+        if (projectId)
+            params.project_id = projectId;
+        return this.get("team/members", params);
+    }
+    /** Invite a team member. Requires Team or Enterprise tier. */
+    async inviteTeamMember(email, projectId, role = "member") {
+        return this.post("team/invite", { email, project_id: projectId, role });
+    }
+    /** Remove a team member. */
+    async removeTeamMember(memberId) {
+        return this.del(`team/remove/${memberId}`);
+    }
+    // ── Memory Relationships & Promotion ──────────────
+    /** Link two related memories. */
+    async linkMemories(memoryId, relatedMemoryId, relationshipType) {
+        return this.post(`memory/${memoryId}/link`, {
+            related_memory_id: relatedMemoryId,
+            relationship_type: relationshipType,
+        });
+    }
+    /** Get linked memories. */
+    async getMemoryLinks(memoryId) {
+        return this.get(`memory/${memoryId}/links`);
+    }
+    /** Find cross-project patterns eligible for global promotion. */
+    async getPromotionCandidates() {
+        return this.get("promotion-candidates");
+    }
+    /** Promote a project memory to global scope. */
+    async promoteToGlobal(memoryId) {
+        return this.post(`memory/${memoryId}/promote`, {});
+    }
+}
+exports.CogmemAi = CogmemAi;

package/dist/types.d.ts

@@ -0,0 +1,161 @@
+/** Memory object returned by the API. */
+export interface Memory {
+    id: number;
+    content: string;
+    memory_type: string;
+    category: string;
+    subject: string;
+    importance: number;
+    scope: string;
+    project_id: string;
+    custom_type: string | null;
+    is_sensitive: boolean;
+    times_referenced: number;
+    created_at: string;
+    updated_at: string;
+}
+/** Options for saving a memory. */
+export interface SaveMemoryOptions {
+    content: string;
+    memory_type?: string;
+    category?: string;
+    subject?: string;
+    importance?: number;
+    scope?: string;
+    project_id?: string;
+}
+/** Result from saving a memory. */
+export interface SaveMemoryResult {
+    memory_id: number;
+    stored: boolean;
+    deduplicated?: boolean;
+    updated_existing?: number;
+    conflict_detected?: boolean;
+    archived_memory_id?: number;
+    warning?: string;
+}
+/** Options for recalling memories. */
+export interface RecallOptions {
+    query: string;
+    limit?: number;
+    memory_type?: string;
+    scope?: string;
+}
+/** Result from recalling memories. */
+export interface RecallResult {
+    memories: Memory[];
+}
+/** Options for extracting memories from conversation. */
+export interface ExtractOptions {
+    user_message: string;
+    assistant_response?: string;
+    previous_context?: string;
+}
+/** Result from extracting memories. */
+export interface ExtractResult {
+    extracted: number;
+    memories: SaveMemoryResult[];
+}
+/** Options for loading project context. */
+export interface ContextOptions {
+    project_id?: string;
+    include_global?: boolean;
+    context?: string;
+}
+/** Options for listing memories. */
+export interface ListOptions {
+    memory_type?: string;
+    category?: string;
+    scope?: string;
+    limit?: number;
+    offset?: number;
+}
+/** Options for updating a memory. */
+export interface UpdateMemoryOptions {
+    content?: string;
+    importance?: number;
+    scope?: string;
+}
+/** Options for ingesting a document. */
+export interface IngestOptions {
+    text: string;
+    document_type?: string;
+    project_id?: string;
+}
+/** Result from ingesting a document. */
+export interface IngestResult {
+    chunks_processed: number;
+    extracted: number;
+    memories: SaveMemoryResult[];
+}
+/** Options for saving a session summary. */
+export interface SessionSummaryOptions {
+    summary: string;
+    project_id?: string;
+}
+/** Export result. */
+export interface ExportResult {
+    version: string;
+    exported_at: string;
+    memory_count: number;
+    memories: Memory[];
+}
+/** Import result. */
+export interface ImportResult {
+    imported: number;
+    skipped: number;
+    errors: number;
+}
+/** Memory version entry. */
+export interface MemoryVersion {
+    id: number;
+    content: string;
+    importance: number;
+    scope: string;
+    changed_by: string;
+    created_at: string;
+}
+/** Usage stats. */
+export interface UsageStats {
+    tier: string;
+    tier_name: string;
+    memories_count: number;
+    memories_limit: number;
+    extractions_count: number;
+    extractions_limit: number;
+    projects_count: number;
+    projects_limit: number;
+}
+/** Team member. */
+export interface TeamMember {
+    id: number;
+    member_user_id: number;
+    project_id: string;
+    role: string;
+    invited_at: string;
+    accepted_at: string | null;
+}
+/** Memory link. */
+export interface MemoryLink {
+    id: number;
+    memory_id: number;
+    related_memory_id: number;
+    relationship_type: string;
+    created_at: string;
+}
+/** Promotion candidate. */
+export interface PromotionCandidate {
+    subject: string;
+    memory_type: string;
+    project_count: number;
+    memories: Memory[];
+}
+/** CogmemAi client options. */
+export interface CogmemAiOptions {
+    /** API key (starts with cm_). */
+    apiKey: string;
+    /** Base URL. Defaults to hosted CogmemAi service. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to 30000. */
+    timeout?: number;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "cogmemai-sdk",
+  "version": "1.0.0",
+  "description": "CogmemAi — Persistent memory for AI coding assistants",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "memory",
+    "claude",
+    "coding-assistant",
+    "mcp",
+    "developer-tools",
+    "persistent-memory"
+  ],
+  "author": "HiFriendbot <developers@hifriendbot.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hifriendbot/cogmemai-sdk.git"
+  },
+  "homepage": "https://hifriendbot.com/developer/",
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}