limbo-ai 1.6.1 → 1.8.0

package/README.md

@@ -100,7 +100,7 @@ Managed automatically by `npx limbo-ai start`, stored in `~/.limbo/.env`.
 | `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`) |
-| `TELEGRAM_AUTO_PAIR_FIRST_DM` | no | `true` | Auto-approves the first Telegram DM sender and persists access (MVP-friendly onboarding) |
+| `TELEGRAM_AUTO_PAIR_FIRST_DM` | no | `false` | Auto-approves the first Telegram DM sender and persists access (must opt-in explicitly) |
 | `OPENCLAW_GATEWAY_TOKEN` | no | generated | Stable gateway token for OpenClaw-compatible clients |
 
 > \* API keys are required only for `AUTH_MODE=api-key`. Subscription auth uses OpenClaw auth profiles instead.

package/SECURITY.md

@@ -0,0 +1,109 @@
+# Security
+
+## Container Security Model
+
+Limbo runs inside a Docker container with the following hardening:
+
+- **Non-root user**: The `limbo` user (UID/GID created at build time) runs all processes
+- **Read-only filesystem**: Container root filesystem is immutable (`read_only: true`)
+- **No new privileges**: `no-new-privileges` seccomp flag prevents privilege escalation
+- **Capabilities dropped**: All Linux capabilities are dropped (`cap_drop: ALL`)
+- **Process limit**: PID limit of 200 prevents fork bombs
+- **Loopback binding**: Gateway only listens on `127.0.0.1` — not exposed to LAN
+- **Writable paths**: Only `/data` (volume), `/home/limbo/.openclaw` (volume), `/tmp` (tmpfs), and `/home/limbo/.npm` (tmpfs) are writable
+
+## What Agents Can Access
+
+Inside the container, the AI agent can:
+
+- Read and write vault notes in `/data/vault/` (via MCP tools only)
+- Execute MCP tools registered through mcporter (vault_search, vault_read, vault_write_note, vault_update_map)
+- Search the web and fetch URLs (`web_search`, `web_fetch` — enabled for recommendations, link previews, etc.)
+- Respond to Telegram messages (if enabled, with pairing required)
+- Make network requests to AI provider APIs (Anthropic, OpenAI, OpenRouter)
+
+## What Agents Cannot Do
+
+- **Execute shell commands**: `exec` tool is denied + set to `security: "deny"`
+- **Browse the web**: `browser` tool is denied
+- **Read/write arbitrary files**: `group:fs` is denied, `fs.workspaceOnly` enforced
+- **Modify gateway config**: `gateway` tool is denied
+- **Create scheduled jobs**: `cron` tool is denied
+- **Spawn sub-agents**: `sessions_spawn` and `sessions_send` are denied
+- **Use elevated mode**: `elevated.enabled: false`
+- **Escape the container**: Read-only root filesystem + all capabilities dropped
+- **Escalate privileges**: `no-new-privileges` seccomp flag
+- **Access host filesystem**: Only the bind-mounted vault directory is accessible
+- **Spawn unlimited processes**: PID limit of 200
+
+## OpenClaw Tool Policy
+
+The agent runs with `tools.profile: "messaging"` — the most restrictive built-in profile. On top of that:
+
+- **Allowed**: `web_search`, `web_fetch` (for link previews, shopping recommendations, general web queries)
+- **Denied**: `exec`, `browser`, `canvas`, `nodes`, `cron`, `gateway`, `sessions_spawn`, `sessions_send`, `process`, `image`, `group:automation`, `group:runtime`, `group:fs`
+- **Exec**: `security: "deny"`, `ask: "always"`
+- **Elevated mode**: disabled
+- **Filesystem**: workspace-only
+
+The agent can interact with users via messaging, access vault data through the MCP server, and search/fetch web content. It cannot execute commands, access the filesystem directly, modify the gateway config, or spawn sub-agents.
+
+## API Key Storage
+
+API keys are stored as Docker Compose secrets:
+
+- **Secret files**: `~/.limbo/secrets/` with `0600` permissions (user read/write only)
+- **Mounted at runtime**: `/run/secrets/<name>` inside the container (read-only, restricted permissions)
+- **Not in environment**: Secrets are scrubbed from the process environment before the gateway starts
+- **Not in `docker inspect`**: Docker secrets don't appear in container inspect output
+- **`.env` file**: Only contains non-sensitive configuration (model provider, model name, language, etc.)
+- **Exception**: `OPENCLAW_GATEWAY_TOKEN` remains in the process environment because the gateway process needs it to validate incoming WebSocket connections. All other secrets (API keys, bot tokens) are scrubbed before exec
+
+## OpenClaw Security
+
+Limbo uses OpenClaw in a **personal assistant trust model** (one trusted operator per gateway). Key settings:
+
+- `gateway.mode: "local"` — local operation only
+- `gateway.bind: "loopback"` — no network exposure
+- `gateway.auth.mode: "token"` — all WebSocket clients must authenticate
+- `session.dmScope: "per-channel-peer"` — DM sessions are isolated per sender (when using Telegram)
+- `dmPolicy: "pairing"` — unknown Telegram senders must be explicitly approved
+
+For more on OpenClaw's security model: https://docs.openclaw.ai/security
+
+## Network Access
+
+The container can make outbound HTTPS requests to:
+
+- AI provider APIs (api.anthropic.com, api.openai.com, openrouter.ai)
+- Telegram Bot API (api.telegram.org) — if Telegram is enabled
+- Arbitrary URLs via `web_search` and `web_fetch` tools (for user-requested link previews, recommendations, etc.)
+
+For stricter environments, Limbo supports an optional Squid proxy sidecar (`--hardened` flag) that restricts outbound traffic to an allowlist of AI provider domains only. Note: `--hardened` mode disables `web_fetch` functionality since the proxy blocks non-allowlisted domains.
+
+## Input Validation
+
+The MCP server applies the following protections:
+
+- **Path traversal**: All file operations resolve paths and verify they don't escape the vault directory
+- **ID sanitization**: Note and map IDs are restricted to alphanumeric characters, dashes, and underscores
+- **Search queries**: User input is always escaped (no raw regex execution) with a 200-character limit to prevent ReDoS
+
+## Known Limitations
+
+- **Prompt injection**: AI agents can be manipulated by carefully crafted input. The container sandbox limits blast radius, but agents may still misuse their available tools within the vault
+- **Vault data exposure**: Anything stored in vault notes is accessible to the agent. Do not store passwords, private keys, or other high-sensitivity secrets in notes
+- **Single trust boundary**: The container runs one agent with one set of credentials. All tools and data inside the container share the same trust level
+- **Web fetch exfiltration**: The agent can read vault notes and fetch arbitrary URLs. A successful prompt injection could theoretically exfiltrate vault data via crafted URLs. Mitigation: DM pairing limits who can trigger the bot, strong models resist injection, and API keys are stored in Docker secrets (not in the vault). Do not store high-sensitivity data in vault notes
+- **Outbound network**: The agent can reach any internet destination via `web_search`/`web_fetch`. Use `--hardened` mode for strict egress filtering (disables web_fetch)
+
+## Reporting Vulnerabilities
+
+If you discover a security vulnerability in Limbo:
+
+1. **Do not** open a public issue
+2. Email the maintainer directly (see repository contact info)
+3. Include: description, reproduction steps, affected version, and impact assessment
+4. We will acknowledge within 48 hours and work on a fix
+
+For vulnerabilities in OpenClaw itself, follow their responsible disclosure process at https://docs.openclaw.ai/security

