@hilbras/remembra 0.1.0 → 0.3.0

package/docs/chatgpt.md

@@ -0,0 +1,200 @@
+# 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"
+```
+
+### Digest a session (LLM extraction)
+
+```bash
+curl -X POST http://localhost:8787/memories/digest \
+  -H "content-type: application/json" \
+  -H "x-api-key: $REMEMBRA_API_KEY" \
+  -d '{"transcript":"<conversation text>","scope":"chatgpt"}'
+```
+
+Requires `REMEMBRA_LLM` + key — see [providers.md](providers.md).
+
+## 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,25 @@ 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) |
+| `REMEMBRA_LLM` | `openai` | Digest LLM: `openai` \| `anthropic` \| `ollama` |
+| `REMEMBRA_EMBEDDINGS` | `none` | Semantic search: `openai` \| `ollama` \| `none` |
+
+LLM/embedding key setup: see **[providers.md](providers.md)**.
 
 ## Tips
 

package/docs/providers.md

@@ -0,0 +1,107 @@
+# AI Providers & Session Digest (v2)
+
+Remembra can call an LLM to extract memories automatically (**session digest**)
+and use embeddings for semantic search. Both are pluggable and off-by-default
+where possible, so a plain keyword install still works with zero API keys.
+
+## Configuration
+
+| Variable | Values | Default | Purpose |
+|----------|--------|---------|---------|
+| `REMEMBRA_LLM` | `openai` \| `anthropic` \| `ollama` | `openai` | Which LLM does digest extraction |
+| `REMEMBRA_LLM_MODEL` | provider model id | provider default | Override the extraction model |
+| `REMEMBRA_EMBEDDINGS` | `openai` \| `ollama` \| `none` | `none` | Semantic search provider |
+| `REMEMBRA_EMBEDDING_MODEL` | provider model id | provider default | Override the embedding model |
+| `OPENAI_API_KEY` | — | — | Required when provider = openai |
+| `ANTHROPIC_API_KEY` | — | — | Required when provider = anthropic |
+| `OLLAMA_HOST` | URL | `http://localhost:11434` | Ollama endpoint (LLM and/or embeddings) |
+
+### Examples
+
+```bash
+# OpenAI for both (simplest hosted setup)
+export OPENAI_API_KEY=sk-...
+export REMEMBRA_LLM=openai
+export REMEMBRA_EMBEDDINGS=openai
+
+# Fully local with Ollama — no API keys
+export REMEMBRA_LLM=ollama
+export REMEMBRA_LLM_MODEL=llama3.2
+export REMEMBRA_EMBEDDINGS=ollama
+export REMEMBRA_EMBEDDING_MODEL=nomic-embed-text
+
+# Anthropic for extraction, semantic search off (keyword mode)
+export ANTHROPIC_API_KEY=sk-ant-...
+export REMEMBRA_LLM=anthropic
+```
+
+## Session digest
+
+Instead of the model remembering to call `memory_store` for every little thing,
+hand the whole conversation to one tool at the end of a session:
+
+```
+memory_digest {
+  transcript: "<full transcript or a detailed summary>",
+  scope: "/path/to/project",   // optional, default global
+  source: "opencode"            // optional
+}
+```
+
+Remembra asks the configured LLM to extract **facts, decisions, roles, and
+history**, then stores each one — **skipping exact duplicates** that are
+already present (normalized by type + scope + content). Running a digest twice
+over the same conversation is a no-op.
+
+HTTP equivalent:
+
+```bash
+curl -X POST http://localhost:8787/memories/digest \
+  -H "content-type: application/json" \
+  -H "x-api-key: $REMEMBRA_API_KEY" \
+  -d '{"transcript":"...","scope":"chatgpt","source":"chatgpt"}'
+```
+
+Response:
+
+```json
+{
+  "extracted": 4,
+  "stored": [ ... ],
+  "skippedDuplicates": 2,
+  "ids": ["a1b2c3d4", "..."]
+}
+```
+
+> **Note:** the digest LLM key is only needed when you actually call
+> `memory_digest` — storage and search work without it.
+
+## Semantic search
+
+With `REMEMBRA_EMBEDDINGS=openai|ollama`:
+
+- **On write**: every stored memory gets an embedding, cached in its
+  frontmatter (`embedding: [...]`) — computed once, never re-embedded.
+- **On search**: the query is embedded and **cosine similarity becomes the
+  primary ranking signal**. Importance and recency remain small modifiers.
+- **Gates stay absolute**: `role` memories always surface, and memories from
+  other scopes are never returned, no matter how similar.
+- **Memories without vectors** (stored while embeddings were off) fall back
+  to keyword matching.
+
+With `REMEMBRA_EMBEDDINGS=none` (default): pure keyword scoring — exactly
+the v1 behavior.
+
+### Backfilling vectors
+
+Memories stored before you enabled embeddings have no vectors. They still
+work (keyword fallback), but to bring them into semantic search, re-store
+them or wait for v3's maintenance commands.
+
+## Failure behavior
+
+- **Embedding API fails** → warning logged, write continues without a vector,
+  search degrades to keywords. Never blocks storing.
+- **LLM call fails** → `memory_digest` returns the error; nothing is stored.
+- **No keys configured** → MCP/HTTP servers run normally; only `memory_digest`
+  errors if invoked.

package/docs/tools.md

@@ -64,12 +64,26 @@ Permanently delete a memory.
 
 Returns an error result if no memory matches the id.
 
+## `memory_digest`
+
+Extract memories from a conversation transcript using the configured LLM and
+store them, skipping exact duplicates. See [providers.md](providers.md).
+
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| `transcript` | string | ✅ | Full transcript or a detailed session summary |
+| `scope` | string | no | Scope for extracted memories (default `global`) |
+| `source` | string | no | Originating session/client |
+
+Requires `REMEMBRA_LLM` + its API key (or Ollama). Returns counts:
+extracted / stored / duplicates skipped, plus stored ids.
+
 ---
 
 ## Suggested session flow
 
 ```
-1. memory_search { scope: <current project> }     → recover roles, facts, decisions
+1. memory_search { scope: <current project> }   → recover roles, facts, decisions
 2. ... work happens; model calls memory_store when something worth keeping emerges ...
-3. (v2) automatic session digest sweeps anything missed
+3. memory_digest { transcript, scope }           → end-of-session sweep (v2, LLM extracts)
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hilbras/remembra",
-  "version": "0.1.0",
+  "version": "0.3.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": {