limbo-ai 1.0.0

package/.claude/settings.local.json

@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Skill(paperclip-run-review)",
+      "WebSearch",
+      "Bash(curl:*)",
+      "Bash(python3:*)",
+      "Bash(git commit:*)"
+    ]
+  }
+}

package/.vercel/README.txt

@@ -0,0 +1,11 @@
+> Why do I have a folder named ".vercel" in my project?
+The ".vercel" folder is created when you link a directory to a Vercel project.
+
+> What does the "project.json" file contain?
+The "project.json" file contains:
+- The ID of the Vercel project that you linked ("projectId")
+- The ID of the user or team your Vercel project is owned by ("orgId")
+
+> Should I commit the ".vercel" folder?
+No, you should not share the ".vercel" folder with anyone.
+Upon creation, it will be automatically added to your ".gitignore" file.

package/.vercel/project.json

@@ -0,0 +1 @@
+{"projectId":"prj_BFmCaecv5QdNrenjJAQy8r6o85ir","orgId":"team_h0ONoWt3JduSqJJuJhnDoDiw","projectName":"limbo-landing"}

package/README.md

@@ -0,0 +1,193 @@
+# 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 OpenClaw gateway.
+
+## What it is
+
+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.
+
+---
+
+## Quick Start (Docker Compose)
+
+```sh
+# 1. Copy the env template
+cp .env.example .env
+
+# 2. Fill in your credentials (see Environment Variables below)
+$EDITOR .env
+
+# 3. Start
+docker compose up -d
+
+# 4. Check health
+docker compose ps
+```
+
+Limbo binds to `127.0.0.1:18789`. Connect via the OpenClaw gateway or Telegram bot.
+
+---
+
+## One-Line Installer
+
+Canonical installer URL:
+
+```sh
+https://gist.githubusercontent.com/TomasWard1/d130b8d34cc8eeb0527d045d06985396/raw/install.sh
+```
+
+Run directly:
+
+```sh
+curl -fsSL https://gist.githubusercontent.com/TomasWard1/d130b8d34cc8eeb0527d045d06985396/raw/install.sh | bash
+```
+
+Run with explicit sudo escalation:
+
+```sh
+sudo bash <(curl -fsSL https://gist.githubusercontent.com/TomasWard1/d130b8d34cc8eeb0527d045d06985396/raw/install.sh)
+```
+
+---
+
+## Release Channel (GHCR)
+
+Stable deploys should use a pinned semver image tag via `LIMBO_IMAGE_TAG`.
+
+- Release workflow source: `.github/workflows/release-ghcr.yml`
+- Published tags per release tag `vX.Y.Z`:
+  - `ghcr.io/tomasward1/limbo:X.Y.Z`
+  - `ghcr.io/tomasward1/limbo:X`
+  - `ghcr.io/tomasward1/limbo:latest`
+
+Create a release tag:
+
+```sh
+git tag -a v1.0.0 -m "Limbo v1.0.0"
+git push origin v1.0.0
+```
+
+Verify public pull (no credentials):
+
+```sh
+docker logout ghcr.io
+docker manifest inspect ghcr.io/tomasward1/limbo:1.0.0
+docker pull ghcr.io/tomasward1/limbo:1.0.0
+```
+
+If GHCR pull is denied (for example, private package or temporary registry policy), the installer automatically falls back to building from source on the target host.
+
+---
+## Environment Variables
+
+Copy `.env.example` to `.env` and set:
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `LLM_API_KEY` | **yes*** | — | API key for your chosen model provider (Anthropic or OpenAI) |
+| `ANTHROPIC_API_KEY` | **yes*** | — | Legacy alias for `LLM_API_KEY` — accepted for backwards compatibility |
+| `MODEL_PROVIDER` | no | `anthropic` | Model provider: `anthropic` or `openai` |
+| `MODEL_NAME` | no | `claude-sonnet-4-6` | Model name (e.g. `claude-sonnet-4-6`, `codex-mini-latest`, `gpt-4o`) |
+| `TELEGRAM_ENABLED` | no | `false` | Enable Telegram bot integration |
+| `TELEGRAM_BOT_TOKEN` | no | — | Telegram bot token (required if `TELEGRAM_ENABLED=true`) |
+| `TELEGRAM_AUTO_PAIR_FIRST_DM` | no | `true` | Auto-approves the first Telegram DM sender and persists access (MVP-friendly onboarding) |
+
+> \* Either `LLM_API_KEY` **or** `ANTHROPIC_API_KEY` is required. `LLM_API_KEY` takes precedence if both are set.
+
+---
+
+## MCP Tools
+
+Limbo exposes 4 tools via the `limbo-vault` MCP server:
+
+| 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) |
+
+Full tool specs in `workspace/TOOLS.md`.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│              Docker Container           │
+│                                         │
+│  ┌─────────────┐    ┌────────────────┐  │
+│  │  OpenClaw   │◄──►│  Claude (LLM)  │  │
+│  │  Gateway    │    └────────┬───────┘  │
+│  │  :18789     │             │          │
+│  └──────┬──────┘    ┌────────▼───────┐  │
+│         │           │  MCP Server    │  │
+│  Telegram Bot        │  limbo-vault  │  │
+│         │           └────────┬───────┘  │
+│         └────────────────────┤          │
+│                              ▼          │
+│                      /data/vault/       │
+│                      (markdown notes)   │
+└─────────────────────────────────────────┘
+```
+
+- **OpenClaw** — gateway that wraps the Claude API with MCP tool support and optional Telegram integration
+- **MCP server** — Node.js server providing vault read/write tools
+- **Vault** — plain markdown files with YAML frontmatter, persisted in a named Docker volume
+- **Migrations** — lightweight Node.js migration runner for vault schema changes
+
+**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)
+```
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- Docker + Docker Compose
+- Node.js 22+ (for local MCP server dev)
+
+### Run MCP server locally
+
+```sh
+cd mcp-server
+npm install
+VAULT_PATH=./dev-vault node index.js
+```
+
+### Build image locally
+
+```sh
+docker build -t limbo:dev .
+docker run --rm -e LLM_API_KEY=sk-ant-... -p 18789:18789 limbo:dev
+```
+
+### Run migrations standalone
+
+```sh
+node migrations/index.js
+```
+
+---
+
+## Connecting
+
+**Via OpenClaw (direct):**
+Point any OpenClaw-compatible client at `ws://localhost:18789`.
+
+**Via Telegram:**
+Set `TELEGRAM_ENABLED=true` and `TELEGRAM_BOT_TOKEN` in `.env`, then message your bot.

