@hilbras/remembra 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to Remembra will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.2.0] — 2026-09-23
+
+### Added
+- HTTP API mode: `remembra --http [--port N]` — same handlers as the MCP tools.
+- Routes: `GET /health`, `POST /memories`, `GET /memories/search`, `GET /memories`,
+  `DELETE /memories/:id`.
+- API-key auth via `REMEMBRA_API_KEY` (`x-api-key` header or `Authorization: Bearer`).
+- `REMEMBRA_PORT` env var as default port.
+- Shared `MemoryService` core used by both MCP and HTTP transports.
+- ChatGPT setup guide with full Custom GPT OpenAPI action schema (`docs/chatgpt.md`).
+- HTTP and service test suites.
+
 ## [0.1.0] — 2026-09-23
 
 ### Added

package/README.md

@@ -16,7 +16,7 @@ One memory server, many clients:
 | Claude Code | MCP (stdio) |
 | Cline | MCP (stdio) |
 | Kimi Code | MCP (stdio) |
-| ChatGPT | HTTP API + Custom GPT action *(v1.5)* |
+| ChatGPT | HTTP API + Custom GPT action ✅ |
 
 ## The problem
 
@@ -73,6 +73,27 @@ claude mcp add remembra -- remembra
 
 More clients (Cline, Kimi Code) in **[docs/clients.md](docs/clients.md)**.
 
+### ChatGPT (HTTP mode)
+
+```bash
+REMEMBRA_API_KEY="your-secret" remembra --http --port 8787
+```
+
+Then wire a Custom GPT to the API — full walkthrough in **[docs/chatgpt.md](docs/chatgpt.md)**.
+
+### HTTP API
+
+| Method | Route | Purpose |
+|--------|-------|---------|
+| GET | `/health` | Liveness (no auth) |
+| POST | `/memories` | Store a memory |
+| GET | `/memories/search?query=&scope=` | Search |
+| GET | `/memories?scope=&type=` | List |
+| DELETE | `/memories/:id` | Forget |
+
+All routes except `/health` require `x-api-key` (or `Authorization: Bearer`) when
+`REMEMBRA_API_KEY` is set.
+
 ## Tools
 
 | Tool | Purpose |
@@ -91,6 +112,7 @@ Full reference: **[docs/tools.md](docs/tools.md)**
 | [Memory model](docs/memory-model.md) | Types, scopes, ranking, storage format |
 | [Tool reference](docs/tools.md) | Every MCP tool with arguments |
 | [Client setup](docs/clients.md) | Config for each supported tool |
+| [ChatGPT setup](docs/chatgpt.md) | HTTP API + Custom GPT walkthrough |
 | [Contributing](CONTRIBUTING.md) | Dev workflow and guidelines |
 | [Changelog](CHANGELOG.md) | Release history |
 
@@ -119,8 +141,8 @@ npm test        # run tests
 
 ## Roadmap
 
-- **v1** *(current)* — MCP server for coding tools, file storage, layered retrieval
-- **v1.5** — HTTP API + ChatGPT Custom GPT action
+- **v1** — MCP server for coding tools, file storage, layered retrieval ✅
+- **v1.5** *(current)* — HTTP API + ChatGPT Custom GPT action ✅
 - **v2** — automatic session-digest extraction, embeddings behind `memory_search`
 - **v3** — SQLite for scale, duplicate merging, memory decay
 

package/dist/http.d.ts

@@ -0,0 +1,19 @@
+import http from "node:http";
+import { MemoryService } from "./service.js";
+interface HttpOptions {
+    port?: number;
+    /** If set, all endpoints except GET /health require `x-api-key` or `Authorization: Bearer`. */
+    apiKey?: string;
+}
+/**
+ * Minimal HTTP API over the same handlers the MCP tools use.
+ *
+ * Routes:
+ *   GET    /health              → liveness (no auth)
+ *   POST   /memories            → store a memory
+ *   GET    /memories/search     → ?query=&scope=&type=&limit=
+ *   GET    /memories            → ?scope=&type=
+ *   DELETE /memories/:id        → forget
+ */
+export declare function createHttpServer(service: MemoryService, opts?: HttpOptions): http.Server;
+export {};

package/dist/http.js

