baby-daemon 1.0.0

package/.env.example

@@ -0,0 +1,3 @@
+# Gemini API Key from Google AI Studio
+# Get a free key from https://aistudio.google.com/
+GEMINI_API_KEY=your_free_gemini_api_key_here

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sankolte
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# 🧠 Baby Daemon
+
+> A background daemon that gives AI coding agents persistent memory across sessions.
+
+---
+
+## The Problem
+
+Every AI coding session is stateless by default. Switch agents, restart a session, or continue the next day — your AI forgets everything. Decisions, bugs, architecture choices. You re-explain it all. Every. Single. Time.
+
+**Baby Daemon fixes that.**
+
+---
+
+## How It Works
+
+```
+1. Run `memory-watch ./logs`  →  daemon starts watching your agent's chat logs
+2. File changes detected      →  Gemini 2.5 Flash extracts structured memories
+3. Memories stored            →  LanceDB (vector) + memory.jsonl (flat)
+4. New session, new agent     →  `memory search "why did auth break?"` → instant context
+```
+
+---
+
+## CLI Commands
+
+```bash
+# Start the daemon (watches a folder for AI chat logs)
+memory-watch ./logs
+
+# Start with human approval for high-confidence decisions
+memory-watch ./logs --require-approval
+
+# Semantic search across all stored memories
+memory search "authentication bug"
+
+# Filtered search
+memory search "caching strategy" --type decision --since "3 days ago"
+
+# Dump raw logs (bypasses vector DB — emergency fallback)
+memory dump --since "yesterday"
+
+# Archive old memories to keep search fast
+memory archive --age 14
+```
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Runtime | Node.js (ES Modules) |
+| File Watcher | `chokidar` (event-driven, OS-native) |
+| LLM Summarizer | Google Gemini 2.5 Flash |
+| Embeddings | `gemini-embedding-2` |
+| Vector DB | LanceDB (local, embedded — no server) |
+| Keyword Fallback | `minisearch` (pure JS) |
+| Date Parsing | `chrono-node` ("yesterday", "2 days ago") |
+| Integrity | SHA-256 hashing (`node:crypto`) |
+
+---
+
+## Memory Schema
+
+Every memory is a structured, typed object — never a plain string:
+
+```json
+{
+  "id": "mem-1716300000-a1b2c3d4",
+  "timestamp": "2026-05-21T10:30:00Z",
+  "type": "proposed_idea",
+  "content": "Consider switching to Redis for caching layer",
+  "original_text": "maybe we should use Redis...",
+  "confidence": 0.4,
+  "status": "active",
+  "related_files": ["cache.ts"],
+  "tags": ["redis", "caching"],
+  "source": { "chat_file": "chat_042.md" },
+  "hash": "e4a91b7a9f..."
+}
+```
+
+**Types:** `decision` · `proposed_idea` · `rejected_idea` · `open_question` · `bug` · `resolved_bug` · `architecture_note` · `file_change`
+
+---
+
+## Key Design Decisions
+
+### Duplicate Prevention (Idempotency)
+OS file watchers fire multiple times per save. Every file event is fingerprinted:
+```
+key = SHA-256(absolute_path + "|" + last_modified_ms)
+```
+Key is stored in `processed_keys.json`. Only recorded **after** successful processing — so failures auto-retry.
+
+### Memory Drift Prevention
+LLMs compress uncertainty. *"Maybe use Redis"* becomes *"Project migrated to Redis."*
+
+Fixes:
+- Strict type schema — `decision` requires explicit commitment from both sides
+- Every memory stores the **exact source quote** (`original_text`)
+- `--require-approval` flag for human-in-the-loop on high-risk memories
+- `status: outdated` for contradicted memories + archival system
+
+### 3-Layer Hybrid Search
+1. **LanceDB vector search** — cosine similarity, 0.70 threshold
+2. **Metadata filtering** — type, date (natural language via chrono-node), file
+3. **MiniSearch keyword fallback** — if vector search returns nothing
+4. **Raw dump fallback** — if everything else fails, `memory dump` bypasses the AI layer entirely
+
+### Never Summarize a Summary
+Memories are always generated from **original raw logs**, never from previous summaries. Prevents information entropy across multi-agent handoffs.
+
+---
+
+## Build Phases
+
+- [x] **Phase 1** — File watcher shell + idempotency
+- [x] **Phase 2** — Gemini summarization pipeline + structured schema
+- [x] **Phase 3** — LanceDB vector store + semantic search
+- [x] **Phase 4** — Integrity (SHA-256 hashes, fallback dump, approval mode, archival)
+- [x] **Phase 5** — MCP Server (wrap as plug-and-play tool for any MCP-compatible agent)
+
+---
+
+## Setup
+
+```bash
+git clone https://github.com/sankolte/Baby-Daemon.git
+cd Baby-Daemon
+npm install
+cp .env.example .env
+# Add your GEMINI_API_KEY to .env
+```
+
+```bash
+# Watch your logs folder
+node bin/memory-watch.js ./logs
+
+# Or if installed globally via npm link:
+memory-watch ./logs
+```
+
+---
+
+## Project Structure
+
+```
+├── mcp-server.js           ← MCP server entry point (Phase 5)
+├── bin/
+│   ├── memory-watch.js     ← Start the daemon
+│   └── memory.js           ← Search, dump, archive
+├── src/
+│   ├── watcher.js          ← chokidar + pipeline orchestration
+│   ├── summarizer.js       ← Gemini call + JSON schema enforcement
+│   ├── vectorStore.js      ← LanceDB, embeddings cache, MiniSearch fallback
+│   ├── memoryStore.js      ← JSONL read/write
+│   ├── idempotency.js      ← SHA-256 key generation + persistence
+│   └── config.js           ← Gemini SDK init
+├── memory.jsonl            ← Flat structured memory store (gitignored)
+├── .lancedb/               ← Local vector DB (gitignored)
+├── claude_desktop_config.example.json  ← Example MCP config
+└── .env.example            ← Environment variable template
+```
+
+---
+
+## Phase 5 — MCP Server
+
+Baby Daemon is now available as an **MCP (Model Context Protocol) server**. Any MCP-compatible AI host can use it natively — no CLI required.
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `memory_search` | Semantic + keyword search with filters (type, date, file, limit) |
+| `memory_store` | Push raw text through the summarization pipeline and store |
+| `memory_dump` | Dump all stored memories with optional filters |
+| `memory_archive` | Move old memories to archive table |
+| `memory_read` | Full project knowledge briefing grouped by category |
+
+**Resource:** `memory://status` — system health, counts, LanceDB status  
+**Prompt:** `continue_from_memory` — context-rich prompt to resume work from previous sessions
+
+### Setup for Claude Desktop
+
+Add to `%APPDATA%/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "baby-daemon": {
+      "command": "node",
+      "args": ["C:\\path\\to\\proj101\\mcp-server.js"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop — Baby Daemon tools appear automatically.
+
+### Setup for Cursor / Cline / Other MCP Hosts
+
+Most MCP hosts use a similar JSON config. Point it to:
+```
+command: node
+args: ["<absolute-path-to>/mcp-server.js"]
+```
+
+### Testing with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector node mcp-server.js
+```
+
+Opens a web UI where you can interactively test all tools, read resources, and invoke prompts.
+
+---
+
+## License
+
+MIT