package/cli.js

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+// cli.js — Limbo CLI
+// Orchestrates the Docker-based Limbo runtime.
+// Zero npm dependencies — pure Node.js stdlib.
+'use strict';
+
+const { execSync, spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const os = require('os');
+
+// ─── Config ──────────────────────────────────────────────────────────────────
+
+const LIMBO_DIR = path.join(os.homedir(), '.limbo');
+const ENV_FILE = path.join(LIMBO_DIR, '.env');
+const COMPOSE_FILE = path.join(LIMBO_DIR, 'docker-compose.yml');
+const GHCR_IMAGE = 'ghcr.io/tomasward1/limbo';
+const DEFAULT_TAG = '1.0.0';
+const PORT = 18789;
+
+// docker-compose.yml written to ~/.limbo on install
+const COMPOSE_CONTENT = `services:
+  limbo:
+    image: ${GHCR_IMAGE}:\${LIMBO_IMAGE_TAG:-${DEFAULT_TAG}}
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:${PORT}:${PORT}"
+    volumes:
+      - limbo-data:/data
+    env_file:
+      - .env
+    healthcheck:
+      test:
+        - CMD-SHELL
+        - >-
+          node -e "const s=require('net').connect(${PORT},'127.0.0.1');const
+          done=(c)=>{try{s.destroy()}catch{};process.exit(c)};s.on('connect',()=>done(0));s.on('error',()=>done(1));setTimeout(()=>done(1),2000);"
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 15s
+
+volumes:
+  limbo-data:
+`;
+
+// ─── Colors ──────────────────────────────────────────────────────────────────
+
+const c = {
+  reset: '\x1b[0m',
+  bold:  '\x1b[1m',
+  cyan:  '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  red:   '\x1b[31m',
+};
+
+const log   = (msg) => console.log(`${c.cyan}[limbo]${c.reset} ${msg}`);
+const ok    = (msg) => console.log(`${c.green}[limbo]${c.reset} ${msg}`);
+const warn  = (msg) => console.log(`${c.yellow}[limbo]${c.reset} ${msg}`);
+const die   = (msg) => { console.error(`${c.red}[limbo] ERROR:${c.reset} ${msg}`); process.exit(1); };
+const header = (msg) => console.log(`\n${c.bold}${msg}${c.reset}`);
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function hasDocker() {
+  const result = spawnSync('docker', ['compose', 'version'], { stdio: 'pipe' });
+  return result.status === 0;
+}
+
+function run(cmd, opts = {}) {
+  return execSync(cmd, { stdio: 'inherit', cwd: LIMBO_DIR, ...opts });
+}
+
+function runQuiet(cmd) {
+  return execSync(cmd, { stdio: 'pipe', cwd: LIMBO_DIR }).toString().trim();
+}
+
+function prompt(rl, question) {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+async function collectConfig() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  console.log('Limbo supports Anthropic (Claude) and OpenAI as model providers.');
+  console.log('Telegram integration is optional — press Enter to skip.\n');
+
+  const provider = (await prompt(rl, '  Model provider (anthropic/openai) [anthropic]: ')).trim() || 'anthropic';
+  const isOpenAI = provider === 'openai';
+  const defaultModel = isOpenAI ? 'codex-mini-latest' : 'claude-sonnet-4-6';
+  const keyLabel = isOpenAI ? 'OpenAI API key (sk-...)' : 'Anthropic API key (sk-ant-...)';
+
+  let llmKey = '';
+  while (!llmKey) {
+    llmKey = (await prompt(rl, `  ${keyLabel}: `)).trim();
+    if (!llmKey) warn('This field is required.');
+  }
+
+  const modelName = (await prompt(rl, `  Model name [${defaultModel}]: `)).trim() || defaultModel;
+  const tgRaw = (await prompt(rl, '  Enable Telegram bot? (true/false) [false]: ')).trim() || 'false';
+  const telegramEnabled = tgRaw === 'true' ? 'true' : 'false';
+  let telegramToken = '';
+  if (telegramEnabled === 'true') {
+    while (!telegramToken) {
+      telegramToken = (await prompt(rl, '  Telegram bot token: ')).trim();
+      if (!telegramToken) warn('This field is required when Telegram is enabled.');
+    }
+  }
+
+  const tag = (await prompt(rl, `  Image tag [${DEFAULT_TAG}]: `)).trim() || DEFAULT_TAG;
+
+  rl.close();
+  return { provider: isOpenAI ? 'openai' : 'anthropic', llmKey, modelName, telegramEnabled, telegramToken, tag };
+}
+
+function writeEnv({ provider, llmKey, modelName, telegramEnabled, telegramToken, tag }) {
+  const content = [
+    `LLM_API_KEY=${llmKey}`,
+    `MODEL_PROVIDER=${provider}`,
+    `MODEL_NAME=${modelName}`,
+    `TELEGRAM_ENABLED=${telegramEnabled}`,
+    `TELEGRAM_BOT_TOKEN=${telegramToken}`,
+    `LIMBO_IMAGE_TAG=${tag}`,
+  ].join('\n') + '\n';
+  fs.writeFileSync(ENV_FILE, content, { mode: 0o600 });
+}
+
+function waitForHealthy(maxAttempts = 12) {
+  for (let i = 1; i <= maxAttempts; i++) {
+    try {
+      const raw = runQuiet('docker compose ps --format json');
+      if (raw.includes('"healthy"')) return true;
+    } catch {}
+    log(`Waiting for container to be healthy... (${i}/${maxAttempts})`);
+    // simple sync sleep
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 5000);
+  }
+  return false;
+}
+
+// ─── Commands ────────────────────────────────────────────────────────────────
+
+async function cmdStart() {
+  header('=== Limbo ===');
+
+  if (!hasDocker()) {
+    die('Docker is not installed or `docker compose` is unavailable.\nInstall Docker Desktop: https://docs.docker.com/get-docker/');
+  }
+
+  fs.mkdirSync(LIMBO_DIR, { recursive: true });
+  fs.writeFileSync(COMPOSE_FILE, COMPOSE_CONTENT);
+
+  const alreadyHasEnv = fs.existsSync(ENV_FILE);
+  let cfg;
+
+  if (alreadyHasEnv) {
+    log(`Found existing config at ${ENV_FILE}`);
+    const reconfig = process.argv.includes('--reconfigure');
+    if (!reconfig) {
+      log('Starting with existing config. Use --reconfigure to change settings.');
+      cfg = null; // skip writing
+    } else {
+      header('Reconfiguration');
+      cfg = await collectConfig();
+    }
+  } else {
+    header('Configuration');
+    cfg = await collectConfig();
+  }
+
+  if (cfg) {
+    writeEnv(cfg);
+    ok('.env written.');
+  }
+
+  header('Pulling image...');
+  try {
+    run('docker compose pull -q');
+    ok('Image pulled.');
+  } catch {
+    warn('Could not pull from GHCR. Is the image public? Trying local build fallback...');
+    // Fallback: build from current directory if we're inside the repo
+    const repoDockerfile = path.join(__dirname, 'Dockerfile');
+    if (fs.existsSync(repoDockerfile)) {
+      log('Building from local Dockerfile...');
+      const tag = cfg?.tag || DEFAULT_TAG;
+      execSync(`docker build -t ${GHCR_IMAGE}:${tag} .`, { stdio: 'inherit', cwd: __dirname });
+      ok(`Built: ${GHCR_IMAGE}:${tag}`);
+    } else {
+      die('Could not pull image and no local Dockerfile found. Check your network or GHCR access.');
+    }
+  }
+
+  header('Starting Limbo...');
+  run('docker compose up -d --remove-orphans');
+
+  header('Verifying health...');
+  const healthy = waitForHealthy();
+  if (!healthy) {
+    warn('Container did not report healthy within timeout.');
+    warn(`Check logs with: limbo logs`);
+  } else {
+    ok('Container is healthy.');
+  }
+
+  console.log(`
+${c.green}${c.bold}╔════════════════════════════════════════════╗${c.reset}
+${c.green}${c.bold}║       Limbo is running!                    ║${c.reset}
+${c.green}${c.bold}╚════════════════════════════════════════════╝${c.reset}
+
+  ${c.bold}Gateway:${c.reset}  ws://127.0.0.1:${PORT}
+  ${c.bold}Data:${c.reset}     ${LIMBO_DIR}
+  ${c.bold}Logs:${c.reset}     limbo logs
+  ${c.bold}Stop:${c.reset}     limbo stop
+  ${c.bold}Update:${c.reset}   limbo update
+`);
+}
+
+function cmdStop() {
+  if (!fs.existsSync(COMPOSE_FILE)) die('Limbo is not installed. Run: npx limbo start');
+  log('Stopping Limbo...');
+  run('docker compose down');
+  ok('Stopped.');
+}
+
+function cmdLogs() {
+  if (!fs.existsSync(COMPOSE_FILE)) die('Limbo is not installed. Run: npx limbo start');
+  run('docker compose logs -f');
+}
+
+function cmdUpdate() {
+  if (!fs.existsSync(COMPOSE_FILE)) die('Limbo is not installed. Run: npx limbo start');
+  log('Pulling latest image...');
+  run('docker compose pull -q');
+  log('Restarting...');
+  run('docker compose up -d --remove-orphans');
+  ok('Updated and restarted.');
+}
+
+function cmdStatus() {
+  if (!fs.existsSync(COMPOSE_FILE)) {
+    log('Limbo is not installed.');
+    return;
+  }
+  run('docker compose ps');
+}
+
+function cmdHelp() {
+  console.log(`
+${c.bold}limbo${c.reset} — personal AI memory agent
+
+${c.bold}Usage:${c.reset}
+  npx limbo [command]
+
+${c.bold}Commands:${c.reset}
+  start         Install and start Limbo (default if no command given)
+  stop          Stop the running container
+  logs          Tail container logs
+  update        Pull latest image and restart
+  status        Show container status
+  help          Show this help
+
+${c.bold}Flags:${c.reset}
+  --reconfigure  Reconfigure API keys and settings (use with start)
+
+${c.bold}Data directory:${c.reset} ${LIMBO_DIR}
+`);
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+const [,, cmd = 'start'] = process.argv;
+
+(async () => {
+  switch (cmd) {
+    case 'start':
+    case 'install': await cmdStart(); break;
+    case 'stop':    cmdStop();  break;
+    case 'logs':    cmdLogs();  break;
+    case 'update':  cmdUpdate(); break;
+    case 'status':  cmdStatus(); break;
+    case 'help':
+    case '--help':
+    case '-h':      cmdHelp(); break;
+    default:
+      warn(`Unknown command: ${cmd}`);
+      cmdHelp();
+      process.exit(1);
+  }
+})().catch((err) => {
+  die(err.message || String(err));
+});

package/mcp-server/index.js

@@ -0,0 +1,164 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { vaultSearch } from "./tools/search.js";
+import { vaultRead } from "./tools/read.js";
+import { vaultWriteNote } from "./tools/write.js";
+import { vaultUpdateMap } from "./tools/update-map.js";
+
+const server = new Server(
+  {
+    name: "limbo-vault",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// ── Tool definitions ────────────────────────────────────────────────────────
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "vault_search",
+      description:
+        "Search notes in the vault by regex query. Returns matching notes with titles, snippets, and relevance scores.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Regex or keyword query to search across all vault notes",
+          },
+        },
+        required: ["query"],
+      },
+    },
+    {
+      name: "vault_read",
+      description:
+        "Read the full content of a vault note by ID. Returns raw markdown including YAML frontmatter.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          noteId: {
+            type: "string",
+            description: "The note ID (filename without .md extension)",
+          },
+        },
+        required: ["noteId"],
+      },
+    },
+    {
+      name: "vault_write_note",
+      description:
+        "Create or overwrite a vault note with YAML frontmatter. Required fields: id, title, type, description, content. Optional: map.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Unique note identifier (alphanumeric, dashes, underscores)" },
+          title: { type: "string", description: "Human-readable note title" },
+          type: { type: "string", description: "Note type, e.g. claim, source, concept, question" },
+          description: { type: "string", description: "One-sentence description of the note's claim or content" },
+          content: { type: "string", description: "Full markdown body of the note" },
+          map: { type: "string", description: "Optional: name of the MOC this note belongs to" },
+        },
+        required: ["id", "title", "type", "description", "content"],
+      },
+    },
+    {
+      name: "vault_update_map",
+      description:
+        "Append entries to a section in a Map of Content (MOC). Creates the map file and/or section if they don't exist.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          map: {
+            type: "string",
+            description: "Map filename without extension (alphanumeric, dashes, underscores)",
+          },
+          section: {
+            type: "string",
+            description: "Section heading text to append entries under",
+          },
+          entries: {
+            type: "array",
+            items: { type: "string" },
+            description: "Markdown link strings to append, e.g. [\"[[note-id|Note Title]]\"]",
+          },
+        },
+        required: ["map", "section", "entries"],
+      },
+    },
+  ],
+}));
+
+// ── Tool execution ──────────────────────────────────────────────────────────
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "vault_search": {
+        const results = await vaultSearch(args.query);
+        return {
+          content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+        };
+      }
+
+      case "vault_read": {
+        const content = await vaultRead(args.noteId);
+        if (content === null) {
+          return {
+            content: [{ type: "text", text: `Note not found: ${args.noteId}` }],
+            isError: true,
+          };
+        }
+        return { content: [{ type: "text", text: content }] };
+      }
+
+      case "vault_write_note": {
+        const result = await vaultWriteNote(args);
+        return {
+          content: [{ type: "text", text: `Note written: ${result.id}` }],
+        };
+      }
+
+      case "vault_update_map": {
+        const result = await vaultUpdateMap(args.map, args.section, args.entries);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Map updated: ${result.map} — added ${result.added} entries to "${result.section}"`,
+            },
+          ],
+        };
+      }
+
+      default:
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+  } catch (err) {
+    return {
+      content: [{ type: "text", text: `Error: ${err.message}` }],
+      isError: true,
+    };
+  }
+});
+
+// ── Start ───────────────────────────────────────────────────────────────────
+
+const transport = new StdioServerTransport();
+await server.connect(transport);