limbo-ai 1.6.1 → 1.7.0

package/cli.js

@@ -114,6 +114,17 @@ 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 Telegram and search for @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: ',
     yes: 'Yes',
     no: 'No',
@@ -192,6 +203,17 @@ 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 Telegram y busca @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: ',
     yes: 'Si',
     no: 'No',
@@ -521,6 +543,10 @@ async function collectConfig(existingEnv = {}) {
 
   let telegramToken = '';
   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') },

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 { readFile, readdir, stat } from "fs/promises";
 import { join } 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,15 @@ 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;
+
   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

@@ -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
@@ -64,8 +78,8 @@ export async function vaultUpdateMap(map, section, entries) {
     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

@@ -6,27 +6,46 @@ 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,26 @@ 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);
+  }
+
+  await mkdir(targetDir, { recursive: true });
 
-  const frontmatter = buildFrontmatter(note);
+  const frontmatter = buildFrontmatter({ ...note, id: safe });
   const fileContent = `${frontmatter}\n\n${note.content}\n`;
-  const filePath = join(NOTES_DIR, `${safe}.md`);
+  const filePath = join(targetDir, `${safe}.md`);
 
   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.7.0",
   "description": "Your personal AI memory agent — install and manage Limbo via npx",
   "type": "commonjs",
   "bin": {