@@ -0,0 +1,101 @@
+import http from "node:http";
+/**
+ * Minimal HTTP API over the same handlers the MCP tools use.
+ *
+ * Routes:
+ *   GET    /health              → liveness (no auth)
+ *   POST   /memories            → store a memory
+ *   GET    /memories/search     → ?query=&scope=&type=&limit=
+ *   GET    /memories            → ?scope=&type=
+ *   DELETE /memories/:id        → forget
+ */
+export function createHttpServer(service, opts = {}) {
+    const server = http.createServer(async (req, res) => {
+        try {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            const path = url.pathname.replace(/\/+$/, "") || "/";
+            if (path === "/health") {
+                return send(res, 200, { status: "ok" });
+            }
+            if (opts.apiKey && !authorized(req, opts.apiKey)) {
+                return send(res, 401, { error: "Unauthorized: missing or invalid API key" });
+            }
+            // POST /memories
+            if (req.method === "POST" && path === "/memories") {
+                const body = await readBody(req);
+                const result = await service.store(body);
+                return send(res, 201, result);
+            }
+            // GET /memories/search
+            if (req.method === "GET" && path === "/memories/search") {
+                const result = await service.search({
+                    query: url.searchParams.get("query") ?? url.searchParams.get("q") ?? undefined,
+                    scope: url.searchParams.get("scope") ?? undefined,
+                    type: url.searchParams.get("type") ?? undefined,
+                    limit: url.searchParams.get("limit") ? Number(url.searchParams.get("limit")) : undefined,
+                });
+                return send(res, 200, result);
+            }
+            // GET /memories
+            if (req.method === "GET" && path === "/memories") {
+                const result = await service.list({
+                    scope: url.searchParams.get("scope") ?? undefined,
+                    type: url.searchParams.get("type") ?? undefined,
+                });
+                return send(res, 200, result);
+            }
+            // DELETE /memories/:id
+            const del = path.match(/^\/memories\/([^/]+)$/);
+            if (req.method === "DELETE" && del) {
+                const result = await service.forget(decodeURIComponent(del[1]));
+                return send(res, result.ok ? 200 : 404, result);
+            }
+            send(res, 404, { error: `No route: ${req.method} ${path}` });
+        }
+        catch (err) {
+            const name = err.name;
+            const isClientError = name === "ZodError" || name === "BadRequestError";
+            send(res, isClientError ? 400 : 500, {
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    });
+    const port = opts.port ?? Number(process.env.REMEMBRA_PORT ?? 8787);
+    server.listen(port, () => {
+        console.error(`Remembra HTTP API listening on :${port}${opts.apiKey ? " (auth required)" : " (no auth!)"}`);
+    });
+    return server;
+}
+function authorized(req, key) {
+    const header = req.headers["x-api-key"];
+    const auth = req.headers.authorization;
+    const provided = (typeof header === "string" ? header : undefined) ??
+        (auth?.startsWith("Bearer ") ? auth.slice(7) : undefined);
+    return provided === key;
+}
+function send(res, status, body) {
+    const data = JSON.stringify(body, null, 2);
+    res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+    res.end(data);
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => {
+            const raw = Buffer.concat(chunks).toString("utf8");
+            if (!raw)
+                return resolve({});
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch {
+                const e = new Error("Invalid JSON body");
+                e.name = "BadRequestError";
+                reject(e);
+            }
+        });
+        req.on("error", reject);
+    });
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

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

package/dist/index.js

@@ -3,80 +3,84 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { MemoryStore } from "./store.js";
-import { search } from "./retrieval.js";
-import { StoreInput } from "./types.js";
+import { MemoryService } from "./service.js";
+import { createHttpServer } from "./http.js";
 const store = new MemoryStore(MemoryStore.defaultRoot());
-const server = new McpServer({ name: "remembra", version: "0.1.0" });
-server.registerTool("memory_store", {
-    title: "Store a memory",
-    description: "Persist a fact, decision, role or history entry so it survives context window resets. " +
-        "Use type 'fact' for stable knowledge, 'decision' for choices already made, " +
-        "'role' for standing instructions/roles, 'history' for condensed chronology of past work.",
-    inputSchema: {
-        type: z.enum(["fact", "decision", "role", "history"]),
-        content: z.string().describe("The memory itself, written as a standalone statement"),
-        scope: z
-            .string()
-            .optional()
-            .describe("'global' for always-relevant memories, or a project path/id for project-scoped ones"),
-        tags: z.array(z.string()).optional(),
-        importance: z.number().int().min(1).max(5).optional().describe("1=minor, 5=critical (default 3)"),
-        source: z.string().optional().describe("Originating session or client"),
-    },
-}, async ({ type, content, scope, tags, importance, source }) => {
-    const memory = await store.store(StoreInput.parse({ type, content, scope, tags, importance, source }));
-    return { content: [{ type: "text", text: `Stored ${memory.type} memory ${memory.id} (scope: ${memory.scope})` }] };
-});
-server.registerTool("memory_search", {
-    title: "Search memories",
-    description: "Retrieve relevant memories from external storage. Call this at the start of a session " +
-        "(or whenever prior context might exist) to recover facts, decisions, roles and history.",
-    inputSchema: {
-        query: z.string().optional().describe("Keywords to match (omit to get a scope/recency-ranked list)"),
-        scope: z.string().optional().describe("Current project path or workspace id to filter by"),
-        type: z.enum(["fact", "decision", "role", "history"]).optional(),
-        limit: z.number().int().min(1).max(50).optional(),
-    },
-}, async ({ query, scope, type, limit }) => {
-    const results = search(await store.all(), { query, scope, type, limit });
-    const text = results.length === 0
-        ? "No matching memories."
-        : results
-            .map((m) => `[${m.id}] ${m.type.toUpperCase()} (scope: ${m.scope}, importance: ${m.importance}, ${m.updatedAt.slice(0, 10)})\n${m.content}`)
-            .join("\n\n");
-    return { content: [{ type: "text", text }] };
-});
-server.registerTool("memory_list", {
-    title: "List memories",
-    description: "List stored memories, optionally filtered by scope or type.",
-    inputSchema: {
-        scope: z.string().optional(),
-        type: z.enum(["fact", "decision", "role", "history"]).optional(),
-    },
-}, async ({ scope, type }) => {
-    let memories = await store.all();
-    if (scope)
-        memories = memories.filter((m) => m.scope === scope || m.scope === "global");
-    if (type)
-        memories = memories.filter((m) => m.type === type);
-    memories.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
-    const text = memories.length === 0
-        ? "No memories stored yet."
-        : memories.map((m) => `[${m.id}] ${m.type} (${m.scope}): ${m.content.split("\n")[0]}`).join("\n");
-    return { content: [{ type: "text", text }] };
-});
-server.registerTool("memory_forget", {
-    title: "Delete a memory",
-    description: "Permanently delete a memory by its id.",
-    inputSchema: { id: z.string() },
-}, async ({ id }) => {
-    const ok = await store.forget(id);
-    return {
-        content: [{ type: "text", text: ok ? `Deleted memory ${id}.` : `No memory with id ${id}.` }],
-        isError: !ok,
-    };
-});
-const transport = new StdioServerTransport();
-await server.connect(transport);
-console.error(`Remembra memory server running (root: ${MemoryStore.defaultRoot()})`);
+const service = new MemoryService(store);
+const httpFlag = process.argv.includes("--http");
+const portArg = process.argv.indexOf("--port");
+const port = portArg !== -1 ? Number(process.argv[portArg + 1]) : undefined;
+if (httpFlag) {
+    // HTTP mode: long-running API for non-MCP clients (ChatGPT, scripts, ...).
+    createHttpServer(service, {
+        port,
+        apiKey: process.env.REMEMBRA_API_KEY,
+    });
+}
+else {
+    // MCP mode (default): stdio transport launched by an MCP client.
+    await startMcp();
+}
+async function startMcp() {
+    const server = new McpServer({ name: "remembra", version: "0.2.0" });
+    server.registerTool("memory_store", {
+        title: "Store a memory",
+        description: "Persist a fact, decision, role or history entry so it survives context window resets. " +
+            "Use type 'fact' for stable knowledge, 'decision' for choices already made, " +
+            "'role' for standing instructions/roles, 'history' for condensed chronology of past work.",
+        inputSchema: {
+            type: z.enum(["fact", "decision", "role", "history"]),
+            content: z.string().describe("The memory itself, written as a standalone statement"),
+            scope: z
+                .string()
+                .optional()
+                .describe("'global' for always-relevant memories, or a project path/id for project-scoped ones"),
+            tags: z.array(z.string()).optional(),
+            importance: z.number().int().min(1).max(5).optional().describe("1=minor, 5=critical (default 3)"),
+            source: z.string().optional().describe("Originating session or client"),
+        },
+    }, async (args) => {
+        const result = await service.store(args);
+        return { content: [{ type: "text", text: result.message }] };
+    });
+    server.registerTool("memory_search", {
+        title: "Search memories",
+        description: "Retrieve relevant memories from external storage. Call this at the start of a session " +
+            "(or whenever prior context might exist) to recover facts, decisions, roles and history.",
+        inputSchema: {
+            query: z.string().optional().describe("Keywords to match (omit to get a scope/recency-ranked list)"),
+            scope: z.string().optional().describe("Current project path or workspace id to filter by"),
+            type: z.enum(["fact", "decision", "role", "history"]).optional(),
+            limit: z.number().int().min(1).max(50).optional(),
+        },
+    }, async (args) => {
+        const result = await service.search(args);
+        return { content: [{ type: "text", text: result.text }] };
+    });
+    server.registerTool("memory_list", {
+        title: "List memories",
+        description: "List stored memories, optionally filtered by scope or type.",
+        inputSchema: {
+            scope: z.string().optional(),
+            type: z.enum(["fact", "decision", "role", "history"]).optional(),
+        },
+    }, async (args) => {
+        const result = await service.list(args);
+        return { content: [{ type: "text", text: result.text }] };
+    });
+    server.registerTool("memory_forget", {
+        title: "Delete a memory",
+        description: "Permanently delete a memory by its id.",
+        inputSchema: { id: z.string() },
+    }, async ({ id }) => {
+        const result = await service.forget(id);
+        return {
+            content: [{ type: "text", text: result.text }],
+            isError: !result.ok,
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`Remembra MCP server running (root: ${MemoryStore.defaultRoot()})`);
+}
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/service.d.ts

@@ -0,0 +1,35 @@
+import { MemoryStore } from "./store.js";
+import { MemoryType } from "./types.js";
+/**
+ * Transport-agnostic handlers. Both the MCP tools and the HTTP API
+ * call into this module, so behavior is guaranteed to match.
+ */
+export declare class MemoryService {
+    readonly db: MemoryStore;
+    constructor(db: MemoryStore);
+    store(input: unknown): Promise<{
+        id: string;
+        message: string;
+        memory: import("./types.js").Memory;
+    }>;
+    search(q: {
+        query?: string;
+        scope?: string;
+        type?: MemoryType;
+        limit?: number;
+    }): Promise<{
+        text: string;
+        results: import("./types.js").Memory[];
+    }>;
+    list(q: {
+        scope?: string;
+        type?: MemoryType;
+    }): Promise<{
+        text: string;
+        memories: import("./types.js").Memory[];
+    }>;
+    forget(id: string): Promise<{
+        ok: boolean;
+        text: string;
+    }>;
+}

package/dist/service.js

@@ -0,0 +1,46 @@
+import { search } from "./retrieval.js";
+import { StoreInput } from "./types.js";
+/**
+ * Transport-agnostic handlers. Both the MCP tools and the HTTP API
+ * call into this module, so behavior is guaranteed to match.
+ */
+export class MemoryService {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async store(input) {
+        const memory = await this.db.store(StoreInput.parse(input));
+        return {
+            id: memory.id,
+            message: `Stored ${memory.type} memory ${memory.id} (scope: ${memory.scope})`,
+            memory,
+        };
+    }
+    async search(q) {
+        const results = search(await this.db.all(), q);
+        const text = results.length === 0
+            ? "No matching memories."
+            : results
+                .map((m) => `[${m.id}] ${m.type.toUpperCase()} (scope: ${m.scope}, importance: ${m.importance}, ${m.updatedAt.slice(0, 10)})\n${m.content}`)
+                .join("\n\n");
+        return { text, results };
+    }
+    async list(q) {
+        let memories = await this.db.all();
+        if (q.scope)
+            memories = memories.filter((m) => m.scope === q.scope || m.scope === "global");
+        if (q.type)
+            memories = memories.filter((m) => m.type === q.type);
+        memories.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+        const text = memories.length === 0
+            ? "No memories stored yet."
+            : memories.map((m) => `[${m.id}] ${m.type} (${m.scope}): ${m.content.split("\n")[0]}`).join("\n");
+        return { text, memories };
+    }
+    async forget(id) {
+        const ok = await this.db.forget(id);
+        return { ok, text: ok ? `Deleted memory ${id}.` : `No memory with id ${id}.` };
+    }
+}
+//# sourceMappingURL=service.js.map

package/dist/service.js.map

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

package/docs/chatgpt.md

@@ -0,0 +1,189 @@
+# ChatGPT Setup (v1.5)
+
+ChatGPT doesn't speak MCP, so Remembra exposes the same memory handlers over a plain
+HTTP API. You connect it by creating a **Custom GPT** with API actions.
+
+## 1. Start the HTTP server
+
+```bash
+export REMEMBRA_API_KEY="pick-a-long-random-secret"
+remembra --http --port 8787
+# or, from source:
+node dist/index.js --http --port 8787
+```
+
+Check it's up:
+
+```bash
+curl http://localhost:8787/health
+# {"status": "ok"}
+```
+
+- `REMEMBRA_API_KEY` **strongly recommended** — without it every endpoint is open.
+- The server binds to localhost by default. For ChatGPT to reach it you must expose it
+  publicly (see [§4](#4-exposing-the-server)).
+
+## 2. HTTP API reference
+
+All endpoints except `/health` require the key via `x-api-key` or `Authorization: Bearer`.
+
+### Store a memory
+
+```bash
+curl -X POST http://localhost:8787/memories \
+  -H "content-type: application/json" \
+  -H "x-api-key: $REMEMBRA_API_KEY" \
+  -d '{
+    "type": "decision",
+    "content": "Chose monthly billing over annual",
+    "scope": "global",
+    "tags": ["pricing"],
+    "importance": 4
+  }'
+```
+
+### Search memories
+
+```bash
+curl "http://localhost:8787/memories/search?query=billing&scope=global&limit=5" \
+  -H "x-api-key: $REMEMBRA_API_KEY"
+```
+
+| Query param | Description |
+|-------------|-------------|
+| `query` (or `q`) | keywords to match |
+| `scope` | project/workspace filter |
+| `type` | `fact` \| `decision` \| `role` \| `history` |
+| `limit` | max results (default 10) |
+
+### List memories
+
+```bash
+curl "http://localhost:8787/memories?scope=global&type=role" \
+  -H "x-api-key: $REMEMBRA_API_KEY"
+```
+
+### Delete a memory
+
+```bash
+curl -X DELETE http://localhost:8787/memories/<id> \
+  -H "x-api-key: $REMEMBRA_API_KEY"
+```
+
+## 3. Create the Custom GPT
+
+1. Go to **chatgpt.com → Explore GPTs → Create a GPT**.
+2. **Name**: Remembra (or whatever you like).
+3. **Instructions** — paste this:
+
+   > You have long-term memory powered by Remembra. At the start of every conversation,
+   > call `search_memories` with no query to load your roles, facts and decisions.
+   > Whenever the user tells you something worth remembering (a fact, a decision,
+   > their role or preferences) or a decision is made, call `store_memory`.
+   > Scope for this chat is `chatgpt` unless the user is discussing a specific project.
+   > If the model asks you to forget something, call `delete_memory` with its id.
+
+4. **Capabilities** → enable **Actions**.
+5. Under **Actions → Create new action**, paste this schema (fill in your domain and key):
+
+```json
+{
+  "openapi": "3.1.0",
+  "info": { "title": "Remembra Memory", "version": "1.0.0" },
+  "servers": [{ "url": "https://YOUR-DOMAIN.example" }],
+  "paths": {
+    "/memories": {
+      "post": {
+        "operationId": "store_memory",
+        "summary": "Store a fact, decision, role or history",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": ["type", "content"],
+                "properties": {
+                  "type": { "type": "string", "enum": ["fact", "decision", "role", "history"] },
+                  "content": { "type": "string", "description": "Standalone statement" },
+                  "scope": { "type": "string", "default": "global" },
+                  "tags": { "type": "array", "items": { "type": "string" } },
+                  "importance": { "type": "integer", "minimum": 1, "maximum": 5 }
+                }
+              }
+            }
+          }
+        },
+        "responses": { "201": { "description": "Stored" } }
+      },
+      "get": {
+        "operationId": "list_memories",
+        "summary": "List stored memories",
+        "parameters": [
+          { "name": "scope", "in": "query", "schema": { "type": "string" } },
+          { "name": "type", "in": "query", "schema": { "type": "string" } }
+        ],
+        "responses": { "200": { "description": "OK" } }
+      }
+    },
+    "/memories/search": {
+      "get": {
+        "operationId": "search_memories",
+        "summary": "Search memories",
+        "parameters": [
+          { "name": "query", "in": "query", "schema": { "type": "string" } },
+          { "name": "scope", "in": "query", "schema": { "type": "string" } },
+          { "name": "type", "in": "query", "schema": { "type": "string" } },
+          { "name": "limit", "in": "query", "schema": { "type": "integer" } }
+        ],
+        "responses": { "200": { "description": "OK" } }
+      }
+    },
+    "/memories/{id}": {
+      "delete": {
+        "operationId": "delete_memory",
+        "summary": "Delete a memory by id",
+        "parameters": [
+          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
+        ],
+        "responses": { "200": { "description": "Deleted" } }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "apiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" }
+    }
+  },
+  "security": [{ "apiKeyAuth": [] }]
+}
+```
+
+6. In **Authentication**, choose **API Key → Custom → Header → `x-api-key`**, and paste
+   your `REMEMBRA_API_KEY`.
+7. **Save** (Only me / Anyone, your choice) and test:
+
+   > *"Remember that I prefer metric units."* → the GPT should call `store_memory`.
+   > Then in a **new chat**: *"What units do I prefer?"* → it calls `search_memories`
+   > and answers. That's the whole point of Remembra — the memory survived the
+   > context reset.
+
+## 4. Exposing the server
+
+ChatGPT must reach your server over HTTPS. Options, easiest first:
+
+| Approach | Notes |
+|----------|-------|
+| **Cloud VM / VPS** | Run `remembra --http` behind nginx/Caddy with TLS. Simplest for a personal server. |
+| **Tunnel** | `cloudflared tunnel` or `ngrok http 8787` — quick HTTPS URL for testing. |
+| **Serverless** | Port `service.ts` handlers to a Lambda/Cloudflare Worker (v2 territory). |
+
+> ⚠️ Always set `REMEMBRA_API_KEY` when the server is reachable from the internet,
+> and prefer a tunnel with access restrictions while testing.
+
+## 5. Sharing memory with your coding tools
+
+Because both transports use the same storage (`~/.remembra`), memories written by
+ChatGPT appear in OpenCode/Claude Code and vice versa — just point both at the same
+`REMEMBRA_HOME`. Use scope `chatgpt` for chat-specific memories and `global` for
+anything that should follow you everywhere.

package/docs/clients.md

@@ -71,14 +71,21 @@ Add to the MCP config file used by Kimi CLI:
 
 ## ChatGPT
 
-*Planned for v1.5* — an HTTP layer exposing the same handlers, wired to a
-Custom GPT action with API-key auth.
+Uses the HTTP mode instead of MCP — see the full walkthrough in
+**[chatgpt.md](chatgpt.md)** (server start, API reference, Custom GPT action schema,
+tunneling options).
+
+```bash
+REMEMBRA_API_KEY="your-secret" remembra --http
+```
 
 ## Environment
 
 | Variable | Default | Purpose |
 |----------|---------|---------|
 | `REMEMBRA_HOME` | `~/.remembra` | Where memory files live |
+| `REMEMBRA_API_KEY` | *(unset)* | Enables auth on the HTTP API |
+| `REMEMBRA_PORT` | `8787` | HTTP API port (`--port` overrides) |
 
 ## Tips
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hilbras/remembra",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "External memory for AI assistants — remember facts, decisions, roles and history across sessions. MCP server for OpenCode, Claude Code, Cline, Kimi Code and more.",
   "type": "module",
   "bin": {