anansi-memory 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# anansi-memory
+
+The memory layer for AI apps. Give any LLM application persistent, synthesized memory in two API calls.
+
+```bash
+npm install anansi-memory
+```
+
+## Usage
+
+```typescript
+import AnansiMemory from "@anansi/memory";
+
+const memory = new AnansiMemory({ apiKey: process.env.ANANSI_API_KEY });
+
+// Store a conversation turn
+await memory.ingest({
+  userId: "user_123",
+  content: "User is building a voice agent. Prefers TypeScript. Team of 4.",
+  sourceType: "conversation",
+});
+
+// Before your next LLM call — inject synthesized context into system prompt
+const ctx = await memory.context({ userId: "user_123", q: "what is the user building?" });
+const systemPrompt = `You are a helpful assistant.\n\n${memory.formatForPrompt(ctx)}`;
+```
+
+## API
+
+### `new AnansiMemory(options)`
+
+| Option | Type | Description |
+|---|---|---|
+| `apiKey` | `string` | Your API key (`zzy_...`) |
+| `baseUrl` | `string` | Override API base URL (default: `https://api.zazzy.app`) |
+
+### `memory.ingest(options)`
+
+Store content in a user's memory. Returns `{ id, queued: true }`.
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `userId` | `string` | ✓ | Your internal user ID |
+| `content` | `string` | ✓ | Text to remember, max 100 KB |
+| `sourceType` | `string` | | `conversation`, `document`, `note`, `meeting`, `custom` |
+| `sourceId` | `string` | | Idempotency key — re-ingesting the same ID is a no-op |
+| `metadata` | `object` | | `title`, `author`, `timestamp`, any custom fields |
+
+### `memory.context(options)`
+
+Retrieve synthesized memory for a user. Returns `{ static, dynamic, relevant }`.
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `userId` | `string` | ✓ | Your internal user ID |
+| `q` | `string` | | Optional query to retrieve relevant chunks |
+
+### `memory.formatForPrompt(ctx)`
+
+Format a context result into a ready-to-inject system prompt block.
+
+## Error handling
+
+```typescript
+import AnansiMemory, { AnansiError } from "@anansi/memory";
+
+try {
+  await memory.ingest({ userId, content });
+} catch (err) {
+  if (err instanceof AnansiError) {
+    console.error(err.statusCode, err.message);
+    // 401 — invalid API key
+    // 402 — monthly quota exceeded
+    // 413 — content too large
+    // 429 — rate limit (retry after 60s)
+  }
+}
+```
+
+## Links
+
+- [Developer Portal](https://api.zazzy.app/portal)
+- [API Docs](https://api.zazzy.app/docs)
+- [GitHub](https://github.com/JibrilSul/zazzy)

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+export interface AnansiMemoryOptions {
+    apiKey: string;
+    baseUrl?: string;
+}
+export interface IngestOptions {
+    userId: string;
+    content: string;
+    sourceType?: "conversation" | "document" | "note" | "meeting" | "custom";
+    sourceId?: string;
+    metadata?: {
+        title?: string;
+        author?: string;
+        timestamp?: string;
+        [key: string]: unknown;
+    };
+}
+export interface IngestResult {
+    id: string;
+    queued: boolean;
+}
+export interface ContextOptions {
+    userId: string;
+    q?: string;
+}
+export interface RelevantChunk {
+    content: string;
+    similarity: number;
+    metadata: Record<string, unknown>;
+}
+export interface ContextResult {
+    static: string[];
+    dynamic: string[];
+    relevant: RelevantChunk[];
+}
+export declare class AnansiMemory {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(options: AnansiMemoryOptions);
+    private request;
+    ingest(options: IngestOptions): Promise<IngestResult>;
+    context(options: ContextOptions): Promise<ContextResult>;
+    formatForPrompt(ctx: ContextResult): string;
+}
+export declare class AnansiError extends Error {
+    readonly statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+export default AnansiMemory;
+//# 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":"AAGA,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,cAAc,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE;QACT,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,EAAE,mBAAmB;YAM1B,OAAO;IA2Bf,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAUrD,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAM9D,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM;CAsB5C;AAED,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAKhD;AAED,eAAe,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,76 @@
+// anansi-memory — The memory layer for AI apps
+// Two calls: ingest content, retrieve synthesized context.
+export class AnansiMemory {
+    constructor(options) {
+        if (!options.apiKey)
+            throw new Error("AnansiMemory: apiKey is required");
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? "https://api.zazzy.app").replace(/\/$/, "");
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const res = await fetch(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!res.ok) {
+            let message = `Anansi API error ${res.status}`;
+            try {
+                const err = (await res.json());
+                if (err.error)
+                    message = err.error;
+            }
+            catch { }
+            throw new AnansiError(message, res.status);
+        }
+        return res.json();
+    }
+    async ingest(options) {
+        return this.request("POST", "/v1/ingest", {
+            userId: options.userId,
+            content: options.content,
+            sourceType: options.sourceType,
+            sourceId: options.sourceId,
+            metadata: options.metadata,
+        });
+    }
+    async context(options) {
+        const params = new URLSearchParams({ userId: options.userId });
+        if (options.q)
+            params.set("q", options.q);
+        return this.request("GET", `/v1/context?${params}`);
+    }
+    formatForPrompt(ctx) {
+        const lines = [];
+        if (ctx.static.length > 0) {
+            lines.push("## User — Stable facts");
+            ctx.static.forEach((f) => lines.push(`- ${f}`));
+        }
+        if (ctx.dynamic.length > 0) {
+            if (lines.length > 0)
+                lines.push("");
+            lines.push("## User — Current context");
+            ctx.dynamic.forEach((d) => lines.push(`- ${d}`));
+        }
+        if (ctx.relevant.length > 0) {
+            if (lines.length > 0)
+                lines.push("");
+            lines.push("## Relevant history");
+            ctx.relevant.forEach((r) => lines.push(`- ${r.content}`));
+        }
+        return lines.join("\n");
+    }
+}
+export class AnansiError extends Error {
+    constructor(message, statusCode) {
+        super(message);
+        this.name = "AnansiError";
+        this.statusCode = statusCode;
+    }
+}
+export default AnansiMemory;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "anansi-memory",
+  "version": "0.1.0",
+  "description": "The memory layer for AI apps — persistent, synthesized context for any LLM application",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "tsc"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": ["memory", "llm", "ai", "rag", "context", "vector", "anansi"],
+  "license": "MIT",
+  "author": "Anansi <hello@zazzy.app>",
+  "homepage": "https://zazzy.app",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JibrilSul/zazzy.git",
+    "directory": "packages/sdk"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}