@holt-os/holt 0.0.2 → 0.3.0

package/README.md

@@ -6,53 +6,117 @@ Holt is an open-source, self-hosted personal agent OS. Clone it, pick your skill
 
 > A *holt* is a small wood: a sheltered place where things are kept and grow. That's the idea. A private home for your knowledge that compounds over time.
 
-> 🚧 **Status: early development (Phase 0).** The architecture and roadmap are locked and the CLI skeleton is here, but Holt is not yet functional end-to-end. Star or watch to follow along. Contributions welcome.
+> **Status: early but usable, and it remembers now.** `holt init`, `holt chat`, and persistent memory work today. A "brain" is an agent CLI (Claude Code, Codex, or Gemini). Holt can install a missing one for you and hand off to its sign-in, you can switch brains mid-conversation without losing context, and every session adds to a private memory in that folder that future sessions recall from. Skills and the knowledge graph view are the next phases.
 
 ---
 
-## Why Holt
-
-- 🧠 **Memory you can see.** Persistent RAG memory plus a *navigable knowledge graph* of everything you feed it. No black-box profile you have to trust.
-- 🔌 **Any LLM.** Claude, OpenAI, Gemini, or a local model. Swap your brain with one line of config. No vendor lock-in.
-- 💸 **Local executes, cloud reviews.** Run a local model for the work and let a premium cloud model review only the risky, irreversible steps. Cheap and private by design.
-- 🧩 **MCP plugin pantry.** Skills, channels, providers, embeddings: everything is a plugin speaking the [Model Context Protocol](https://modelcontextprotocol.io). Extend it in any language.
-- 📚 **Standard skills.** Compatible with the [agentskills.io](https://agentskills.io) skill format. Pull from the community catalog or publish your own.
-- 🖥️ **CLI-first.** Works in your terminal the moment you clone. Telegram and other channels are opt-in.
-
 ## Quickstart
 
 ```bash
-npm install -g @holt-os/holt   # or: pnpm add -g @holt-os/holt
-holt init                      # pick your brain + memory (local or cloud)
-holt chat                      # start talking
+npm install -g @holt-os/holt
+cd ~/where-you-want-to-work
+holt init      # trust this folder, choose and install brains, sign in, set defaults
+holt chat      # start talking (or use your custom command, e.g. `ai`)
+```
+
+## First run
+
+Holt runs in the folder you launch it from, like a per-project tool. The first time you use a folder it asks:
+
+```
+Trust this folder?
+  /Users/you/where-you-want-to-work
+  Holt will read and write here.
+  Trust and continue? [y/N]
+```
+
+Trusted folders are remembered in `~/.holt/trust.json`. Everything Holt writes for that folder (its config, and later its memory) stays in `<folder>/.holt/`.
+
+During `holt init` you:
+
+1. **Trust the folder.**
+2. **Choose brains** (claude, codex, gemini). Holt installs any you pick that are missing.
+3. **Sign in.** For a newly installed brain, Holt starts that tool's own login (browser or its own prompt). Holt never stores your credentials.
+4. **Pick a default** brain and, optionally, a **launch command** (a short word like `ai` that runs `holt chat`).
+
+## Using it
+
+Inside `holt chat`:
+
+```
+/brain            list your brains and see which is active
+/brain gemini     switch brain. your conversation context is kept
+/memory           memory stats. /memory <query> previews what recall would surface
+/setting          configure brains and your launch command
+/clear            forget this session (saved memory stays)
+/help             show commands
+/exit             leave
 ```
 
-Add skills:
+The point of `/brain`: Holt owns the transcript, so you can start a thread on one model and hand it to another mid-conversation. The new brain picks up with the full context.
+
+## Memory
+
+Every exchange is saved to `<folder>/.holt/memory/turns.jsonl`, private and local. On each message, Holt recalls the most relevant moments from your *past* sessions in that folder and hands them to the brain, so it remembers what you told it last week.
+
+Two recall modes, picked automatically:
+
+- **Semantic** (best): if a local [Ollama](https://ollama.com) is running with an embedding model (`ollama pull nomic-embed-text`), recall matches by meaning. Asking "who owns my apartment" finds "my landlord is called Pieter". No API keys, nothing leaves your machine.
+- **Keyword** (fallback): with no Ollama, recall matches by word overlap. Still useful, zero setup.
+
+Inspect it any time:
 
 ```bash
-holt skill search finance
-holt skill add deep-research
+holt memory                    # stats for this folder
+holt memory search <query>     # find remembered moments
+holt memory clear              # wipe this folder's memory
+```
+
+Long conversations stay cheap: only recent turns are replayed verbatim, older context comes back through recall.
+
+## Brains
+
+A brain is an agent CLI installed and logged in on your machine. No API keys to paste.
+
+| Brain | Command | Install |
+|-------|---------|---------|
+| Claude Code | `claude` | `npm i -g @anthropic-ai/claude-code` |
+| Codex | `codex` | `npm i -g @openai/codex` |
+| Gemini CLI | `gemini` | `npm i -g @google/gemini-cli` |
+
+`holt init` runs these for you when you pick a brain that is missing. You can also sign in any time with `holt login <brain>`. Raw API providers are planned for a later phase.
+
+## Commands
+
+```
+holt init            set up (trust, brains, sign-in, defaults) for this folder
+holt chat            start a session that remembers past ones
+holt memory          inspect memory: holt memory [search <query> | clear]
+holt setting         configure brains and launch command
+holt login <brain>   sign in to claude, codex, or gemini
+holt version         print version
+holt help            show help
 ```
 
 ## Configuration
 
-Copy `config.example.yml` to `config.yml` and edit. See the file for the full schema: brain/provider, memory and embeddings, output format (HTML or Markdown), orchestration, and channels.
+`holt init` writes `<folder>/.holt/config.json` (default brain and enabled brains for that folder). Trusted folders live in `~/.holt/trust.json`. Edit settings with `holt setting`.
 
 ## Architecture
 
-Small strongly-typed **TypeScript core** (agent loop, brain router, memory orchestration, risky-action review gate, plugin dispatcher). *Everything else* is an MCP plugin: providers, embeddings, skills, channels. See [`ARCHITECTURE.md`](./ARCHITECTURE.md).
+Small strongly-typed **TypeScript core** (command dispatch, brain router, transcript, and a plugin dispatcher coming with skills). Brains and, soon, skills and channels are adapters. See [`ARCHITECTURE.md`](./ARCHITECTURE.md).
 
 ## Roadmap
 
 Built in always-shippable phases toward a full-vision v1:
 
-0. **Skeleton**: core loop + CLI *(in progress)*
-1. **Memory**: sqlite-vec RAG + embeddings
-2. **Any-LLM**: provider plugins + output toggle
-3. **Skills**: agentskills.io catalog + installer
-4. **Knowledge graph**: navigable memory view
-5. **Orchestration**: local-executes / cloud-reviews
-6. **Channels + polish**: Telegram, docs, one-command install
+0. **Skeleton and chat**: trust, init with install and sign-in, chat, brain switching with kept context *(shipped)*
+1. **Memory**: per-folder store, semantic recall via local embeddings with keyword fallback, streaming replies *(shipped)*
+2. **Any LLM directly**: raw provider brains and an HTML or Markdown output toggle
+3. **Skills**: install, search, and publish in the agentskills.io format
+4. **Knowledge graph**: a view where you can see and navigate your own memory
+5. **Orchestration**: a local model works, a cloud model reviews the risky steps
+6. **Channels and polish**: Telegram, docs, one-command setup
 
 ## Contributing
 

package/config.example.yml

@@ -1,5 +1,7 @@
-# Holt configuration. Copy to config.yml and edit.
-# config.yml is git-ignored; never commit secrets or personal memory.
+# Planned full configuration schema (later phases). Preview only.
+# Phase 0 does NOT read this file: run `holt init`, which writes
+# ~/.holt/config.json (your brains, default brain, and launch command).
+# Never commit real secrets or personal memory.
 
 # ── Brain ────────────────────────────────────────────────────────────────
 # The LLM that runs the agent. Provider-agnostic: swap freely.

package/dist/cli.js

@@ -1,7 +1,715 @@
 #!/usr/bin/env node
 
+// src/config.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2 } from "fs";
+
+// src/workspace.ts
+import { homedir } from "os";
+import { join } from "path";
+import { mkdirSync, readFileSync, writeFileSync } from "fs";
+
+// src/ui.ts
+import readline from "readline";
+var on = process.stdout.isTTY && !process.env.NO_COLOR;
+var wrap = (code) => (s) => on ? `\x1B[${code}m${s}\x1B[0m` : s;
+var c = {
+  dim: wrap("2"),
+  bold: wrap("1"),
+  accent: wrap("38;5;214"),
+  // amber
+  green: wrap("32"),
+  red: wrap("31"),
+  cyan: wrap("36")
+};
+function createReader() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const buffer = [];
+  const waiters = [];
+  let closed = false;
+  rl.on("line", (line) => {
+    const w = waiters.shift();
+    if (w) w(line);
+    else buffer.push(line);
+  });
+  rl.on("close", () => {
+    closed = true;
+    while (waiters.length) waiters.shift()(null);
+  });
+  const ask = (q) => new Promise((resolve) => {
+    if (q) process.stdout.write(q);
+    if (buffer.length) resolve(buffer.shift());
+    else if (closed) resolve(null);
+    else waiters.push(resolve);
+  });
+  return { ask, close: () => rl.close() };
+}
+
+// src/workspace.ts
+var GLOBAL_DIR = join(homedir(), ".holt");
+var TRUST_PATH = join(GLOBAL_DIR, "trust.json");
+function workspace() {
+  return process.cwd();
+}
+function wsHoltDir(dir = workspace()) {
+  return join(dir, ".holt");
+}
+function wsConfigPath(dir = workspace()) {
+  return join(wsHoltDir(dir), "config.json");
+}
+function readTrust() {
+  try {
+    return JSON.parse(readFileSync(TRUST_PATH, "utf8"));
+  } catch {
+    return { trusted: [] };
+  }
+}
+function isTrusted(dir = workspace()) {
+  return readTrust().trusted.includes(dir);
+}
+function trustDir(dir = workspace()) {
+  const t = readTrust();
+  if (!t.trusted.includes(dir)) t.trusted.push(dir);
+  mkdirSync(GLOBAL_DIR, { recursive: true });
+  writeFileSync(TRUST_PATH, JSON.stringify(t, null, 2) + "\n", "utf8");
+}
+async function ensureTrusted(ask) {
+  const ws = workspace();
+  if (isTrusted(ws)) return true;
+  console.log("\n" + c.accent("Trust this folder?"));
+  console.log("  " + ws);
+  console.log(c.dim("  Holt will read and write here: its config, memory, and any files you ask a brain to touch."));
+  const ans = (await ask("  Trust and continue? [y/N] ") ?? "").trim().toLowerCase();
+  if (ans === "y" || ans === "yes") {
+    trustDir(ws);
+    console.log(c.green("  Trusted.") + c.dim(" (remembered for next time)") + "\n");
+    return true;
+  }
+  console.log(c.dim("  Cancelled. Holt only runs in folders you trust.\n"));
+  return false;
+}
+function ensureWsDir() {
+  mkdirSync(wsHoltDir(), { recursive: true });
+}
+
+// src/config.ts
+var BRAIN_DEFS = {
+  claude: { label: "Claude Code", command: "claude", args: ["-p"] },
+  codex: { label: "Codex (OpenAI)", command: "codex", args: ["exec"] },
+  gemini: { label: "Gemini CLI", command: "gemini", args: ["-p"] }
+};
+var BRAIN_SETUP = {
+  claude: { install: ["npm", "install", "-g", "@anthropic-ai/claude-code"], login: ["claude"] },
+  codex: { install: ["npm", "install", "-g", "@openai/codex"], login: ["codex", "login"] },
+  gemini: { install: ["npm", "install", "-g", "@google/gemini-cli"], login: ["gemini"] }
+};
+var BRAIN_IDS = ["claude", "codex", "gemini"];
+function defaultConfig() {
+  const brains = {};
+  for (const id of BRAIN_IDS) {
+    const d = BRAIN_DEFS[id];
+    brains[id] = { id, label: d.label, command: d.command, args: [...d.args], enabled: false };
+  }
+  return { version: 2, defaultBrain: null, brains };
+}
+function loadConfig() {
+  const path = wsConfigPath();
+  if (!existsSync2(path)) return null;
+  try {
+    const cfg = JSON.parse(readFileSync2(path, "utf8"));
+    const base = defaultConfig();
+    for (const id of BRAIN_IDS) if (!cfg.brains?.[id]) cfg.brains[id] = base.brains[id];
+    return cfg;
+  } catch {
+    return null;
+  }
+}
+function saveConfig(cfg) {
+  ensureWsDir();
+  writeFileSync2(wsConfigPath(), JSON.stringify(cfg, null, 2) + "\n", "utf8");
+}
+
+// src/brains.ts
+import { spawn, spawnSync } from "child_process";
+var MAX_REPLAY_TURNS = 12;
+function isInstalled(command) {
+  const finder = process.platform === "win32" ? "where" : "which";
+  const res = spawnSync(finder, [command], { stdio: "ignore" });
+  return res.status === 0;
+}
+function renderPrompt(history, message, memory = []) {
+  const recent = history.slice(-MAX_REPLAY_TURNS);
+  const parts = [];
+  if (recent.length || memory.length) {
+    parts.push(
+      "You are continuing an ongoing conversation. Use the context below and reply only as the assistant to the final User message."
+    );
+  }
+  if (memory.length) {
+    parts.push(
+      "",
+      "Relevant notes from this user's earlier sessions:",
+      ...memory.map((m) => `- (${m.turn.role}) ${m.turn.content.slice(0, 500)}`)
+    );
+  }
+  if (recent.length) {
+    parts.push("", "Transcript so far:", ...recent.map((t) => `${t.role === "user" ? "User" : "Assistant"}: ${t.content}`));
+  }
+  if (parts.length === 0) return message;
+  parts.push("", `User: ${message}`, "", "Assistant:");
+  return parts.join("\n");
+}
+function runBrain(brain, prompt, onChunk) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(brain.command, [...brain.args, prompt], { stdio: ["ignore", "pipe", "pipe"] });
+    } catch (e) {
+      resolve({ ok: false, text: `Could not launch "${brain.command}": ${e.message}` });
+      return;
+    }
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (d) => {
+      const s = d.toString();
+      out += s;
+      if (onChunk) onChunk(s);
+    });
+    child.stderr.on("data", (d) => {
+      err += d.toString();
+    });
+    child.on("error", (e) => resolve({ ok: false, text: `Could not run "${brain.command}": ${e.message}` }));
+    child.on("close", (code) => {
+      const text = out.trim();
+      if (code === 0 && text) resolve({ ok: true, text });
+      else resolve({ ok: false, text: err.trim() || text || `"${brain.command}" exited with code ${code}` });
+    });
+  });
+}
+
+// src/alias.ts
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync3, existsSync as existsSync3 } from "fs";
+var START = "# >>> holt launch alias >>>";
+var END = "# <<< holt launch alias <<<";
+function rcFile() {
+  const shell = process.env.SHELL || "";
+  if (shell.includes("zsh")) return join2(homedir2(), ".zshrc");
+  if (shell.includes("bash")) return join2(homedir2(), ".bashrc");
+  return join2(homedir2(), ".profile");
+}
+function installAlias(name) {
+  const file = rcFile();
+  const block = `${START}
+alias ${name}="holt chat"
+${END}`;
+  try {
+    let content = existsSync3(file) ? readFileSync3(file, "utf8") : "";
+    const re = new RegExp(`${START}[\\s\\S]*?${END}`);
+    if (re.test(content)) content = content.replace(re, block);
+    else content = content.replace(/\n*$/, "\n") + block + "\n";
+    writeFileSync3(file, content, "utf8");
+    return { ok: true, file };
+  } catch (e) {
+    return { ok: false, file, message: `Could not write ${file}: ${e.message}` };
+  }
+}
+function currentAlias() {
+  const file = rcFile();
+  try {
+    const m = readFileSync3(file, "utf8").match(/alias\s+([^\s=]+)="holt chat"/);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+function removeAlias() {
+  const file = rcFile();
+  try {
+    if (existsSync3(file)) {
+      const content = readFileSync3(file, "utf8").replace(new RegExp(`\\n*${START}[\\s\\S]*?${END}\\n*`), "\n");
+      writeFileSync3(file, content, "utf8");
+    }
+    return { ok: true, file };
+  } catch (e) {
+    return { ok: false, file, message: e.message };
+  }
+}
+
+// src/install.ts
+import { spawn as spawn2 } from "child_process";
+function runInteractive(cmd, args) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn2(cmd, args, { stdio: "inherit" });
+    } catch {
+      resolve(-1);
+      return;
+    }
+    child.on("error", () => resolve(-1));
+    child.on("close", (code) => resolve(code ?? -1));
+  });
+}
+
+// src/commands/init.ts
+function parseBrains(raw, found) {
+  const s = raw.trim().toLowerCase();
+  if (s === "") return found.length ? found : [...BRAIN_IDS];
+  if (s === "all") return [...BRAIN_IDS];
+  const picked = s.split(/[\s,]+/).filter((x) => BRAIN_IDS.includes(x));
+  if (picked.length) return [...new Set(picked)];
+  return found.length ? found : ["claude"];
+}
+async function init() {
+  const { ask, close } = createReader();
+  if (!await ensureTrusted(ask)) {
+    close();
+    return;
+  }
+  console.log(c.accent("Holt setup") + c.dim(`  (${workspace()})`) + "\n");
+  console.log("Looking for agent CLIs on your machine...\n");
+  const found = [];
+  for (const id of BRAIN_IDS) {
+    const ok = isInstalled(BRAIN_DEFS[id].command);
+    console.log(`  ${ok ? c.green("found  ") : c.dim("missing")}  ${BRAIN_DEFS[id].label} (${BRAIN_DEFS[id].command})`);
+    if (ok) found.push(id);
+  }
+  console.log("");
+  const chosen = parseBrains(
+    await ask('Which brains do you want? claude, codex, gemini (comma-separated, or "all"): ') ?? "",
+    found
+  );
+  console.log(c.dim(`  using: ${chosen.join(", ")}`));
+  const toInstall = chosen.filter((id) => !isInstalled(BRAIN_DEFS[id].command));
+  const loginWanted = /* @__PURE__ */ new Set();
+  for (const id of toInstall) {
+    const a = (await ask(`  ${BRAIN_DEFS[id].label} is not installed. Sign in after install? [Y/n] `) ?? "").trim().toLowerCase();
+    if (a !== "n" && a !== "no") loginWanted.add(id);
+  }
+  const defPick = chosen.includes("claude") ? "claude" : chosen[0];
+  const dans = (await ask(`
+Default brain? [${chosen.join("/")}] (${defPick}): `) ?? "").trim();
+  const defaultBrain = chosen.includes(dans) ? dans : defPick;
+  const aliasAns = (await ask('Launch command? Type a custom word like "ai", or press enter to keep "holt": ') ?? "").trim();
+  let aliasNote = "";
+  if (aliasAns && aliasAns !== "holt") {
+    if (isInstalled(aliasAns)) console.log(c.dim(`  note: "${aliasAns}" already exists; the alias will shadow it in new shells.`));
+    const r = installAlias(aliasAns);
+    aliasNote = r.ok ? c.green(`  alias "${aliasAns}" -> holt chat added to ${r.file} (run: source ${r.file})`) : c.red("  " + r.message);
+  }
+  close();
+  for (const id of toInstall) {
+    const s = BRAIN_SETUP[id];
+    console.log("\n" + c.accent(`Installing ${BRAIN_DEFS[id].label}`) + c.dim(`  (${s.install.join(" ")})`));
+    const code = await runInteractive(s.install[0], s.install.slice(1));
+    console.log(code === 0 ? c.green(`  ${BRAIN_DEFS[id].label} installed.`) : c.red(`  Install failed (exit ${code}). Run manually: ${s.install.join(" ")}`));
+  }
+  for (const id of toInstall) {
+    if (!loginWanted.has(id) || !isInstalled(BRAIN_DEFS[id].command)) continue;
+    const s = BRAIN_SETUP[id];
+    console.log("\n" + c.accent(`Sign in to ${BRAIN_DEFS[id].label}`));
+    console.log(c.dim(`  Starting "${s.login.join(" ")}". Complete sign-in, then exit that tool to return here.`));
+    await runInteractive(s.login[0], s.login.slice(1));
+  }
+  const cfg = loadConfig() ?? defaultConfig();
+  for (const id of BRAIN_IDS) cfg.brains[id].enabled = chosen.includes(id) && isInstalled(BRAIN_DEFS[id].command);
+  cfg.defaultBrain = cfg.brains[defaultBrain].enabled ? defaultBrain : BRAIN_IDS.find((id) => cfg.brains[id].enabled) ?? null;
+  saveConfig(cfg);
+  console.log("\n" + c.green("Saved to ./.holt/config.json"));
+  if (aliasNote) console.log(aliasNote);
+  if (cfg.defaultBrain) console.log("Start chatting:  " + c.accent(aliasAns && aliasAns !== "holt" ? aliasAns : "holt chat") + "\n");
+  else console.log(c.dim('No brain is ready yet. Install one, then run "holt init" again.\n'));
+}
+
+// src/commands/chat.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/memory.ts
+import { appendFileSync, readFileSync as readFileSync4, existsSync as existsSync4, mkdirSync as mkdirSync2, rmSync, statSync } from "fs";
+import { join as join3 } from "path";
+import { randomUUID } from "crypto";
+var OLLAMA_URL = process.env.HOLT_OLLAMA_URL || "http://127.0.0.1:11434";
+var EMBED_MODEL = process.env.HOLT_EMBED_MODEL || "nomic-embed-text";
+function memDir() {
+  return join3(wsHoltDir(), "memory");
+}
+function memPath() {
+  return join3(memDir(), "turns.jsonl");
+}
+function newSessionId() {
+  return randomUUID().slice(0, 8);
+}
+var embedProbe = null;
+async function embeddingsAvailable() {
+  if (embedProbe !== null) return embedProbe;
+  try {
+    const res = await fetch(`${OLLAMA_URL}/api/tags`, { signal: AbortSignal.timeout(1200) });
+    if (!res.ok) return embedProbe = false;
+    const data = await res.json();
+    embedProbe = !!data.models?.some((m) => (m.name || "").startsWith(EMBED_MODEL));
+  } catch {
+    embedProbe = false;
+  }
+  return embedProbe;
+}
+async function embed(text) {
+  if (!await embeddingsAvailable()) return null;
+  try {
+    const res = await fetch(`${OLLAMA_URL}/api/embeddings`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ model: EMBED_MODEL, prompt: text.slice(0, 4e3) }),
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!res.ok) return null;
+    const data = await res.json();
+    if (!Array.isArray(data.embedding)) return null;
+    return data.embedding.map((x) => Math.round(x * 1e4) / 1e4);
+  } catch {
+    return null;
+  }
+}
+function loadTurns() {
+  if (!existsSync4(memPath())) return [];
+  const out = [];
+  for (const line of readFileSync4(memPath(), "utf8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      out.push(JSON.parse(line));
+    } catch {
+    }
+  }
+  return out;
+}
+function appendTurn(t) {
+  mkdirSync2(memDir(), { recursive: true });
+  appendFileSync(memPath(), JSON.stringify(t) + "\n", "utf8");
+}
+function clearMemory() {
+  if (existsSync4(memPath())) rmSync(memPath());
+}
+function memStats() {
+  const turns = loadTurns();
+  const sessions = new Set(turns.map((t) => t.session)).size;
+  const withEmbeddings = turns.filter((t) => Array.isArray(t.emb)).length;
+  const bytes = existsSync4(memPath()) ? statSync(memPath()).size : 0;
+  return { turns: turns.length, sessions, withEmbeddings, bytes };
+}
+function cosine(a, b) {
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    const x = a[i];
+    const y = b[i];
+    dot += x * y;
+    na += x * x;
+    nb += y * y;
+  }
+  return na && nb ? dot / (Math.sqrt(na) * Math.sqrt(nb)) : 0;
+}
+function tokens(s) {
+  return new Set(
+    s.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 2)
+  );
+}
+function keywordScore(q, text) {
+  if (q.size === 0) return 0;
+  const t = tokens(text);
+  let hit = 0;
+  for (const w of q) if (t.has(w)) hit++;
+  return hit / q.size;
+}
+async function recall(query, currentSession, k = 4) {
+  const past = loadTurns().filter((t) => t.session !== currentSession);
+  if (past.length === 0) return [];
+  const qEmb = await embed(query);
+  const qTok = tokens(query);
+  const scored = [];
+  for (const turn of past) {
+    let score = 0;
+    if (qEmb && Array.isArray(turn.emb)) score = cosine(qEmb, turn.emb);
+    else score = keywordScore(qTok, turn.content);
+    if (score > (qEmb && Array.isArray(turn.emb) ? 0.35 : 0.15)) scored.push({ turn, score });
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, k);
+}
+
+// src/commands/setting.ts
+function printStatus(cfg) {
+  console.log("\n" + c.accent("Holt settings") + c.dim("  (this folder)"));
+  for (const id of BRAIN_IDS) {
+    const b = cfg.brains[id];
+    const tags = [
+      b.enabled ? c.green("enabled") : isInstalled(b.command) ? c.dim("installed, off") : c.dim("not installed"),
+      cfg.defaultBrain === id ? c.accent("default") : ""
+    ].filter(Boolean).join("  ");
+    console.log(`  ${id.padEnd(7)} ${b.label.padEnd(16)} ${tags}`);
+  }
+  console.log(c.dim(`  launch command: ${currentAlias() || "holt (default)"}`));
+  console.log("\n  " + c.dim("[d] default brain   [t] toggle brain   [a] launch command   [enter] done"));
+}
+async function runSettings(ask) {
+  let cfg = loadConfig() ?? defaultConfig();
+  while (true) {
+    printStatus(cfg);
+    const raw = await ask("  > ");
+    const choice = (raw ?? "").trim().toLowerCase();
+    if (raw === null || choice === "" || choice === "q") break;
+    if (choice === "d") {
+      const enabled = BRAIN_IDS.filter((id) => cfg.brains[id].enabled);
+      if (enabled.length === 0) {
+        console.log(c.dim('  No enabled brains. Toggle one on first with "t".'));
+        continue;
+      }
+      const pick = (await ask(`  default brain [${enabled.join("/")}]: `) ?? "").trim();
+      if (enabled.includes(pick)) {
+        cfg.defaultBrain = pick;
+        console.log(c.green(`  default set to ${cfg.brains[pick].label}`));
+      } else console.log(c.dim("  unchanged."));
+    } else if (choice === "t") {
+      const pick = (await ask(`  toggle which brain [${BRAIN_IDS.join("/")}]: `) ?? "").trim();
+      if (BRAIN_IDS.includes(pick)) {
+        if (!cfg.brains[pick].enabled && !isInstalled(cfg.brains[pick].command)) {
+          console.log(c.dim(`  ${cfg.brains[pick].label} is not installed. Run "holt init" to install it.`));
+        } else {
+          cfg.brains[pick].enabled = !cfg.brains[pick].enabled;
+          if (!cfg.brains[pick].enabled && cfg.defaultBrain === pick) cfg.defaultBrain = BRAIN_IDS.find((id) => cfg.brains[id].enabled) ?? null;
+          if (cfg.brains[pick].enabled && !cfg.defaultBrain) cfg.defaultBrain = pick;
+          console.log(c.dim(`  ${cfg.brains[pick].label} is now ${cfg.brains[pick].enabled ? "on" : "off"}.`));
+        }
+      } else console.log(c.dim("  unchanged."));
+    } else if (choice === "a") {
+      const name = (await ask("  launch command (blank to reset to holt): ") ?? "").trim();
+      if (name && name !== "holt") {
+        if (isInstalled(name)) console.log(c.dim(`  note: "${name}" already exists; the alias will shadow it in new shells.`));
+        const r = installAlias(name);
+        console.log(r.ok ? c.green(`  alias "${name}" -> holt chat added to ${r.file} (run: source ${r.file})`) : c.red("  " + r.message));
+      } else {
+        removeAlias();
+        console.log(c.dim("  reset to holt."));
+      }
+    } else {
+      console.log(c.dim("  pick d, t, a, or press enter to finish."));
+    }
+    saveConfig(cfg);
+  }
+  saveConfig(cfg);
+  return cfg;
+}
+async function setting() {
+  const { ask, close } = createReader();
+  if (!await ensureTrusted(ask)) {
+    close();
+    return;
+  }
+  await runSettings(ask);
+  close();
+  console.log("");
+}
+
+// src/commands/chat.ts
+function help() {
+  console.log(c.dim([
+    "  commands:",
+    "    /brain [name]     switch brain (claude, codex, gemini). context is kept.",
+    "    /memory [query]   memory stats, or preview what a query would recall",
+    "    /setting          configure brains and your launch command",
+    "    /clear            forget this session so far (saved memory stays)",
+    "    /help             this list",
+    "    /exit             leave"
+  ].join("\n")));
+}
+async function chat() {
+  const { ask, close } = createReader();
+  if (!await ensureTrusted(ask)) {
+    close();
+    return;
+  }
+  let cfg = loadConfig();
+  if (!cfg || !cfg.defaultBrain) {
+    const a = (await ask(c.dim("No Holt setup in this folder. Set it up now? [Y/n] ")) ?? "").trim().toLowerCase();
+    close();
+    if (a === "n" || a === "no") {
+      console.log(c.dim('  Run "holt init" here when ready.\n'));
+      return;
+    }
+    await init();
+    console.log(c.dim('\nSetup done. Run "holt chat" to start talking.\n'));
+    return;
+  }
+  let current = cfg.defaultBrain;
+  const session = newSessionId();
+  const history = [];
+  const embedOk = await embeddingsAvailable();
+  const stats = memStats();
+  console.log("\n" + c.accent("Holt") + c.dim(`  brain: ${cfg.brains[current].label}`));
+  console.log(c.dim(
+    `Memory: ${stats.turns} moments from ${stats.sessions} session${stats.sessions === 1 ? "" : "s"} in this folder (recall: ${embedOk ? "embeddings via local Ollama" : "keyword match"}).`
+  ));
+  console.log(c.dim("Type a message. Commands: /brain  /memory  /setting  /clear  /help  /exit\n"));
+  while (true) {
+    const raw = await ask(c.accent("\u203A "));
+    if (raw === null) break;
+    const line = raw.trim();
+    if (!line) continue;
+    if (line.startsWith("/")) {
+      const parts = line.slice(1).split(/\s+/);
+      const cmd = (parts[0] || "").toLowerCase();
+      const rest = parts.slice(1).join(" ");
+      const arg = (parts[1] || "").toLowerCase();
+      if (cmd === "exit" || cmd === "quit" || cmd === "q") break;
+      if (cmd === "help" || cmd === "h") {
+        help();
+        continue;
+      }
+      if (cmd === "clear") {
+        history.length = 0;
+        console.log(c.dim("  session context cleared. Saved memory is untouched."));
+        continue;
+      }
+      if (cmd === "memory" || cmd === "mem") {
+        if (rest) {
+          const hits = await recall(rest, session, 5);
+          if (hits.length === 0) console.log(c.dim("  nothing relevant in memory for that."));
+          else for (const h of hits) console.log(c.dim(`  ${h.score.toFixed(2)}  (${h.turn.role}) ${h.turn.content.slice(0, 110).replace(/\s+/g, " ")}`));
+        } else {
+          const s = memStats();
+          console.log(c.dim(`  ${s.turns} moments, ${s.sessions} sessions, ${s.withEmbeddings} embedded, ${(s.bytes / 1024).toFixed(1)} KB in ./.holt/memory/`));
+          console.log(c.dim('  usage: /memory <query> to preview recall, or "holt memory clear" to wipe.'));
+        }
+        continue;
+      }
+      if (cmd === "setting" || cmd === "settings") {
+        cfg = await runSettings(ask);
+        if (!cfg.brains[current].enabled && cfg.defaultBrain) current = cfg.defaultBrain;
+        console.log(c.dim(`  brain: ${cfg.brains[current].label}`));
+        continue;
+      }
+      if (cmd === "brain") {
+        const enabled = BRAIN_IDS.filter((id) => cfg.brains[id].enabled);
+        if (arg && enabled.includes(arg)) {
+          current = arg;
+          const turns = Math.floor(history.length / 2);
+          console.log(c.green(`  switched to ${cfg.brains[current].label}. Context kept (${turns} turn${turns === 1 ? "" : "s"}).`));
+        } else if (arg) {
+          console.log(c.dim(`  "${arg}" is not available. Installed: ${enabled.join(", ") || "none"}`));
+        } else {
+          console.log(c.dim("  brains: " + enabled.map((id) => id === current ? c.accent(id + " (current)") : id).join("  ")));
+          console.log(c.dim("  usage: /brain <name>"));
+        }
+        continue;
+      }
+      console.log(c.dim(`  unknown command: /${cmd}  (try /help)`));
+      continue;
+    }
+    const brain = cfg.brains[current];
+    if (!isInstalled(brain.command)) {
+      console.log(c.red(`  ${brain.label} (${brain.command}) is not on your PATH. Use /brain to switch or /setting.`));
+      continue;
+    }
+    const remembered = await recall(line, session, 4);
+    const label = remembered.length ? `${brain.label} is thinking (recalled ${remembered.length} moment${remembered.length === 1 ? "" : "s"})...` : `${brain.label} is thinking...`;
+    console.log(c.dim(`  ${label}`) + "\n");
+    let streamed = false;
+    const res = await runBrain(brain, renderPrompt(history, line, remembered), (chunk) => {
+      streamed = true;
+      process.stdout.write(chunk);
+    });
+    if (res.ok) {
+      if (!streamed) console.log(res.text);
+      if (!res.text.endsWith("\n")) console.log("");
+      console.log("");
+      history.push({ role: "user", content: line });
+      history.push({ role: "assistant", content: res.text });
+      const now = Date.now();
+      appendTurn({ id: randomUUID2().slice(0, 8), ts: now, session, role: "user", content: line, emb: await embed(line) ?? void 0 });
+      appendTurn({ id: randomUUID2().slice(0, 8), ts: now, session, role: "assistant", content: res.text, emb: await embed(res.text) ?? void 0 });
+    } else {
+      console.log(c.red("\n  " + res.text + "\n"));
+    }
+  }
+  close();
+  console.log(c.dim("\nBye.\n"));
+}
+
+// src/commands/login.ts
+async function login(which) {
+  const id = (which || "").toLowerCase();
+  if (!BRAIN_IDS.includes(id)) {
+    console.log(c.dim(`
+  Usage: holt login <${BRAIN_IDS.join("|")}>
+`));
+    return;
+  }
+  const s = BRAIN_SETUP[id];
+  console.log("\n" + c.accent(`Sign in to ${BRAIN_DEFS[id].label}`));
+  console.log(c.dim(`  Starting "${s.login.join(" ")}". Complete sign-in, then exit that tool.
+`));
+  await runInteractive(s.login[0], s.login.slice(1));
+}
+
+// src/commands/memory.ts
+async function memoryCmd(sub, rest = []) {
+  const { ask, close } = createReader();
+  if (!await ensureTrusted(ask)) {
+    close();
+    return;
+  }
+  const action = (sub || "").toLowerCase();
+  if (action === "clear") {
+    const s2 = memStats();
+    if (s2.turns === 0) {
+      console.log(c.dim("\n  Memory is already empty.\n"));
+      close();
+      return;
+    }
+    const a = (await ask(`
+  Delete all ${s2.turns} remembered moments in this folder? [y/N] `) ?? "").trim().toLowerCase();
+    if (a === "y" || a === "yes") {
+      clearMemory();
+      console.log(c.green("  Memory cleared.\n"));
+    } else console.log(c.dim("  Kept.\n"));
+    close();
+    return;
+  }
+  if (action === "search") {
+    const q = rest.join(" ").trim();
+    if (!q) {
+      console.log(c.dim("\n  Usage: holt memory search <query>\n"));
+      close();
+      return;
+    }
+    const hits = await recall(q, "__none__", 8);
+    console.log("");
+    if (hits.length === 0) console.log(c.dim("  Nothing relevant found."));
+    else for (const h of hits) {
+      const when = new Date(h.turn.ts).toISOString().slice(0, 10);
+      console.log(`  ${c.accent(h.score.toFixed(2))}  ${c.dim(when)}  (${h.turn.role}) ${h.turn.content.slice(0, 100).replace(/\s+/g, " ")}`);
+    }
+    console.log("");
+    close();
+    return;
+  }
+  const s = memStats();
+  const embedOk = await embeddingsAvailable();
+  const sessions = new Set(loadTurns().map((t) => t.session)).size;
+  console.log("\n" + c.accent("Holt memory") + c.dim("  (this folder)"));
+  console.log(`  moments     ${s.turns}`);
+  console.log(`  sessions    ${sessions}`);
+  console.log(`  embedded    ${s.withEmbeddings} of ${s.turns}`);
+  console.log(`  size        ${(s.bytes / 1024).toFixed(1)} KB  (./.holt/memory/turns.jsonl)`);
+  console.log(`  recall via  ${embedOk ? "embeddings (local Ollama)" : "keyword match (start Ollama with an embed model for semantic recall)"}`);
+  console.log(c.dim("\n  holt memory search <query>   find remembered moments"));
+  console.log(c.dim("  holt memory clear            wipe this folder's memory\n"));
+  close();
+}
+
 // src/cli.ts
