open-think 0.1.14 → 0.2.1

package/README.md

@@ -25,33 +25,76 @@ think summary
 think summary --last-week --raw   # raw entries, no AI
 ```
 
+## Local-first architecture
+
+All reads and writes go to local SQLite. Sync is optional and eventual — your agents work fully offline.
+
+```
+  your machine                          remote (optional)
+  ─────────────                         ────────────────
+  entries → engrams → curator → memories  ⇄  git | pg*
+                      (local AI)
+```
+
+Engrams (raw events) never leave your machine. Only curated memories sync to the backend you choose.
+
+*Postgres adapter coming soon.*
+
 ## Cortex — shared team memory
 
-Cortexes connect agents across a team via a shared git repo. Engrams (raw events) stay local. A curator agent evaluates them and appends curated memories to the repo.
+Cortexes are memory workspaces. Each has its own engrams, memories, and sync state.
 
 ```bash
 # Set up (once)
 think cortex setup git@github.com:org/hivedb.git
 think cortex create engineering
 
-# Work normally — think sync logs engrams locally
+# Work normally — syncs log engrams locally
 think sync "deployed auth service to staging"
 
-# Curate — evaluate engrams, append memories to the branch
+# Curate — evaluate engrams, promote memories
 think curate              # full run
-think curate --dry-run    # preview without pushing
+think curate --dry-run    # preview without saving
 
 # Read team memories
 think recall "auth"       # search memories + local engrams
-think memory              # show all memories from branch
+think memory              # show all memories
+
+# Sync with remote
+think cortex push         # push local memories to remote
+think cortex pull         # pull remote memories to local
+think cortex sync         # push + pull
+think cortex status       # show sync state
 
 # Monitor curation quality
 think monitor             # what got promoted vs dropped
 
-# Pull another team's memories
+# Read another team's memories
 think pull product
 ```
 
+Cortexes work without a remote — `think cortex setup` with no repo URL creates an offline-only workspace.
+
+## Episodes — narrative memory for task agents
+
+Episodes let task-oriented agents (review bots, bug fixers, deploy agents) accumulate work across multiple rounds and synthesize it into a single narrative memory.
+
+```bash
+# Tag engrams with an episode key
+think sync -e "org/repo#42" "found SQL injection in auth middleware"
+think sync -e "org/repo#42" "author fixed queries but missed token rotation"
+think sync -e "org/repo#42" "all paths encrypted, approved"
+
+# Synthesize into a narrative memory
+think curate --episode "org/repo#42"
+```
+
+Episode curation produces stories, not logs:
+
+> *"A code review was opened against the auth middleware rewrite. The initial review identified plaintext session token storage — a direct violation of the encryption-at-rest requirement from the engineering standards doc. The author addressed this but missed the token rotation endpoint. After a third round, all session paths were encrypted and rotation was confirmed working."*
+
+Re-curating after new rounds updates the existing narrative rather than creating a duplicate.
+
 ### Privacy
 
 ```bash
@@ -70,39 +113,52 @@ think curator show    # print current guidance
 
 ## Data
 
-- **Engrams:** `~/.local/share/think/think.db` (no cortex) or `~/.think/engrams/<cortex>.db`
+- **Cortex DB:** `~/.think/engrams/<cortex>.db` (engrams, memories, sync state — all in one SQLite file)
 - **Config:** `~/.config/think/config.json`
 - **Curator guidance:** `~/.think/curator.md`
-- **Memories:** `memories.jsonl` on cortex git branches (append-only JSONL)
+- **Entries (no cortex):** `~/.local/share/think/think.db`
+
+Override the data directory with `$THINK_HOME`.
 
 ## All commands
 
 ```
 think sync <message>           Log a work event
+think sync -e <key> <message>  Log an episode-tagged event
 think log <message>            Log a note (with --category, --tags)
 think list                     List entries (--week, --since, --category)
 think summary                  AI summary (--raw for plain text)
 think delete                   Soft-delete entries
 
-think cortex setup <repo>      Configure git repo for shared memory
-think cortex create <name>     Create a cortex branch
-think cortex list              Show cortex branches
+think cortex setup [repo]      Configure sync backend (or offline-only)
+think cortex create <name>     Create a cortex
+think cortex list              Show all cortexes (local + remote)
 think cortex switch <name>     Set active cortex
 think cortex current           Show active cortex
+think cortex push              Push local memories to remote
+think cortex pull              Pull remote memories to local
+think cortex sync              Push + pull
+think cortex status            Show sync state
 
 think curate                   Run curation (--dry-run to preview)
+think curate --episode <key>   Curate an episode into a narrative memory
+think curate --consolidate     Compress older memories into long-term summary
 think monitor                  Show promoted vs dropped engrams
 think recall <query>           Search memories + engrams
-think memory                   Show memories (--history for git log)
-think pull <cortex>            Pull another cortex's memories
+think memory                   Show memories (--history for timeline)
+think pull <cortex>            Read another cortex's memories
 
 think curator edit             Edit personal curator guidance
 think curator show             Show current guidance
 think pause                    Suppress engram creation
 think resume                   Re-enable engram creation
 
+think migrate-data             Import existing git memories into local SQLite
 think init                     Set up CLAUDE.md for auto-logging
 think export                   Export entries as sync bundle
 think import <file>            Import sync bundle
 think audit                    Show sync audit log
+think config show              Print configuration
+think config set <key> <val>   Update a config value
+think update                   Update to latest version
 ```

