@smara/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,61 @@
+# @smara/mcp-server
+
+MCP server for the [Smara Memory API](https://smara.io) — give any AI app persistent, decay-aware memory.
+
+## Quick Start
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "smara": {
+      "command": "npx",
+      "args": ["-y", "@smara/mcp-server"],
+      "env": {
+        "SMARA_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+Get a free API key at [smara.io](https://smara.io) (10,000 memories, no credit card).
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `store_memory` | Store a fact about a user with importance scoring |
+| `search_memories` | Semantic search with Ebbinghaus decay-aware ranking |
+| `get_user_context` | Pre-formatted context string for LLM system prompts |
+| `delete_memory` | Delete a specific memory |
+| `get_usage` | Check plan limits and memory count |
+
+## How It Works
+
+Smara combines vector similarity search (Voyage AI embeddings) with Ebbinghaus forgetting curves. Memories decay over time — recent, frequently-accessed memories rank higher, just like human recall.
+
+```
+score = similarity × 0.7 + decay_score × 0.3
+```
+
+## Works With
+
+- Claude Desktop
+- Claude Code
+- Cursor
+- Windsurf
+- VS Code (GitHub Copilot)
+- Any MCP-compatible client
+
+## Environment Variables
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `SMARA_API_KEY` | Yes | — |
+| `SMARA_API_URL` | No | `https://api.smara.io` |
+
+## License
+
+MIT

package/build/api-client.d.ts

@@ -0,0 +1 @@
+export declare function smaraFetch(path: string, options?: RequestInit): Promise<unknown>;

package/build/api-client.js

@@ -0,0 +1,19 @@
+const BASE_URL = process.env.SMARA_API_URL || "https://api.smara.io";
+const API_KEY = process.env.SMARA_API_KEY;
+export async function smaraFetch(path, options = {}) {
+    if (!API_KEY)
+        throw new Error("SMARA_API_KEY environment variable is required. Get a free key at https://smara.io");
+    const res = await fetch(`${BASE_URL}${path}`, {
+        ...options,
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            "Content-Type": "application/json",
+            ...options.headers,
+        },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Smara API ${res.status}: ${text}`);
+    }
+    return res.json();
+}

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { smaraFetch } from "./api-client.js";
+const server = new McpServer({
+    name: "smara",
+    version: "1.0.0",
+});
+// ── Store a memory ──────────────────────────────────
+server.registerTool("store_memory", {
+    title: "Store Memory",
+    description: "Store a fact or preference about a user. Smara handles deduplication and contradiction detection automatically. Use importance 0.1-0.3 for trivia, 0.5 for general facts, 0.7-1.0 for critical preferences.",
+    inputSchema: {
+        user_id: z.string().describe("Unique identifier for the user"),
+        fact: z.string().describe("The fact or preference to remember"),
+        importance: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .default(0.5)
+            .describe("Importance score (0-1). Higher = slower decay."),
+    },
+}, async ({ user_id, fact, importance }) => {
+    const data = await smaraFetch("/v1/memories", {
+        method: "POST",
+        body: JSON.stringify({ user_id, fact, importance }),
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ── Search memories ─────────────────────────────────
+server.registerTool("search_memories", {
+    title: "Search Memories",
+    description: "Semantic search across stored memories for a user. Returns results ranked by a blend of vector similarity (70%) and Ebbinghaus decay score (30%). Recent, frequently-accessed memories rank higher.",
+    inputSchema: {
+        user_id: z.string().describe("User to search memories for"),
+        q: z.string().describe("Natural language search query"),
+        limit: z
+            .number()
+            .min(1)
+            .max(50)
+            .optional()
+            .default(5)
+            .describe("Max results to return"),
+    },
+}, async ({ user_id, q, limit }) => {
+    const params = new URLSearchParams({ user_id, q, limit: String(limit) });
+    const data = await smaraFetch(`/v1/memories/search?${params}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ── Get user context ────────────────────────────────
+server.registerTool("get_user_context", {
+    title: "Get User Context",
+    description: "Retrieve a pre-formatted context string for a user, ready to inject into an LLM system prompt. Returns the most relevant memories ranked by decay-aware scoring.",
+    inputSchema: {
+        user_id: z.string().describe("User to get context for"),
+        q: z
+            .string()
+            .optional()
+            .describe("Optional query to focus the context on a topic"),
+        top_n: z
+            .number()
+            .min(1)
+            .max(20)
+            .optional()
+            .default(5)
+            .describe("Number of top memories to include"),
+    },
+}, async ({ user_id, q, top_n }) => {
+    const params = new URLSearchParams({ top_n: String(top_n) });
+    if (q)
+        params.set("q", q);
+    const data = await smaraFetch(`/v1/users/${encodeURIComponent(user_id)}/context?${params}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ── Delete a memory ─────────────────────────────────
+server.registerTool("delete_memory", {
+    title: "Delete Memory",
+    description: "Delete a specific memory by ID. Use when a user asks to forget something.",
+    inputSchema: {
+        id: z.string().describe("The memory ID to delete"),
+    },
+}, async ({ id }) => {
+    await smaraFetch(`/v1/memories/${encodeURIComponent(id)}`, { method: "DELETE" });
+    return { content: [{ type: "text", text: JSON.stringify({ deleted: id }) }] };
+});
+// ── Get usage stats ─────────────────────────────────
+server.registerTool("get_usage", {
+    title: "Get Usage",
+    description: "Check current memory usage — plan, limits, and how many memories are stored. Useful for monitoring quota.",
+    inputSchema: {},
+}, async () => {
+    const data = await smaraFetch("/v1/usage");
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+});
+// ── Start ────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Smara MCP Server running on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@smara/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for Smara Memory API — persistent memory for AI agents",
+  "type": "module",
+  "bin": {
+    "smara-mcp": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod 755 build/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "files": [
+    "build"
+  ],
+  "keywords": [
+    "mcp",
+    "smara",
+    "memory",
+    "ai-agents",
+    "model-context-protocol"
+  ],
+  "author": "parallelromb",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smara-io/mcp-server"
+  },
+  "homepage": "https://smara.io",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.8.0"
+  }
+}