-var VERSION = "0.0.1";
+var VERSION = "0.3.0";
 var BANNER = `
   \u2588\u2588\u2557  \u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2557  \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557
   \u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2551  \u255A\u2550\u2550\u2588\u2588\u2554\u2550\u2550\u255D
@@ -12,27 +720,25 @@ var BANNER = `
   Everything you know, kept and connected.
 `;
 var HELP = `${BANNER}
-Usage: holt <command> [options]
+Usage: holt <command>
 
 Commands:
-  init            Set up your brain (LLM) and memory (local or cloud)
-  chat            Start an interactive session
-  skill <cmd>     Manage skills: search | add | remove | list | publish
+  init            Trust this folder, choose and install brains, sign in, set defaults
+  chat            Start a session. It remembers past sessions in this folder
+  memory          Inspect memory: holt memory [search <query> | clear]
+  setting         Configure brains and your launch command (per folder)
+  login <brain>   Sign in to a brain: claude, codex, or gemini
   version         Print the Holt version
   help            Show this help
 
+Holt runs in the folder you launch it from and asks to trust it first.
+Brains are the agent CLIs on your machine: claude (Claude Code), codex, gemini.
+
 Docs: https://productsdecoded.com/holt
 Repo: https://github.com/holt-os/holt
-
-Holt is in early development (Phase 0). Most commands are not wired up yet.
 `;
-function notReady(cmd) {
-  console.log(`
-  "${cmd}" is not implemented yet. Holt is in Phase 0 (skeleton).`);
-  console.log("  Follow progress: https://github.com/holt-os/holt\n");
-}
-function main(argv) {
-  const [cmd, ...rest] = argv;
+async function main() {
+  const cmd = process.argv[2];
   switch (cmd) {
     case void 0:
     case "help":
@@ -46,9 +752,20 @@ function main(argv) {
       console.log(`holt ${VERSION}`);
       break;
     case "init":
+      await init();
+      break;
     case "chat":
-    case "skill":
-      notReady([cmd, ...rest].join(" "));
+      await chat();
+      break;
+    case "setting":
+    case "settings":
+      await setting();
+      break;
+    case "login":
+      await login(process.argv[3]);
+      break;
+    case "memory":
+      await memoryCmd(process.argv[3], process.argv.slice(4));
       break;
     default:
       console.log(`
@@ -58,4 +775,4 @@ function main(argv) {
       process.exitCode = 1;
   }
 }
-main(process.argv.slice(2));
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holt-os/holt",
-  "version": "0.0.2",
+  "version": "0.3.0",
   "description": "An open-source personal agent OS: any LLM, private memory you can see and walk.",
   "type": "module",
   "license": "MIT",