package/dist/chunk-K2FT7ZHJ.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node --no-warnings=ExperimentalWarning
+
+// src/lib/git.ts
+import { execFileSync } from "child_process";
+import fs3 from "fs";
+import path3 from "path";
+
+// src/lib/paths.ts
+import path from "path";
+import fs from "fs";
+function getHome() {
+  const home = process.env.HOME;
+  if (!home) {
+    throw new Error("HOME environment variable is not set");
+  }
+  return home;
+}
+function sanitizeName(name) {
+  if (!name || /[\/\\\.]{2}/.test(name) || /[^a-zA-Z0-9_-]/.test(name)) {
+    throw new Error(`Invalid cortex name: "${name}". Use only alphanumeric characters, hyphens, and underscores.`);
+  }
+  return name;
+}
+function getThinkHome() {
+  const thinkHome = process.env.THINK_HOME;
+  if (thinkHome === void 0 || thinkHome === "") return null;
+  return thinkHome;
+}
+function getThinkDir() {
+  return getThinkHome() ?? path.join(getHome(), ".think");
+}
+function getThinkConfigDir() {
+  const thinkHome = getThinkHome();
+  if (thinkHome) return path.join(thinkHome, "config");
+  const xdgConfig = process.env.XDG_CONFIG_HOME || path.join(getHome(), ".config");
+  return path.join(xdgConfig, "think");
+}
+function getThinkDataDir() {
+  const thinkHome = getThinkHome();
+  if (thinkHome) return path.join(thinkHome, "data");
+  const xdgData = process.env.XDG_DATA_HOME || path.join(getHome(), ".local", "share");
+  return path.join(xdgData, "think");
+}
+function getEngramsDir() {
+  return path.join(getThinkDir(), "engrams");
+}
+function getEngramDbPath(cortexName) {
+  return path.join(getEngramsDir(), `${sanitizeName(cortexName)}.db`);
+}
+function getRepoPath() {
+  return path.join(getThinkDir(), "repo");
+}
+function getLongtermDir() {
+  return path.join(getThinkDir(), "longterm");
+}
+function getLongtermPath(cortexName) {
+  return path.join(getLongtermDir(), `${sanitizeName(cortexName)}.md`);
+}
+function getCuratorMdPath() {
+  return path.join(getThinkDir(), "curator.md");
+}
+function ensureThinkDirs() {
+  fs.mkdirSync(getEngramsDir(), { recursive: true });
+  fs.mkdirSync(getLongtermDir(), { recursive: true });
+}
+
+// src/lib/config.ts
+import path2 from "path";
+import fs2 from "fs";
+import { v4 as uuidv4 } from "uuid";
+function getConfigDir() {
+  return getThinkConfigDir();
+}
+function configPath() {
+  return path2.join(getConfigDir(), "config.json");
+}
+function saveConfig(config) {
+  const dir = getConfigDir();
+  fs2.mkdirSync(dir, { recursive: true });
+  fs2.writeFileSync(configPath(), JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+function getConfig() {
+  const fp = configPath();
+  if (fs2.existsSync(fp)) {
+    const raw = fs2.readFileSync(fp, "utf-8");
+    return JSON.parse(raw);
+  }
+  const config = {
+    peerId: uuidv4(),
+    syncPort: 47821
+  };
+  saveConfig(config);
+  return config;
+}
+
+// src/lib/git.ts
+function runGit(args, cwd) {
+  const repoPath = cwd ?? getRepoPath();
+  return execFileSync("git", args, {
+    cwd: repoPath,
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  }).trim();
+}
+function ensureRepoCloned() {
+  const config = getConfig();
+  if (!config.cortex?.repo) {
+    throw new Error("No cortex repo configured. Run: think cortex setup");
+  }
+  const repoPath = getRepoPath();
+  if (fs3.existsSync(path3.join(repoPath, ".git"))) {
+    const remote = runGit(["remote", "get-url", "origin"], repoPath);
+    if (remote !== config.cortex.repo) {
+      throw new Error(`Repo at ${repoPath} points to ${remote}, expected ${config.cortex.repo}`);
+    }
+    return;
+  }
+  fs3.mkdirSync(repoPath, { recursive: true });
+  execFileSync("git", ["clone", "--no-checkout", config.cortex.repo, repoPath], {
+    encoding: "utf-8",
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+}
+function branchExists(branchName) {
+  try {
+    runGit(["ls-remote", "--exit-code", "--heads", "origin", branchName]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function createOrphanBranch(branchName) {
+  runGit(["checkout", "--orphan", branchName]);
+  try {
+    runGit(["rm", "-rf", "."]);
+  } catch {
+  }
+  const repoPath = getRepoPath();
+  fs3.writeFileSync(path3.join(repoPath, "memories.jsonl"), "", "utf-8");
+  runGit(["add", "memories.jsonl"]);
+  runGit(["commit", "-m", `init: create cortex ${branchName}`]);
+  runGit(["push", "--set-upstream", "origin", branchName]);
+}
+function fetchBranch(branchName) {
+  runGit(["fetch", "origin", branchName]);
+}
+function readFileFromBranch(branchName, filePath) {
+  try {
+    return runGit(["show", `origin/${branchName}:${filePath}`]);
+  } catch {
+    return null;
+  }
+}
+function appendAndCommit(branchName, newLines, commitMessage, maxRetries = 3) {
+  const repoPath = getRepoPath();
+  const memoriesPath = path3.join(repoPath, "memories.jsonl");
+  try {
+    runGit(["switch", branchName]);
+  } catch {
+    runGit(["switch", "-c", branchName, `origin/${branchName}`]);
+  }
+  try {
+    runGit(["pull", "--rebase", "origin", branchName]);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("CONFLICT") || message.includes("could not apply")) {
+      try {
+        runGit(["rebase", "--abort"]);
+      } catch {
+      }
+      throw new Error(`Rebase conflict on ${branchName}. This should not happen with append-only files \u2014 check for manual edits to memories.jsonl.`);
+    }
+  }
+  const content = newLines.join("\n") + "\n";
+  fs3.appendFileSync(memoriesPath, content, "utf-8");
+  runGit(["add", "memories.jsonl"]);
+  runGit(["commit", "-m", commitMessage]);
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      runGit(["push", "origin", branchName]);
+      return;
+    } catch {
+      if (attempt === maxRetries) {
+        throw new Error(`Push failed after ${maxRetries} attempts. Run 'think curate' again.`);
+      }
+      runGit(["pull", "--rebase", "origin", branchName]);
+    }
+  }
+}
+function getFileLog(branchName, filePath) {
+  return runGit(["log", "--oneline", `origin/${branchName}`, "--", filePath]);
+}
+function listRemoteBranches() {
+  const output = runGit(["ls-remote", "--heads", "origin"]);
+  return output.trim().split("\n").filter(Boolean).map((line) => line.split("	")[1]?.replace("refs/heads/", "")).filter(Boolean);
+}
+
+export {
+  getThinkDataDir,
+  getEngramsDir,
+  getEngramDbPath,
+  getLongtermPath,
+  getCuratorMdPath,
+  ensureThinkDirs,
+  getConfigDir,
+  saveConfig,
+  getConfig,
+  ensureRepoCloned,
+  branchExists,
+  createOrphanBranch,
+  fetchBranch,
+  readFileFromBranch,
+  appendAndCommit,
+  getFileLog,
+  listRemoteBranches
+};

package/dist/git-Y3N244VA.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node --no-warnings=ExperimentalWarning
+import {
+  appendAndCommit,
+  branchExists,
+  createOrphanBranch,
+  ensureRepoCloned,
+  fetchBranch,
+  getFileLog,
+  listRemoteBranches,
+  readFileFromBranch
+} from "./chunk-K2FT7ZHJ.js";
+export {
+  appendAndCommit,
+  branchExists,
+  createOrphanBranch,
+  ensureRepoCloned,
+  fetchBranch,
+  getFileLog,
+  listRemoteBranches,
+  readFileFromBranch
+};