limbo-ai 1.24.7 → 1.24.9

package/README.md

@@ -1,143 +1,104 @@
 # Limbo
 
-A personal memory agent. Captures ideas, remembers things, and connects knowledge across time — running quietly in a Docker container, accessible via Telegram or the ZeroClaw gateway.
+[![npm](https://img.shields.io/npm/v/limbo-ai?color=blue&label=release)](https://www.npmjs.com/package/limbo-ai)
+[![build](https://img.shields.io/github/actions/workflow/status/TomasWard1/limbo/ci.yml?branch=staging&label=build)](https://github.com/TomasWard1/limbo/actions)
+[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
+[![platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS-lightgrey)](.)
+[![docker](https://img.shields.io/badge/docker-%E2%9C%93-blue)](https://github.com/TomasWard1/limbo/pkgs/container/limbo)
 
-## What it is
+A personal memory agent. Captures ideas, remembers things, and connects knowledge across time — running in a Docker container, accessible via Telegram or the ZeroClaw gateway.
 
-Limbo is a second brain with a conversational interface. It stores atomic notes in a local vault, searches them semantically, and maintains Maps of Content (MOCs) to keep knowledge navigable. It is not a general-purpose assistant — it is a memory system.
-
-**Agent personality:** defined in `workspace/IDENTITY.md` and `workspace/SOUL.md`, baked into the image at build time.
+Limbo is a second brain with a conversational interface. It stores atomic notes in a local vault, searches them semantically, and maintains Maps of Content (MOCs) to keep knowledge navigable.
 
 ---
 
-## Hardware Requirements
-
-Limbo runs as a single Docker container (~35 MB RAM at idle). The main resource cost is Docker and the host OS, not Limbo itself.
-
-| Tier | RAM | vCPU | Disk | Notes |
-|------|-----|------|------|-------|
-| Minimum | 512 MB | 1 | 1 GB | Needs swap configured |
-| Recommended | 1 GB | 1 | 5 GB | Comfortable for Limbo alone |
-| With other services | 2 GB | 1 | 10 GB | Room for reverse proxy, monitoring, etc. |
+## Install
 
-> Limbo's container uses ~35 MB at rest and peaks around ~70 MB during cold starts. CPU usage is negligible — short bursts of 5-7% when processing messages.
+> Limbo is designed to run on a VPS (always-on, accessible from anywhere). A $5/month Ubuntu server is all you need.
 
----
+### 1. Provision a server
 
-## Quick Start
+Any Ubuntu/Debian VPS with 1 GB+ RAM. Recommended providers: Hetzner, DigitalOcean, Vultr, ReliedCloud.
 
-Requires [Docker Desktop](https://docs.docker.com/get-docker/) and Node.js 18+.
+### 2. Run the installer
 
-```sh
-npx limbo-ai start
+```bash
+curl -fsSL https://raw.githubusercontent.com/TomasWard1/limbo/main/scripts/install.sh | bash
 ```
 
-This will:
-1. Prompt for your API key (Anthropic or OpenAI)
-2. Write `~/.limbo/.env` and `~/.limbo/docker-compose.yml`
-3. Pull the latest Limbo image and start the container
+This installs Docker, Node.js, and the Limbo CLI.
 
-Limbo binds to `127.0.0.1:18789`.
-
-### Agent Installation
-
-AI agents can install Limbo non-interactively using CLI flags:
+### 3. Start Limbo
 
 ```bash
-npx limbo-ai start --provider openrouter --api-key sk-or-v1-xxx --model auto
+limbo start
 ```
 
-**Required flags:**
-| Flag | Description |
-|------|-------------|
-| `--provider` | `openai`, `anthropic`, or `openrouter` |
-| `--api-key` | Your provider API key |
-
-**Optional flags:**
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--model` | Provider default | Model name (e.g. `anthropic/claude-sonnet-4-6`) |
-| `--language` | `en` | CLI language (`en` or `es`) |
-
-Headless mode skips Telegram setup. To add Telegram later, run `npx limbo-ai start --reconfigure`.
+The setup wizard walks you through:
+- [ ] Choose a language (English / Español)
+- [ ] Select a provider (Anthropic, OpenAI, OpenRouter)
+- [ ] Authenticate (API key or Claude/ChatGPT subscription)
+- [ ] Pick a model
+- [ ] Connect Telegram (optional but recommended)
+- [ ] Enable voice messages and web search (optional)
+- [ ] Review and confirm
 
-> **Note:** Subscription-based auth (ChatGPT/Codex, Claude Code) requires interactive setup because it involves browser-based OAuth or token pasting. Use `npx limbo-ai start` without flags for subscription auth.
+Once complete, Limbo restarts and is ready to use.
 
-### Available commands
+### 4. Update
 
-```sh
-npx limbo-ai@latest start        # Install and start (default if no command given)
-npx limbo-ai@latest stop         # Stop the container
-npx limbo-ai@latest update       # Pull latest image and restart
-npx limbo-ai@latest status       # Show container status
-npx limbo-ai@latest logs         # Tail container logs
-npx limbo-ai@latest start --reconfigure   # Change API keys or settings
-npx limbo-ai@latest config               # Configure optional features (voice, web-search)
+```bash
+limbo update
 ```
 
----
-
-## Optional Features
-
-Limbo supports optional features that can be enabled during the setup wizard (step 7) or anytime via the CLI.
-
-### Voice Messages
+Pulls the latest image and restarts. Vault data is persisted and not affected.
 
-Transcribe Telegram voice notes using [Groq](https://groq.com) Whisper. Requires a Groq API key (`gsk_...`).
-
-```sh
-npx limbo-ai@latest config voice --enable --api-key gsk_xxx
-npx limbo-ai@latest config voice --status
-npx limbo-ai@latest config voice --disable
-```
+---
 
-### Web Search
+## Local Install (macOS/Linux)
 
-Give Limbo real-time web search via the [Brave Search API](https://brave.com/search/api/). Requires a Brave API key (`BSA...`).
+If you prefer running locally instead of a VPS:
 
-```sh
-npx limbo-ai@latest config web-search --enable --api-key BSAxxx
-npx limbo-ai@latest config web-search --status
-npx limbo-ai@latest config web-search --disable
+```bash
+npx limbo-ai start
 ```
 
-Both features store API keys as Docker secrets and toggle config sections in the container on restart.
+Requires [Docker Desktop](https://docs.docker.com/get-docker/) and Node.js 18+. Binds to `127.0.0.1:18789`.
 
 ---
 
-## Updating
+## Commands
 
 ```sh
-npx limbo-ai@latest update
+limbo start                  # Install and start (enters wizard on first run)
+limbo stop                   # Stop the container
+limbo update                 # Pull latest image and restart
+limbo status                 # Show container status
+limbo logs                   # Tail container logs
+limbo start --reconfigure    # Re-run the setup wizard
+limbo config voice --enable --api-key gsk_xxx   # Enable voice transcription
+limbo config web-search --enable --api-key BSA_xxx  # Enable web search
 ```
 
-Pulls the latest Limbo image and restarts the container. Your vault data is persisted in the `limbo-data` Docker volume and is not affected.
-
 ---
 
 ## Connecting
 
-There are two ways to connect: **talk to Limbo** (conversational, with its personality and memory logic) or **use the vault directly** (raw tool access from another agent).
-
-### Talk to Limbo
+### Telegram (recommended)
 
-#### Telegram (recommended)
+The setup wizard walks you through creating a Telegram bot and pairing it. Message your bot and Limbo responds — full agent with personality, memory logic, and vault tools.
 
-During setup (`npx limbo-ai start`), the wizard will walk you through creating a Telegram bot via BotFather and pairing it. Message your bot and Limbo will respond — full agent with personality, memory logic, and vault tools.
+### ZeroClaw gateway
 
-#### ZeroClaw gateway
-
-Any [ZeroClaw](https://github.com/zeroclaw-labs/zeroclaw)-compatible chat client can connect to:
+Any [ZeroClaw](https://github.com/zeroclaw-labs/zeroclaw)-compatible client can connect via WebSocket:
 
 ```
 ws://localhost:18789
 ```
 
-This gives you a conversational session with Limbo, same as Telegram but over WebSocket.
-
-### Use the vault from another agent
+### MCP (for other AI agents)
 
-If you want another AI agent (like Claude Code) to read and write to Limbo's vault directly — without going through Limbo's personality or reasoning — add it as an MCP server:
+Add Limbo as an MCP server to give another agent direct vault access:
 
 ```json
 {
@@ -149,43 +110,43 @@ If you want another AI agent (like Claude Code) to read and write to Limbo's vau
 }
 ```
 
-This exposes the 4 vault tools (`vault_search`, `vault_read`, `vault_write_note`, `vault_update_map`) as MCP tools in the connecting agent. The agent operates on the vault directly — Limbo's LLM is not involved.
+This exposes 4 vault tools (`vault_search`, `vault_read`, `vault_write_note`, `vault_update_map`). The connecting agent operates on the vault directly — Limbo's LLM is not involved.
 
 ---
 
-## Environment Variables
+## Optional Features
 
-Managed automatically by `npx limbo-ai start`, stored in `~/.limbo/.env`.
+Enable during the setup wizard or anytime via CLI.
 
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `AUTH_MODE` | no | `api-key` | `api-key` or `subscription` |
-| `OPENAI_API_KEY` | no* | — | OpenAI API key for `MODEL_PROVIDER=openai` |
-| `ANTHROPIC_API_KEY` | no* | — | Anthropic API key for `MODEL_PROVIDER=anthropic` |
-| `LLM_API_KEY` | no | — | Legacy generic key path for older installs |
-| `MODEL_PROVIDER` | no | `anthropic` | Model provider: `anthropic`, `openai`, or `openai-codex` |
-| `MODEL_NAME` | no | `claude-opus-4-6` | Model name (e.g. `claude-opus-4-6`, `claude-sonnet-4-6`, `gpt-5.4`) |
-| `TELEGRAM_ENABLED` | no | `false` | Enable Telegram bot integration |
-| `TELEGRAM_BOT_TOKEN` | no | — | Telegram bot token (required if `TELEGRAM_ENABLED=true`) |
-| `VOICE_ENABLED` | no | `false` | Enable voice transcription (requires Groq API key as Docker secret) |
-| `WEB_SEARCH_ENABLED` | no | `false` | Enable web search (requires Brave API key as Docker secret) |
+### Voice Messages
 
-> \* API keys are required only for `AUTH_MODE=api-key`. Subscription auth uses ZeroClaw auth profiles instead.
+Transcribe Telegram voice notes using [Groq](https://groq.com) Whisper.
 
----
+```sh
+limbo config voice --enable --api-key gsk_xxx
+limbo config voice --disable
+```
+
+### Web Search
 
-## MCP Tools
+Real-time web search via [Brave Search API](https://brave.com/search/api/).
 
-Limbo exposes 4 tools via the `limbo-vault` MCP server:
+```sh
+limbo config web-search --enable --api-key BSAxxx
+limbo config web-search --disable
+```
+
+---
 
-| Tool | Description |
-|------|-------------|
-| `vault_search` | Search notes by regex or keyword |
-| `vault_read` | Read a note by ID (returns raw markdown + frontmatter) |
-| `vault_write_note` | Create or overwrite a note with structured frontmatter |
-| `vault_update_map` | Append entries to a Map of Content (MOC) |
+## Hardware Requirements
+
+| Tier | RAM | vCPU | Disk |
+|------|-----|------|------|
+| Minimum | 512 MB | 1 | 1 GB |
+| Recommended | 1 GB | 1 | 5 GB |
+| With other services | 2 GB | 1 | 10 GB |
 
-Full tool specs in `workspace/TOOLS.md`.
+Limbo uses ~35 MB at rest, peaks ~70 MB during cold starts. CPU usage is negligible.
 
 ---
 
@@ -211,54 +172,59 @@ Full tool specs in `workspace/TOOLS.md`.
 └─────────────────────────────────────────┘
 ```
 
-- **ZeroClaw** — lightweight Rust runtime (~5MB RAM) that handles client connections, routes to the LLM, manages Telegram, and integrates MCP tools natively
-- **MCP server** — Node.js server providing vault read/write tools (spawned by ZeroClaw, no mcporter needed)
-- **Vault** — plain markdown files with YAML frontmatter, persisted in a named Docker volume
-- **Migrations** — lightweight Node.js migration runner for vault schema changes
+- **ZeroClaw** — Rust runtime (~5 MB RAM) handling connections, LLM routing, Telegram, and MCP tools
+- **MCP server** — Node.js vault read/write tools, spawned by ZeroClaw
+- **Vault** — plain markdown with YAML frontmatter, persisted in a Docker volume
 
-**Data directory layout** (in `/data` volume):
+---
 
-```
-/data/
-  vault/      # markdown notes
-  db/         # sqlite (future use)
-  logs/       # startup and runtime logs
-  backups/    # snapshots
-  memory/     # agent memory
-  config/
-    USER.md   # per-user persona file (generated at runtime)
+## Agent Installation (headless)
+
+For CI/CD or automated provisioning:
+
+```bash
+npx limbo-ai start --provider anthropic --api-key sk-ant-xxx --model claude-sonnet-4-6
 ```
 
----
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--provider` | yes | — | `anthropic`, `openai`, or `openrouter` |
+| `--api-key` | yes | — | Provider API key |
+| `--model` | no | Provider default | Model name |
+| `--language` | no | `en` | `en` or `es` |
 
-## Development Setup
+Headless mode skips Telegram. Add it later with `limbo start --reconfigure`.
 
-### Prerequisites
+> Subscription auth (Claude Code, ChatGPT Plus) requires the interactive wizard.
 
-- Docker + Docker Compose
-- Node.js 22+ (for local MCP server dev)
+---
 
-### Run MCP server locally
+## Environment Variables
 
-```sh
-cd mcp-server
-npm install
-VAULT_PATH=./dev-vault node index.js
-```
+Managed by `limbo start`, stored in `~/.limbo/.env`.
 
-### Build image locally
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AUTH_MODE` | `api-key` | `api-key` or `subscription` |
+| `MODEL_PROVIDER` | `anthropic` | `anthropic`, `openai`, `openai-codex`, or `openrouter` |
+| `MODEL_NAME` | `claude-sonnet-4-6` | Model to use |
+| `TELEGRAM_ENABLED` | `false` | Enable Telegram integration |
+| `VOICE_ENABLED` | `false` | Enable Groq voice transcription |
+| `WEB_SEARCH_ENABLED` | `false` | Enable Brave web search |
 
-```sh
-docker build -t limbo:dev .
-docker compose up -d
-```
+---
 
-### Run migrations standalone
+## Development
 
 ```sh
-node migrations/index.js
-```
+# Run MCP server locally
+cd mcp-server && npm install && VAULT_PATH=./dev-vault node index.js
 
----
+# Build image locally
+docker build -t limbo:dev . && docker compose up -d
+
+# Run tests
+npm test
+```
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for release and deployment process.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "limbo-ai",
-  "version": "1.24.7",
+  "version": "1.24.9",
   "description": "Your personal AI memory agent — install and manage Limbo via npx",
   "type": "commonjs",
   "bin": {

package/setup-server/server.js

@@ -229,9 +229,11 @@ function decodeJwtPayload(token) {
   return JSON.parse(Buffer.from(parts[1], 'base64url').toString());
 }
 
-// ZeroClaw auth-profiles.json — must match the structure used by the CLI
-// (cli.js buildAnthropicAuthProfile / buildCodexAuthProfile).
-// Path: ~/.zeroclaw/agents/main/agent/auth-profiles.json
+// ─── OpenAI Codex auth profiles ──────────────────────────────────────────────
+// OpenAI OAuth tokens expire and need refresh. ZeroClaw reads auth-profiles.json
+// for the refresh token and handles renewal automatically. This is ONLY needed
+// for OpenAI Codex — Anthropic tokens are static and stored as secrets instead.
+const AUTH_PROFILES_FILE = path.join(ZEROCLAW_STATE, 'auth-profiles.json');
 
 function buildCodexAuthProfile(profile) {
   const profileId = profile.email ? `openai-codex:${profile.email}` : 'openai-codex:default';
@@ -253,26 +255,6 @@ function buildCodexAuthProfile(profile) {
   };
 }
 
-function buildAnthropicAuthProfile(token) {
-  return {
-    version: 1,
-    profiles: {
-      'anthropic:token': {
-        type: 'token',
-        provider: 'anthropic',
-        token,
-      },
-    },
-    order: { anthropic: ['anthropic:token'] },
-    lastGood: {},
-    usageStats: {},
-  };
-}
-
-// ZeroClaw resolves auth profiles from the state dir root: ~/.zeroclaw/auth-profiles.json
-// See: ZeroClaw src/auth/profiles.rs — state_dir.join("auth-profiles.json")
-const AUTH_PROFILES_FILE = path.join(ZEROCLAW_STATE, 'auth-profiles.json');
-
 function writeAuthProfiles(store) {
   fs.mkdirSync(ZEROCLAW_STATE, { recursive: true, mode: 0o700 });
   fs.writeFileSync(AUTH_PROFILES_FILE, JSON.stringify(store, null, 2), { mode: 0o600 });
@@ -557,6 +539,7 @@ async function exchangeOAuthCode(code, verifier, redirectUri) {
 function processOAuthTokens(tokenRes) {
   const jwt = decodeJwtPayload(tokenRes.access_token);
   const authClaim = jwt['https://api.openai.com/auth'] || {};
+  // Write auth profile for ZeroClaw's OAuth refresh flow
   const store = buildCodexAuthProfile({
     access: tokenRes.access_token,
     refresh: tokenRes.refresh_token,
@@ -565,6 +548,8 @@ function processOAuthTokens(tokenRes) {
     email: jwt.email || '',
   });
   writeAuthProfiles(store);
+  // Also write access token as secret for entrypoint to export
+  writeSecretFile('llm_api_key', tokenRes.access_token);
   return { email: jwt.email || '' };
 }
 
@@ -676,8 +661,9 @@ async function handleAnthropicToken(req, res) {
     return;
   }
 
-  const store = buildAnthropicAuthProfile(token);
-  writeAuthProfiles(store);
+  // Anthropic tokens are static (no refresh needed) — store as secret
+  writeSecretFile('llm_api_key', token);
+  log('Anthropic token written to secrets/llm_api_key');
   sendJSON(res, 200, { success: true });
 }
 
@@ -861,7 +847,6 @@ module.exports = {
   buildOAuthUrl,
   decodeJwtPayload,
   buildCodexAuthProfile,
-  buildAnthropicAuthProfile,
   handleRequest,
   _internals: {
     OPENAI_OAUTH,

package/test/setup-server.test.js

@@ -15,7 +15,6 @@ const {
   buildOAuthUrl,
   decodeJwtPayload,
   buildCodexAuthProfile,
-  buildAnthropicAuthProfile,
   handleRequest,
   _internals: { OPENAI_OAUTH },
 } = require('../setup-server/server.js');
@@ -197,24 +196,6 @@ describe('buildCodexAuthProfile', () => {
   });
 });
 
-describe('buildAnthropicAuthProfile', () => {
-  it('builds correct structure', () => {
-    const result = buildAnthropicAuthProfile('sk-ant-test123');
-    assert.strictEqual(result.version, 1);
-    const pid = 'anthropic:token';
-    assert.ok(result.profiles[pid], 'profile entry exists');
-    assert.strictEqual(result.profiles[pid].provider, 'anthropic');
-    assert.strictEqual(result.profiles[pid].type, 'token');
-    assert.strictEqual(result.profiles[pid].token, 'sk-ant-test123');
-  });
-
-  it('order includes anthropic key', () => {
-    const result = buildAnthropicAuthProfile('sk-ant-xyz');
-    assert.ok(result.order.anthropic, 'order has anthropic key');
-    assert.deepStrictEqual(result.order.anthropic, ['anthropic:token']);
-  });
-});
-
 // ─── B. HTTP handler tests ──────────────────────────────────────────────────
 
 describe('HTTP handler', () => {