package/bin/baby-daemon.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+/**
+ * bin/baby-daemon.js
+ * ──────────────────
+ * The main entry command for Baby Daemon.
+ * 
+ * When a user installs globally (npm install -g baby-daemon),
+ * they can run: baby-daemon
+ * 
+ * This shows:
+ *   - Quick status (is API key set? are there memories?)
+ *   - Available commands
+ *   - MCP setup instructions
+ *   - First-time setup help
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import dotenv from 'dotenv';
+
+// Load .env from current working directory (where the user runs the command)
+dotenv.config({ path: path.join(process.cwd(), '.env') });
+
+// Also try loading from the package directory (for global installs)
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.join(__dirname, '..');
+dotenv.config({ path: path.join(PACKAGE_ROOT, '.env') });
+
+// CLI Styling
+const R = '\x1b[0m';     // Reset
+const B = '\x1b[1m';     // Bold
+const D = '\x1b[2m';     // Dim
+const C = '\x1b[36m';    // Cyan
+const G = '\x1b[32m';    // Green
+const Y = '\x1b[33m';    // Yellow
+const M = '\x1b[35m';    // Magenta
+const RED = '\x1b[31m';  // Red
+
+const args = process.argv.slice(2);
+const command = args[0]?.toLowerCase();
+
+if (command === 'setup') {
+  handleSetup();
+} else if (command === 'mcp-config') {
+  handleMcpConfig();
+} else {
+  handleDefault();
+}
+
+// ─────────────────────────────────────────────────────────────────
+// DEFAULT: Show status + available commands
+// ─────────────────────────────────────────────────────────────────
+
+function handleDefault() {
+  const hasApiKey = !!process.env.GEMINI_API_KEY;
+  const memoryFile = path.join(process.cwd(), 'memory.jsonl');
+  const hasMemories = fs.existsSync(memoryFile);
+  let memoryCount = 0;
+  if (hasMemories) {
+    try {
+      const content = fs.readFileSync(memoryFile, 'utf-8');
+      memoryCount = content.split('\n').filter(l => l.trim()).length;
+    } catch { /* ignore */ }
+  }
+
+  console.log(`
+  ${B}${C}🧠 Baby Daemon${R} ${D}v0.1.0${R}
+  ${D}AI memory system for coding agents${R}
+
+  ${B}STATUS:${R}
+    API Key    : ${hasApiKey ? `${G}✓ Set${R}` : `${RED}✗ Not set${R} ${D}(run: baby-daemon setup)${R}`}
+    Memories   : ${hasMemories ? `${G}${memoryCount} stored${R}` : `${Y}None yet${R}`}
+    Directory  : ${D}${process.cwd()}${R}
+
+  ${B}COMMANDS:${R}
+    ${C}memory-watch ${D}<folder>${R}        Watch a folder for AI chat logs
+    ${C}memory search ${D}<query>${R}        Search stored memories (semantic + keyword)
+    ${C}memory read${R}                  View all active memories by category
+    ${C}memory dump${R}                  Dump raw memory data
+    ${C}memory archive${R}               Archive old memories
+
+  ${B}SETUP:${R}
+    ${C}baby-daemon setup${R}            First-time setup guide
+    ${C}baby-daemon mcp-config${R}       Show MCP server config for Claude/Cursor
+
+  ${B}MCP SERVER:${R}
+    ${D}For AI hosts (Claude Desktop, Cursor, Cline):${R}
+    ${C}baby-daemon mcp-config${R}       ${D}← shows the JSON config to copy${R}
+  `);
+}
+
+// ─────────────────────────────────────────────────────────────────
+// SETUP: First-time setup guide
+// ─────────────────────────────────────────────────────────────────
+
+function handleSetup() {
+  const hasApiKey = !!process.env.GEMINI_API_KEY;
+  const envExists = fs.existsSync(path.join(process.cwd(), '.env'));
+
+  console.log(`
+  ${B}${C}🧠 Baby Daemon — Setup Guide${R}
+
+  ${B}Step 1: Get a Gemini API Key (free)${R}
+  ${D}Go to:${R} ${C}https://aistudio.google.com/apikey${R}
+  ${D}Click "Create API key" → copy it${R}
+
+  ${B}Step 2: Create a .env file${R}
+  ${D}In your project root, create a file called${R} ${C}.env${R} ${D}with:${R}
+
+    ${G}GEMINI_API_KEY=your_api_key_here${R}
+
+  ${envExists ? `  ${G}✓ .env file found in current directory${R}` : `  ${Y}⚠ No .env file found in ${process.cwd()}${R}`}
+  ${hasApiKey ? `  ${G}✓ API key is loaded${R}` : `  ${RED}✗ API key not detected yet${R}`}
+
+  ${B}Step 3: Create a logs folder${R}
+  ${D}This is where your AI agent chat logs go:${R}
+
+    ${C}mkdir logs${R}
+
+  ${B}Step 4: Start watching${R}
+
+    ${C}memory-watch ./logs${R}
+
+  ${D}Baby Daemon will now watch for new/changed files in ./logs,
+  extract structured memories via Gemini, and store them for search.${R}
+
+  ${B}Step 5 (Optional): Connect to Claude Desktop / Cursor${R}
+
+    ${C}baby-daemon mcp-config${R}
+  `);
+}
+
+// ─────────────────────────────────────────────────────────────────
+// MCP-CONFIG: Show copy-paste MCP configuration
+// ─────────────────────────────────────────────────────────────────
+
+function handleMcpConfig() {
+  // Find the mcp-server.js path
+  const mcpServerPath = path.join(PACKAGE_ROOT, 'mcp-server.js');
+  const mcpServerExists = fs.existsSync(mcpServerPath);
+
+  // Format path for JSON (escape backslashes for Windows)
+  const escapedPath = mcpServerPath.replace(/\\/g, '\\\\');
+
+  console.log(`
+  ${B}${C}🧠 Baby Daemon — MCP Server Configuration${R}
+
+  ${mcpServerExists ? `${G}✓ MCP server found at:${R}` : `${RED}✗ MCP server not found at:${R}`}
+  ${D}${mcpServerPath}${R}
+
+  ─────────────────────────────────────────────────────
+
+  ${B}${M}Claude Desktop${R}
+  ${D}Add this to:${R} ${C}%APPDATA%\\Claude\\claude_desktop_config.json${R}
+  ${D}(Mac: ~/Library/Application Support/Claude/claude_desktop_config.json)${R}
+
+  ${G}{
+    "mcpServers": {
+      "baby-daemon": {
+        "command": "node",
+        "args": ["${escapedPath}"]
+      }
+    }
+  }${R}
+
+  ${D}Then restart Claude Desktop.${R}
+
+  ─────────────────────────────────────────────────────
+
+  ${B}${M}Cursor${R}
+  ${D}Go to: Settings → MCP → Add Server${R}
+  ${D}Command:${R} ${C}node${R}
+  ${D}Args:${R}    ${C}${mcpServerPath}${R}
+
+  ─────────────────────────────────────────────────────
+
+  ${B}AVAILABLE TOOLS (auto-discovered by AI host):${R}
+    ${C}memory_search${R}    ${D}— Semantic search across all stored memories${R}
+    ${C}memory_store${R}     ${D}— Push text through summarization pipeline${R}
+    ${C}memory_read${R}      ${D}— Full project knowledge briefing${R}
+    ${C}memory_dump${R}      ${D}— Raw memory dump with filters${R}
+    ${C}memory_archive${R}   ${D}— Archive old memories${R}
+
+  ${B}RESOURCE:${R}  ${C}memory://status${R}   ${D}— System health dashboard${R}
+  ${B}PROMPT:${R}    ${C}continue_from_memory${R} ${D}— Context-rich session bootstrap${R}
+  `);
+}

