kimiflare 0.21.0 → 0.23.0

package/README.md

@@ -16,6 +16,11 @@
   Moonshot's 1T-parameter open-source model, running directly on your Cloudflare account.
 </p>
 
+> 💸 **Heads up — this runs on your Cloudflare account.**
+> We recommend setting a [budget cap](https://developers.cloudflare.com/workers-ai/platform/pricing/) on Workers AI and checking your [Cloudflare billing](https://dash.cloudflare.com/) regularly while using KimiFlare.
+>
+> 🚀 **Stay up to date.** Newer versions are significantly more token-efficient and cheaper to run. Run `/update` inside KimiFlare or `npm update -g kimiflare` to get the latest release.
+
 <p align="center">
   <img src="docs/screenshot.png" alt="kimiflare TUI" width="900">
 </p>
@@ -24,7 +29,7 @@
 
 - **262k context window** — Read entire modules, large configs, and full stack traces without the model losing track.
 - **Image understanding** — Drop image paths into your prompt (PNG, JPG, WebP, GIF, BMP). The model sees them inline — great for UI reviews, diagrams, screenshots, and mockups.
-- **Direct to Cloudflare** — No AI Gateway, no proxy, no OpenAI SDK. Your traffic goes straight to Workers AI from your account.
+- **Direct by default** — No proxy, no OpenAI SDK. Your traffic goes straight to Workers AI from your account, with optional AI Gateway routing for user-owned logging, caching, and analytics.
 - **Plan mode** — Ask the agent to research and produce a plan without touching your filesystem. Review it, then exit plan mode to execute.
 
 ## Quick start
@@ -57,11 +62,13 @@ Requires Node.js ≥ 20.
 | **Streaming reasoning** | Toggle the model's chain-of-thought with `/reasoning` or `Ctrl-R`. See how it thinks in real time. |
 | **Image understanding** | Drop image paths (PNG, JPG, WebP, GIF, BMP up to 5 MB) into any prompt. The model sees them inline — perfect for UI reviews, diagrams, and screenshots. |
 | **Live cost tracking** | Status bar shows real-time cost based on Cloudflare pricing: `$0.95/M input`, `$0.16/M cached`, `$4.00/M output`. |
+| **Optional AI Gateway** | Route Workers AI traffic through your own Cloudflare AI Gateway for request logs, cache status, and analytics while keeping your API token local. |
 | **Session persistence** | Every turn is auto-saved. `/resume` lists past sessions (with message counts) in a paginated picker. |
 | **Smart permissions** | Bash session-allow is keyed by the first token (e.g., allow all `git` commands). Write/edit show a unified diff before you approve. |
 | **Project context (`/init`)** | Scans your repo and writes a concise `KIMI.md` — build commands, layout, conventions. Auto-loaded on every launch. |
 | **MCP server integration** | Plug in external tools via the Model Context Protocol — local stdio servers or remote SSE endpoints. GitHub, Sentry, docs search, databases, etc. |
 | **Co-author auto-append** | Detects `git commit` commands and auto-injects `Co-authored-by: kimiflare <kimiflare@proton.me>`. |
+| **Local structured memory** | SQLite + embeddings cross-session memory. Extracts facts, instructions, and preferences at compaction time; recalls them via hybrid search (FTS5 + vector + exact) in future sessions. Team-shareable via `.kimiflare/memory.db`. |
 | **Resilient transport** | Retries Cloudflare capacity errors (code 3040) and 5xx with exponential backoff up to 5 attempts. |
 
 ## Configure
@@ -76,6 +83,13 @@ Then either export them each shell:
 ```sh
 export CLOUDFLARE_ACCOUNT_ID=...
 export CLOUDFLARE_API_TOKEN=...
+# Optional: route through a Cloudflare AI Gateway you own
+export KIMIFLARE_AI_GATEWAY_ID=...
+# Optional: enable local structured memory
+export KIMIFLARE_MEMORY_ENABLED=1
+export KIMIFLARE_MEMORY_DB_PATH=.kimiflare/memory.db
+export KIMIFLARE_MEMORY_MAX_AGE_DAYS=90
+export KIMIFLARE_MEMORY_MAX_ENTRIES=1000
 ```
 
 or save them once (`chmod 600` automatically):
@@ -86,12 +100,36 @@ cat > ~/.config/kimiflare/config.json <<'EOF'
 {
   "accountId": "YOUR_ACCOUNT_ID",
   "apiToken":  "YOUR_API_TOKEN",
-  "model":     "@cf/moonshotai/kimi-k2.6"
+  "model":     "@cf/moonshotai/kimi-k2.6",
+  "aiGatewayId": "YOUR_GATEWAY_NAME"
 }
 EOF
 chmod 600 ~/.config/kimiflare/config.json
 ```
 
+### Optional AI Gateway
+
+kimiflare talks directly to Workers AI unless `aiGatewayId` is configured. When set, chat completions are sent to Cloudflare's native Workers AI Gateway endpoint:
+
+```text
+https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/workers-ai/{model_id}
+```
+
+Create a gateway in the Cloudflare dashboard under **AI > AI Gateway**, then set `aiGatewayId` in `~/.config/kimiflare/config.json` or export `KIMIFLARE_AI_GATEWAY_ID`. The same Workers AI API token stays on your machine and is sent to Cloudflare.
+
+Optional per-request controls:
+
+```json
+{
+  "aiGatewayCacheTtl": 3600,
+  "aiGatewaySkipCache": false,
+  "aiGatewayCollectLogPayload": false,
+  "aiGatewayMetadata": { "tool": "kimiflare" }
+}
+```
+
+`cf-aig-cache-status` from AI Gateway is shown separately from Workers AI prompt-token caching (`cached_tokens`). If you enable gateway logs, kimiflare records metadata such as log id, cache hit/miss, tokens, duration, and status when Cloudflare returns it; prompt and response bodies are not stored by kimiflare.
+
 ## MCP servers (Model Context Protocol)
 
 kimiflare supports external tools via MCP. Add servers to your `~/.config/kimiflare/config.json`:
@@ -132,6 +170,43 @@ MCP tools appear prefixed as `mcp_<server>_<tool>` alongside built-in tools.
 - `/mcp list` — show connected servers and tool counts
 - `/mcp reload` — disconnect and reconnect all configured servers
 
+## Local structured memory
+
+kimiflare can remember facts, instructions, and preferences across sessions using a local SQLite database with vector search.
+
+**How it works:**
+- At compaction time, the agent extracts structured memories from the conversation
+- Memories are stored with embeddings (`@cf/baai/bge-base-en-v1.5`) in a local SQLite database
+- On future sessions, relevant memories are recalled via hybrid search (FTS5 full-text + vector similarity + exact file-path matching)
+- Supports team-shared memory: `.kimiflare/memory.db` in your repo root (add to `.gitignore`)
+
+**Enable:**
+```sh
+export KIMIFLARE_MEMORY_ENABLED=1
+```
+
+Or in `~/.config/kimiflare/config.json`:
+```json
+{
+  "memoryEnabled": true,
+  "memoryDbPath": ".kimiflare/memory.db",
+  "memoryMaxAgeDays": 90,
+  "memoryMaxEntries": 1000,
+  "memoryEmbeddingModel": "@cf/baai/bge-base-en-v1.5"
+}
+```
+
+**Commands:**
+- `/memory` — show memory stats (total count, DB size, by category)
+- `/memory search <query>` — manual hybrid search over stored memories
+- `/memory clear` — wipe all memories for the current repo
+
+**Storage & cleanup:**
+- Default retention: 90 days, 1000 memories per repo
+- Automatic deduplication of near-identical memories
+- Cleanup runs on startup and after every compaction
+- Typical size: ~4–5 KB per memory; ~15 MB/month under heavy use
+
 ## Usage
 
 ### Interactive TUI
@@ -183,8 +258,11 @@ Supported formats: PNG, JPG, JPEG, WebP, GIF, BMP (up to 5 MB each, 10 per messa
 | `/theme` | Interactive theme picker with live preview (`Ctrl+T`). Saved to config. |
 | `/theme NAME` | Set theme by name directly. |
 | `/resume` | Pick a past conversation to restore. |
-| `/compact` | Summarize older turns to free context. Suggested automatically at ~80% full. |
+| `/compact` | Summarize older turns to free context. Suggested automatically at ~80% full. Extracts memories if memory is enabled. |
 | `/init` | Scan the repo and write a `KIMI.md` so future agents have project context. |
+| `/memory` | Show memory stats (total count, DB size, by category). |
+| `/memory search <query>` | Search stored memories manually. |
+| `/memory clear` | Wipe all memories for the current repo. |
 | `/mcp list` | List connected MCP servers and their tools. |
 | `/mcp reload` | Disconnect and reconnect all configured MCP servers. |
 | `/reasoning` | Toggle chain-of-thought display. |
@@ -271,7 +349,7 @@ All tool calls show inline; mutating ones require per-call approval the first ti
                                        @cf/moonshotai/kimi-k2.6
 ```
 
-Direct `fetch` to Workers AI, OpenAI-compatible `messages` + `tools` payload, SSE stream with reasoning + content + tool-call deltas accumulated by index.
+Direct `fetch` to Workers AI by default, or the native Workers AI AI Gateway endpoint when `aiGatewayId` is configured. The payload remains OpenAI-compatible `messages` + `tools`, with an SSE stream containing reasoning + content + tool-call deltas accumulated by index.
 
 ## Development
 
@@ -384,6 +462,10 @@ For a real-world test, try the [official GitHub MCP server](https://github.com/m
 
 Then ask: `search for issues labeled bug in sinameraji/kimiflare`
 
+## Credits
+
+- **Cloudflare Agent Memory** — This feature was inspired by [Cloudflare's Agent Memory](https://blog.cloudflare.com/introducing-agent-memory/) announcement. While Cloudflare's managed service requires a platform binding, kimiflare implements a local self-hosted equivalent using SQLite + Workers AI embeddings so you can use it today with your own account.
+
 ## License
 
 [MIT](LICENSE) © Sina Meraji