package/cli.js

@@ -14,6 +14,7 @@ const readline = require('readline');
 
 const LIMBO_DIR = path.join(os.homedir(), '.limbo');
 const VAULT_DIR = path.join(LIMBO_DIR, 'vault');
+const SECRETS_DIR = path.join(LIMBO_DIR, 'secrets');
 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';
@@ -64,12 +65,25 @@ const COMPOSE_CONTENT = `services:
   limbo:
     image: ${GHCR_IMAGE}:${DEFAULT_TAG}
     restart: unless-stopped
+    read_only: true
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    pids_limit: 200
+    tmpfs:
+      - /tmp:size=100M,noexec,nosuid,nodev
+      - /home/limbo/.npm:size=50M,noexec,nosuid,nodev
     ports:
       - "127.0.0.1:${PORT}:${PORT}"
     volumes:
       - limbo-data:/data
       - ./vault:/data/vault
       - limbo-openclaw-state:/home/limbo/.openclaw
+    secrets:
+      - llm_api_key
+      - telegram_bot_token
+      - gateway_token
     env_file:
       - .env
     environment:
@@ -86,6 +100,98 @@ const COMPOSE_CONTENT = `services:
       retries: 3
       start_period: 15s
 
+secrets:
+  llm_api_key:
+    file: ./secrets/llm_api_key
+  telegram_bot_token:
+    file: ./secrets/telegram_bot_token
+  gateway_token:
+    file: ./secrets/gateway_token
+
+volumes:
+  limbo-data:
+  limbo-openclaw-state:
+`;
+
+// Hardened variant: adds Squid egress proxy sidecar with domain allowlist
+const COMPOSE_CONTENT_HARDENED = `services:
+  limbo:
+    image: ${GHCR_IMAGE}:${DEFAULT_TAG}
+    restart: unless-stopped
+    read_only: true
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    pids_limit: 200
+    tmpfs:
+      - /tmp:size=100M,noexec,nosuid,nodev
+      - /home/limbo/.npm:size=50M,noexec,nosuid,nodev
+    ports:
+      - "127.0.0.1:${PORT}:${PORT}"
+    volumes:
+      - limbo-data:/data
+      - ./vault:/data/vault
+      - limbo-openclaw-state:/home/limbo/.openclaw
+    secrets:
+      - llm_api_key
+      - telegram_bot_token
+      - gateway_token
+    env_file:
+      - .env
+    environment:
+      OPENCLAW_CONFIG_PATH: /home/limbo/.openclaw/openclaw.json
+      OPENCLAW_STATE_DIR: /home/limbo/.openclaw
+      HTTP_PROXY: http://squid:3128
+      HTTPS_PROXY: http://squid:3128
+      NO_PROXY: "127.0.0.1,localhost"
+    networks:
+      - internal
+    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
+
+  squid:
+    image: ubuntu/squid:latest
+    restart: unless-stopped
+    read_only: true
+    security_opt:
+      - no-new-privileges:true
+    cap_drop:
+      - ALL
+    cap_add:
+      - NET_BIND_SERVICE
+    tmpfs:
+      - /var/spool/squid:size=50M
+      - /var/log/squid:size=10M
+      - /var/run:size=5M
+    networks:
+      - internal
+      - external
+    volumes:
+      - ./squid/squid.conf:/etc/squid/squid.conf:ro
+      - ./squid/allowed-domains.txt:/etc/squid/allowed-domains.txt:ro
+
+networks:
+  internal:
+    internal: true
+  external:
+
+secrets:
+  llm_api_key:
+    file: ./secrets/llm_api_key
+  telegram_bot_token:
+    file: ./secrets/telegram_bot_token
+  gateway_token:
+    file: ./secrets/gateway_token
+
 volumes:
   limbo-data:
   limbo-openclaw-state:
@@ -114,7 +220,19 @@ const TEXT = {
     invalidOpenAIKey: 'OpenAI API keys usually start with "sk-".',
     invalidAnthropicKey: 'Anthropic API keys usually start with "sk-ant-".',
     telegramQuestion: 'Want to speak to Limbo through Telegram?',
+    telegramBotFatherSteps: [
+      'To create a Telegram bot:',
+      '  1. Open @BotFather: https://t.me/BotFather',
+      '  2. Send the command: /newbot',
+      '  3. Choose a display name for your bot (e.g. "My Limbo")',
+      '  4. Choose a username ending in "bot" (e.g. "my_limbo_bot")',
+      '  5. BotFather will reply with a token like:',
+      '       123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+      '  6. Copy that token and paste it below.',
+    ],
+    telegramTokenSafe: 'Your token is stored locally in ~/.limbo/.env and never sent anywhere.',
     telegramTokenPrompt: '  Telegram bot token: ',
+    telegramAutoPairQuestion: 'Auto-approve the first Telegram DM? (Convenient but less secure)',
     yes: 'Yes',
     no: 'No',
     configuration: 'Configuration',
@@ -168,6 +286,7 @@ const TEXT = {
     helpStatus: 'Show container status',
     helpHelp: 'Show this help',
     helpReconfigure: 'Reconfigure auth and onboarding settings (use with start)',
+    securityNotice: 'Security notice: Limbo runs AI agents inside a Docker container with access to your API keys and vault data. The container can make network requests to AI provider APIs. Do not store sensitive secrets (passwords, private keys) in your vault notes.',
     unknownCommand: (cmd) => `Unknown command: ${cmd}`,
   },
   es: {
@@ -192,7 +311,19 @@ const TEXT = {
     invalidOpenAIKey: 'Las API keys de OpenAI normalmente empiezan con "sk-".',
     invalidAnthropicKey: 'Las API keys de Anthropic normalmente empiezan con "sk-ant-".',
     telegramQuestion: 'Quieres hablar con Limbo por Telegram?',
+    telegramBotFatherSteps: [
+      'Para crear un bot de Telegram:',
+      '  1. Abri @BotFather: https://t.me/BotFather',
+      '  2. Manda el comando: /newbot',
+      '  3. Elegí un nombre para tu bot (ej: "Mi Limbo")',
+      '  4. Elegí un username que termine en "bot" (ej: "mi_limbo_bot")',
+      '  5. BotFather te va a responder con un token como este:',
+      '       123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
+      '  6. Copiá ese token y pegalo abajo.',
+    ],
+    telegramTokenSafe: 'Tu token se guarda localmente en ~/.limbo/.env y nunca se envia a ningun servidor externo.',
     telegramTokenPrompt: '  Telegram bot token: ',
+    telegramAutoPairQuestion: 'Auto-aprobar el primer DM de Telegram? (Conveniente pero menos seguro)',
     yes: 'Si',
     no: 'No',
     configuration: 'Configuracion',
@@ -246,6 +377,7 @@ const TEXT = {
     helpStatus: 'Muestra el estado del container',
     helpHelp: 'Muestra esta ayuda',
     helpReconfigure: 'Reconfigura auth y onboarding (usar con start)',
+    securityNotice: 'Aviso de seguridad: Limbo corre agentes de IA dentro de un container Docker con acceso a tus API keys y datos del vault. El container puede hacer requests a las APIs de los proveedores de IA. No guardes secretos sensibles (passwords, claves privadas) en las notas del vault.',
     unknownCommand: (cmd) => `Comando desconocido: ${cmd}`,
   },
 };
@@ -411,15 +543,35 @@ function normalizeConfig(cfg, existingEnv = {}) {
     LLM_API_KEY: cfg.apiKey || (cfg.keepExisting ? existingEnv.LLM_API_KEY || '' : ''),
     TELEGRAM_ENABLED: cfg.telegramEnabled || existingEnv.TELEGRAM_ENABLED || 'false',
     TELEGRAM_BOT_TOKEN: cfg.telegramToken || (cfg.keepExisting ? existingEnv.TELEGRAM_BOT_TOKEN || '' : ''),
-    TELEGRAM_AUTO_PAIR_FIRST_DM: existingEnv.TELEGRAM_AUTO_PAIR_FIRST_DM || 'true',
+    TELEGRAM_AUTO_PAIR_FIRST_DM: cfg.telegramAutoPair || existingEnv.TELEGRAM_AUTO_PAIR_FIRST_DM || 'false',
     OPENCLAW_GATEWAY_TOKEN: gatewayToken,
   };
 
   return base;
 }
 
+function writeSecretFile(name, value) {
+  fs.mkdirSync(SECRETS_DIR, { recursive: true, mode: 0o700 });
+  const filePath = path.join(SECRETS_DIR, name);
+  fs.writeFileSync(filePath, value || '', { mode: 0o600 });
+}
+
+function writeSecrets(cfg, existingEnv = {}) {
+  const normalized = normalizeConfig(cfg, existingEnv);
+  writeSecretFile('llm_api_key', normalized.LLM_API_KEY);
+  writeSecretFile('telegram_bot_token', normalized.TELEGRAM_BOT_TOKEN);
+  writeSecretFile('gateway_token', normalized.OPENCLAW_GATEWAY_TOKEN);
+}
+
+const SECRET_KEYS = new Set([
+  'LLM_API_KEY', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY',
+  'TELEGRAM_BOT_TOKEN', 'OPENCLAW_GATEWAY_TOKEN',
+]);
+
 function writeEnv(cfg, existingEnv = {}) {
+  writeSecrets(cfg, existingEnv);
   const content = Object.entries(normalizeConfig(cfg, existingEnv))
+    .filter(([key]) => !SECRET_KEYS.has(key))
     .map(([key, value]) => `${key}=${value}`)
     .join('\n') + '\n';
   fs.writeFileSync(ENV_FILE, content, { mode: 0o600 });
@@ -520,11 +672,21 @@ async function collectConfig(existingEnv = {}) {
   ], language);
 
   let telegramToken = '';
+  let telegramAutoPair = 'false';
   if (telegramChoice.value === 'true') {
+    console.log('');
+    TEXT[language].telegramBotFatherSteps.forEach((line) => console.log(`  ${c.dim}${line}${c.reset}`));
+    console.log(`  ${c.yellow}${TEXT[language].telegramTokenSafe}${c.reset}`);
+    console.log('');
     telegramToken = await promptValidated(
       t(language, 'telegramTokenPrompt'),
       (value) => value ? { ok: true, value } : { ok: false, message: t(language, 'requiredField') },
     );
+    const autoPairChoice = await selectMenu(t(language, 'telegramAutoPairQuestion'), [
+      { label: t(language, 'no'), value: 'false' },
+      { label: t(language, 'yes'), value: 'true' },
+    ], language);
+    telegramAutoPair = autoPairChoice.value;
   }
 
   return {
@@ -536,21 +698,50 @@ async function collectConfig(existingEnv = {}) {
     apiKey,
     telegramEnabled: telegramChoice.value,
     telegramToken,
+    telegramAutoPair,
     gatewayToken: existingEnv.OPENCLAW_GATEWAY_TOKEN || generateGatewayToken(),
   };
 }
 
-function ensureComposeFile() {
+function ensureComposeFile(hardened = false) {
   fs.mkdirSync(LIMBO_DIR, { recursive: true });
   fs.mkdirSync(path.join(VAULT_DIR, 'notes'), { recursive: true });
   fs.mkdirSync(path.join(VAULT_DIR, 'maps'), { recursive: true });
-  fs.writeFileSync(COMPOSE_FILE, COMPOSE_CONTENT);
+  fs.mkdirSync(SECRETS_DIR, { recursive: true, mode: 0o700 });
+  // Ensure secret files exist (Docker Compose secrets require the files to be present)
+  for (const name of ['llm_api_key', 'telegram_bot_token', 'gateway_token']) {
+    const fp = path.join(SECRETS_DIR, name);
+    if (!fs.existsSync(fp)) fs.writeFileSync(fp, '', { mode: 0o600 });
+  }
+  if (hardened) {
+    // Copy squid config files for egress filtering
+    const squidDir = path.join(LIMBO_DIR, 'squid');
+    fs.mkdirSync(squidDir, { recursive: true });
+    const srcSquidDir = path.join(__dirname, 'squid');
+    for (const file of ['squid.conf', 'allowed-domains.txt']) {
+      const src = path.join(srcSquidDir, file);
+      const dest = path.join(squidDir, file);
+      if (fs.existsSync(src)) fs.copyFileSync(src, dest);
+    }
+  }
+  fs.writeFileSync(COMPOSE_FILE, hardened ? COMPOSE_CONTENT_HARDENED : COMPOSE_CONTENT);
+}
+
+function readSecretFile(name) {
+  const fp = path.join(SECRETS_DIR, name);
+  try { return fs.readFileSync(fp, 'utf8').trim(); } catch { return ''; }
 }
 
 function ensureGatewayToken(existingEnv) {
-  if (existingEnv.OPENCLAW_GATEWAY_TOKEN) return existingEnv.OPENCLAW_GATEWAY_TOKEN;
+  // Check secret file first, then legacy env
+  const fromFile = readSecretFile('gateway_token');
+  if (fromFile) return fromFile;
+  if (existingEnv.OPENCLAW_GATEWAY_TOKEN) {
+    writeSecretFile('gateway_token', existingEnv.OPENCLAW_GATEWAY_TOKEN);
+    return existingEnv.OPENCLAW_GATEWAY_TOKEN;
+  }
   writeEnv({ keepExisting: true }, existingEnv);
-  return parseEnvFile().OPENCLAW_GATEWAY_TOKEN;
+  return readSecretFile('gateway_token');
 }
 
 function pullOrBuildImage(lang) {
@@ -676,7 +867,8 @@ ${c.green}${c.bold}╚═══════════════════
 async function cmdStart() {
   if (!hasDocker()) die(t('en', 'dockerMissing'));
 
-  ensureComposeFile();
+  const hardened = process.argv.includes('--hardened');
+  ensureComposeFile(hardened);
 
   const existingEnv = parseEnvFile();
   const alreadyHasEnv = fs.existsSync(ENV_FILE);
@@ -741,10 +933,12 @@ async function cmdStart() {
     ok(t(cfg.language, 'healthy'));
   }
 
+  console.log(`\n  ${c.yellow}⚠  ${t(cfg.language, 'securityNotice')}${c.reset}\n`);
+
   printSuccess({
     language: cfg.language,
     telegramEnabled: mergedEnv.TELEGRAM_ENABLED || cfg.telegramEnabled || 'false',
-  }, parseEnvFile().OPENCLAW_GATEWAY_TOKEN);
+  }, readSecretFile('gateway_token') || mergedEnv.OPENCLAW_GATEWAY_TOKEN);
 }
 
 function cmdStop() {
@@ -793,6 +987,7 @@ ${c.bold}Commands:${c.reset}
 
 ${c.bold}Flags:${c.reset}
   --reconfigure  Reconfigure auth and onboarding settings (use with start)
+  --hardened     Enable egress proxy (restricts outbound to AI provider APIs only)
 
 ${c.bold}Data directory:${c.reset} ${LIMBO_DIR}
 `);

package/mcp-server/index.js

@@ -13,7 +13,7 @@ import { vaultUpdateMap } from "./tools/update-map.js";
 const server = new Server(
   {
     name: "limbo-vault",
-    version: "1.0.0",
+    version: "1.1.0",
   },
   {
     capabilities: {
@@ -29,13 +29,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: "vault_search",
       description:
-        "Search notes in the vault by regex query. Returns matching notes with titles, snippets, and relevance scores.",
+        "Search notes in the vault by keyword query. Recursively searches all subdirectories. Returns matching notes with titles, snippets, relevance scores, and domain (subdirectory).",
       inputSchema: {
         type: "object",
         properties: {
           query: {
             type: "string",
-            description: "Regex or keyword query to search across all vault notes",
+            description: "Keyword query to search across all vault notes",
           },
         },
         required: ["query"],
@@ -44,13 +44,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: "vault_read",
       description:
-        "Read the full content of a vault note by ID. Returns raw markdown including YAML frontmatter.",
+        "Read the full content of a vault note by ID. Searches recursively through subdirectories. Returns raw markdown including YAML frontmatter.",
       inputSchema: {
         type: "object",
         properties: {
           noteId: {
             type: "string",
-            description: "The note ID (filename without .md extension)",
+            description: "The note ID (filename without .md extension). Searched recursively across all subdirectories.",
           },
         },
         required: ["noteId"],
@@ -59,16 +59,24 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       name: "vault_write_note",
       description:
-        "Create or overwrite a vault note with YAML frontmatter. Required fields: id, title, type, description, content. Optional: map.",
+        "Create or overwrite a vault note with YAML frontmatter. Supports subdirectory organization — creates the subdirectory if it doesn't exist.",
       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" },
+          type: { type: "string", description: "Note type: gotcha, decision, config-fact, pattern, tool-knowledge, research-finding, personal-fact" },
+          description: { type: "string", description: "One-sentence falsifiable description of the note's claim" },
           content: { type: "string", description: "Full markdown body of the note" },
-          map: { type: "string", description: "Optional: name of the MOC this note belongs to" },
+          subdirectory: { type: "string", description: "Optional subdirectory under notes/ (e.g. 'openclaw', 'research', 'aios/infrastructure'). Created if it doesn't exist." },
+          status: { type: "string", description: "Optional: current, outdated, superseded. Defaults to none." },
+          domain: { type: "string", description: "Optional: knowledge domain (e.g. openclaw, aios, research, personal)" },
+          source: { type: "string", description: "Optional: provenance (e.g. limbo, claude-code, web)" },
+          topics: {
+            type: "array",
+            items: { type: "string" },
+            description: "Optional: map references as wikilinks, e.g. [\"[[openclaw-map]]\"]",
+          },
         },
         required: ["id", "title", "type", "description", "content"],
       },
@@ -76,13 +84,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
     {
       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.",
+        "Append entries to a section in a Map of Content (MOC). Creates the map file (with frontmatter) and/or section if they don't exist. Maps live in vault/maps/.",
       inputSchema: {
         type: "object",
         properties: {
           map: {
             type: "string",
-            description: "Map filename without extension (alphanumeric, dashes, underscores)",
+            description: "Map filename without extension (e.g. 'openclaw-map', 'ai-research-map')",
           },
           section: {
             type: "string",
@@ -91,7 +99,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           entries: {
             type: "array",
             items: { type: "string" },
-            description: "Markdown link strings to append, e.g. [\"[[note-id|Note Title]]\"]",
+            description: "Markdown link strings to append, e.g. [\"- [[note-id|Note Title]]\"]",
           },
         },
         required: ["map", "section", "entries"],
@@ -128,7 +136,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       case "vault_write_note": {
         const result = await vaultWriteNote(args);
         return {
-          content: [{ type: "text", text: `Note written: ${result.id}` }],
+          content: [{ type: "text", text: `Note written: ${result.id} → ${result.path}` }],
         };
       }
 

package/mcp-server/tools/read.js

@@ -1,11 +1,65 @@
-import { readFile } from "fs/promises";
-import { join } from "path";
+import { readFile, readdir, stat } from "fs/promises";
+import { join, resolve } from "path";
 
 const VAULT_PATH = process.env.VAULT_PATH || "/data/vault";
 const NOTES_DIR = join(VAULT_PATH, "notes");
 
+/**
+ * Recursively find a note file by ID. Checks flat first, then subdirectories.
+ * Returns the file path or null.
+ */
+async function findNote(noteId) {
+  // Fast path: check flat location first
+  const flatPath = join(NOTES_DIR, `${noteId}.md`);
+  try {
+    await stat(flatPath);
+    return flatPath;
+  } catch {
+    // Not in root — search subdirectories
+  }
+
+  return searchDir(NOTES_DIR, noteId);
+}
+
+async function searchDir(dir, noteId) {
+  let items;
+  try {
+    items = await readdir(dir);
+  } catch {
+    return null;
+  }
+
+  for (const item of items) {
+    if (item.startsWith(".") || item === "_meta") continue;
+
+    const full = join(dir, item);
+    let s;
+    try {
+      s = await stat(full);
+    } catch {
+      continue;
+    }
+
+    if (s.isDirectory()) {
+      // Check if the note exists directly in this subdirectory
+      const candidate = join(full, `${noteId}.md`);
+      try {
+        await stat(candidate);
+        return candidate;
+      } catch {
+        // Recurse deeper
+        const found = await searchDir(full, noteId);
+        if (found) return found;
+      }
+    }
+  }
+
+  return null;
+}
+
 /**
  * vault_read(noteId): reads full content of a note by ID.
+ * Searches recursively through subdirectories.
  * Returns the raw markdown content including YAML frontmatter.
  * Returns null if the note doesn't exist.
  */
@@ -14,13 +68,21 @@ export async function vaultRead(noteId) {
     throw new Error("noteId must be a non-empty string");
   }
 
-  // Sanitize: only allow alphanumeric, dashes, underscores
+  // Sanitize: allow alphanumeric, dashes, underscores
   const safe = noteId.replace(/[^a-zA-Z0-9_\-]/g, "");
   if (safe !== noteId) {
     throw new Error("noteId contains invalid characters");
   }
 
-  const filePath = join(NOTES_DIR, `${safe}.md`);
+  const filePath = await findNote(safe);
+  if (!filePath) return null;
+
+  // Defense-in-depth: ensure resolved path stays within vault
+  const resolved = resolve(filePath);
+  if (!resolved.startsWith(resolve(NOTES_DIR) + "/")) {
+    throw new Error("Path traversal detected");
+  }
+
   try {
     return await readFile(filePath, "utf8");
   } catch (err) {

package/mcp-server/tools/search.js

@@ -1,17 +1,56 @@
-import { readdir, readFile } from "fs/promises";
-import { join, basename } from "path";
+import { readdir, readFile, stat } from "fs/promises";
+import { join, basename, relative } from "path";
 
 const VAULT_PATH = process.env.VAULT_PATH || "/data/vault";
 const NOTES_DIR = join(VAULT_PATH, "notes");
 
 /**
- * Extracts the title from YAML frontmatter or first H1 heading.
+ * Recursively collects all .md files under a directory.
+ * Returns array of { filePath, domain } where domain is the relative subdirectory.
+ */
+async function walkNotes(dir, base = dir) {
+  const entries = [];
+  let items;
+  try {
+    items = await readdir(dir);
+  } catch {
+    return entries;
+  }
+
+  for (const item of items) {
+    // Skip hidden directories and _meta
+    if (item.startsWith(".") || item === "_meta") continue;
+
+    const full = join(dir, item);
+    let s;
+    try {
+      s = await stat(full);
+    } catch {
+      continue;
+    }
+
+    if (s.isDirectory()) {
+      const sub = await walkNotes(full, base);
+      entries.push(...sub);
+    } else if (item.endsWith(".md")) {
+      const rel = relative(base, dir);
+      entries.push({ filePath: full, domain: rel || null });
+    }
+  }
+  return entries;
+}
+
+/**
+ * Extracts the title from YAML frontmatter, falling back to description or first H1.
  */
 function extractTitle(content) {
   const fmMatch = content.match(/^---\s*\n([\s\S]*?)\n---/);
   if (fmMatch) {
     const titleMatch = fmMatch[1].match(/^title:\s*["']?(.+?)["']?\s*$/m);
     if (titleMatch) return titleMatch[1];
+    // Fallback: use description if no title field
+    const descMatch = fmMatch[1].match(/^description:\s*["']?(.+?)["']?\s*$/m);
+    if (descMatch) return descMatch[1];
   }
   const h1Match = content.match(/^#\s+(.+)$/m);
   if (h1Match) return h1Match[1];
@@ -35,33 +74,27 @@ function extractSnippet(content, regex, maxLen = 150) {
 }
 
 /**
- * vault_search(query): regex search across all .md files in /data/vault/notes/.
- * Returns [{noteId, title, snippet, score}] sorted by score desc.
+ * vault_search(query): recursive search across all .md files in vault/notes/.
+ * Returns [{noteId, title, snippet, score, domain}] sorted by score desc.
  *
  * NOTE: Current implementation is a linear scan (O(n) per query). This is fine
  * for small vaults (hundreds of notes), but will need optimization at scale —
  * consider an inverted index (e.g. SQLite FTS5) when the vault grows large.
  */
 export async function vaultSearch(query) {
-  let files;
-  try {
-    files = await readdir(NOTES_DIR);
-  } catch {
-    return [];
+  if (query.length > 200) {
+    throw new Error("Search query too long (max 200 characters)");
   }
 
-  const mdFiles = files.filter((f) => f.endsWith(".md"));
-  let regex;
-  try {
-    regex = new RegExp(query, "gi");
-  } catch {
-    // Fallback to literal search if invalid regex
-    regex = new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), "gi");
-  }
+  const files = await walkNotes(NOTES_DIR);
+  if (files.length === 0) return [];
+
+  // Always escape user input to prevent ReDoS from pathological patterns
+  const escaped = query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const regex = new RegExp(escaped, "gi");
 
   const results = [];
-  for (const file of mdFiles) {
-    const filePath = join(NOTES_DIR, file);
+  for (const { filePath, domain } of files) {
     let content;
     try {
       content = await readFile(filePath, "utf8");
@@ -72,12 +105,12 @@ export async function vaultSearch(query) {
     const matches = content.match(regex);
     if (!matches) continue;
 
-    const noteId = basename(file, ".md");
+    const noteId = basename(filePath, ".md");
     const title = extractTitle(content) || noteId;
     const score = matches.length;
     const snippet = extractSnippet(content, regex);
 
-    results.push({ noteId, title, snippet, score });
+    results.push({ noteId, title, snippet, score, domain });
   }
 
   results.sort((a, b) => b.score - a.score);

package/mcp-server/tools/update-map.js

@@ -1,5 +1,5 @@
 import { readFile, writeFile, mkdir } from "fs/promises";
-import { join } from "path";
+import { join, resolve } from "path";
 
 const VAULT_PATH = process.env.VAULT_PATH || "/data/vault";
 const MAPS_DIR = join(VAULT_PATH, "maps");
@@ -13,6 +13,19 @@ function sanitizeName(name) {
   return safe;
 }
 
+/**
+ * Builds frontmatter for a new map file.
+ */
+function buildMapFrontmatter(name) {
+  const lines = [
+    "---",
+    `description: "${name.replace(/-/g, " ")}"`,
+    "type: moc",
+    "---",
+  ];
+  return lines.join("\n");
+}
+
 /**
  * Finds or creates a section in markdown content.
  * Returns the updated content string.
@@ -42,8 +55,9 @@ function upsertSection(content, section, entries) {
 
 /**
  * vault_update_map(map, section, entries): appends entries to a MOC section.
- * Creates the section if it doesn't exist.
- * Entries are markdown link strings, e.g. ["[[note-id|Note Title]]"]
+ * Creates the map file and/or section if they don't exist.
+ * New maps are created with proper YAML frontmatter.
+ * Entries are markdown link strings, e.g. ["- [[note-id|Note Title]]"]
  *
  * @param {string} map - map filename without extension
  * @param {string} section - section heading text
@@ -57,15 +71,18 @@ export async function vaultUpdateMap(map, section, entries) {
   const safeMap = sanitizeName(map);
   await mkdir(MAPS_DIR, { recursive: true });
 
-  const filePath = join(MAPS_DIR, `${safeMap}.md`);
+  const filePath = resolve(MAPS_DIR, `${safeMap}.md`);
+  if (!filePath.startsWith(resolve(MAPS_DIR) + "/")) {
+    throw new Error("Path traversal detected");
+  }
 
   let existing = "";
   try {
     existing = await readFile(filePath, "utf8");
   } catch (err) {
     if (err.code !== "ENOENT") throw err;
-    // New map — start with a title
-    existing = `# ${map}\n`;
+    // New map — start with frontmatter and title
+    existing = `${buildMapFrontmatter(map)}\n\n# ${map}\n`;
   }
 
   const updated = upsertSection(existing, section, entries);

package/mcp-server/tools/write.js

@@ -1,32 +1,51 @@
 import { writeFile, mkdir } from "fs/promises";
-import { join } from "path";
+import { join, resolve } from "path";
 
 const VAULT_PATH = process.env.VAULT_PATH || "/data/vault";
 const NOTES_DIR = join(VAULT_PATH, "notes");
 
 const REQUIRED_FIELDS = ["id", "title", "type", "description", "content"];
 
+function escapeYaml(str) {
+  return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+
 /**
  * Builds YAML frontmatter string from note metadata.
+ * Supports the merged schema: id, title, description, type, status, domain,
+ * created, source, topics.
  */
 function buildFrontmatter(note) {
   const lines = ["---"];
   lines.push(`id: ${note.id}`);
-  lines.push(`title: "${note.title.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`);
+  lines.push(`title: "${escapeYaml(note.title)}"`);
+  lines.push(`description: "${escapeYaml(note.description)}"`);
   lines.push(`type: ${note.type}`);
-  lines.push(`description: "${note.description.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`);
-  if (note.map) {
-    lines.push(`map: ${note.map}`);
+  if (note.status) {
+    lines.push(`status: ${note.status}`);
+  }
+  if (note.domain) {
+    lines.push(`domain: ${note.domain}`);
+  }
+  lines.push(`created: "${note.created || new Date().toISOString().split("T")[0]}"`);
+  if (note.source) {
+    lines.push(`source: ${note.source}`);
+  }
+  if (note.topics && note.topics.length > 0) {
+    lines.push("topics:");
+    for (const topic of note.topics) {
+      lines.push(`  - "${escapeYaml(topic)}"`);
+    }
   }
-  lines.push(`created: ${new Date().toISOString().split("T")[0]}`);
   lines.push("---");
   return lines.join("\n");
 }
 
 /**
  * vault_write_note(note): creates a markdown file with YAML frontmatter.
- * Input: {id, title, type, description, content, map?}
- * Writes to /data/vault/notes/{id}.md
+ * Input: {id, title, type, description, content, subdirectory?, status?, domain?, source?, topics?}
+ * Writes to /data/vault/notes/{subdirectory?}/{id}.md
+ * Creates the subdirectory if it doesn't exist.
  */
 export async function vaultWriteNote(note) {
   for (const field of REQUIRED_FIELDS) {
@@ -41,11 +60,29 @@ export async function vaultWriteNote(note) {
     throw new Error("note.id contains invalid characters");
   }
 
-  await mkdir(NOTES_DIR, { recursive: true });
+  // Determine target directory
+  let targetDir = NOTES_DIR;
+  if (note.subdirectory) {
+    // Sanitize subdirectory: allow alphanumeric, dashes, underscores, forward slashes
+    const safeSub = note.subdirectory.replace(/[^a-zA-Z0-9_\-/]/g, "");
+    if (safeSub !== note.subdirectory) {
+      throw new Error("subdirectory contains invalid characters");
+    }
+    // Prevent path traversal
+    if (safeSub.includes("..")) {
+      throw new Error("subdirectory cannot contain '..'");
+    }
+    targetDir = join(NOTES_DIR, safeSub);
+  }
 
-  const frontmatter = buildFrontmatter(note);
+  await mkdir(targetDir, { recursive: true });
+
+  const frontmatter = buildFrontmatter({ ...note, id: safe });
   const fileContent = `${frontmatter}\n\n${note.content}\n`;
-  const filePath = join(NOTES_DIR, `${safe}.md`);
+  const filePath = resolve(targetDir, `${safe}.md`);
+  if (!filePath.startsWith(resolve(NOTES_DIR) + "/")) {
+    throw new Error("Path traversal detected");
+  }
 
   await writeFile(filePath, fileContent, "utf8");
   return { id: safe, path: filePath };

package/package.json

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

package/squid/allowed-domains.txt

@@ -0,0 +1,4 @@
+.api.anthropic.com
+.api.openai.com
+.openrouter.ai
+.api.telegram.org

package/squid/squid.conf

@@ -0,0 +1,39 @@
+# Squid proxy config for Limbo egress filtering
+# Only allows HTTPS CONNECT to allowlisted domains
+
+# ACL: allowed destination domains
+acl allowed_domains dstdomain "/etc/squid/allowed-domains.txt"
+
+# ACL: SSL ports used by AI provider APIs
+acl SSL_ports port 443
+
+# Only allow CONNECT method (HTTPS tunneling)
+acl CONNECT method CONNECT
+
+# Only CONNECT (HTTPS tunneling) is allowed — deny plain HTTP
+http_access deny !CONNECT
+
+# Deny CONNECT to non-SSL ports
+http_access deny CONNECT !SSL_ports
+
+# Allow CONNECT to allowlisted domains only
+http_access allow CONNECT allowed_domains
+
+# Deny everything else
+http_access deny all
+
+# Listen on port 3128
+http_port 3128
+
+# Minimal logging (privacy)
+access_log none
+cache_log /dev/null
+
+# No caching — we're a pure forward proxy
+cache deny all
+
+# Suppress Squid version in headers
+httpd_suppress_version_string on
+
+# Visible hostname (internal only)
+visible_hostname limbo-proxy