package/bin/memory-watch.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * memory-watch.js  (the CLI entry point)
+ * ────────────────────────────────────────
+ * WHAT THIS FILE DOES:
+ *   This is the file that runs when you type `memory-watch` in the terminal.
+ *   It reads the command-line arguments, validates them, and calls startWatcher().
+ *   It's intentionally tiny — a CLI entry point should ONLY parse args and delegate.
+ *   All real logic lives in src/watcher.js.
+ *
+ * CONCEPT: #!/usr/bin/env node  (the "shebang" line)
+ *   The very first line starting with #! is called a "shebang" (or hashbang).
+ *   On Unix/Mac, when you run a script file directly, the OS reads this line
+ *   to know WHICH program should execute the file.
+ *   #!/usr/bin/env node means: "find 'node' in the PATH and run this file with it"
+ *   On Windows this line is ignored (Node handles it differently via the bin field
+ *   in package.json), but we still include it for cross-platform compatibility.
+ *
+ * CONCEPT: process.argv
+ *   Every Node.js process has a global 'process' object with useful info.
+ *   process.argv is an array of command-line arguments:
+ *     process.argv[0] = path to node executable (e.g., "C:/nodejs/node.exe")
+ *     process.argv[1] = path to the script being run (e.g., "C:/proj101/bin/memory-watch.js")
+ *     process.argv[2] = FIRST argument YOU passed (e.g., "./logs")
+ *     process.argv[3] = second argument (if any)
+ *   So when you run: memory-watch ./logs
+ *   process.argv = ['node', 'memory-watch.js', './logs']
+ *   And process.argv[2] = './logs'
+ *
+ * CONCEPT: ES Module imports
+ *   We use: import { startWatcher } from '../src/watcher.js';
+ *   This is the modern JS module system (ESM).
+ *   The older system (CommonJS) used: const { startWatcher } = require('../src/watcher');
+ *   We use ESM because we set "type": "module" in package.json.
+ *   Key difference: ESM is static (imports resolved at parse time), CJS is dynamic.
+ */
+
+import { startWatcher } from '../src/watcher.js';
+
+// ─────────────────────────────────────────────────────────
+// PARSE ARGUMENTS
+// ─────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+// .slice(2) removes the first two items (node path + script path)
+// leaving only the arguments the user actually typed
+
+// Show help if user runs: memory-watch --help  or  memory-watch -h
+if (args.includes('--help') || args.includes('-h')) {
+  printHelp();
+  process.exit(0);
+}
+
+// The watch path is the first real argument
+const requireApproval = args.includes('--require-approval') || args.includes('-a');
+const watchPath = args.find(arg => !arg.startsWith('-'));
+
+if (!watchPath) {
+  console.error('\n  ✗ Error: No folder path provided.\n');
+  printHelp();
+  process.exit(1);
+}
+
+// ─────────────────────────────────────────────────────────
+// START THE WATCHER
+// ─────────────────────────────────────────────────────────
+
+startWatcher(watchPath, { requireApproval });
+
+// ─────────────────────────────────────────────────────────
+// HELP TEXT
+// ─────────────────────────────────────────────────────────
+
+function printHelp() {
+  console.log(`
+  Baby Daemon — memory-watch (Phase 3)
+
+  USAGE:
+    memory-watch <folder-path> [options]
+
+  OPTIONS:
+    -a, --require-approval    Prompt to confirm or reject each extracted memory
+
+  EXAMPLES:
+    memory-watch ./logs
+    memory-watch ./logs --require-approval
+    memory-watch .            (watch current folder)
+
+  WHAT IT DOES:
+    Watches <folder-path> for new and modified files.
+    Extracts structured memories via Gemini API.
+    Saves memories to memory.jsonl and syncs with LanceDB vector database.
+    Skips duplicates using idempotency fingerprints.
+
+  STOP:
+    Press Ctrl+C to stop the watcher gracefully.
+  `);
+}