digital-brain 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rushill Shah
+
+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,113 @@
+# Digital Brain
+
+Your private digital imprint for AI.
+
+Digital Brain turns your local notes and message history into an editable memory vault that AI assistants can use to understand your people, patterns, tone, and context.
+
+It is not a chatbot. It is not a cloud memory service. It is the local context layer that makes your existing AI tools feel less generic.
+
+## Why
+
+AI tools are powerful, but they usually start every personal question cold.
+
+Digital Brain gives them a structured, local map of:
+
+- who matters in your life
+- how you communicate with different people
+- which relationships are warm, operational, difficult, or high-context
+- what tone to use when drafting replies
+- what not to assume
+
+## Install
+
+```bash
+npx digital-brain init
+```
+
+The installer asks a short setup quiz: history window, primary focus, refresh cadence, active time window, outbound mode, and AI adapter setup.
+
+For local development:
+
+```bash
+npm install
+node ./bin/digital-brain.js init ./Digital Brain\ Vault
+```
+
+## What It Creates
+
+- An Obsidian-friendly Markdown vault.
+- AI adapter files for Codex, Claude, and Gemini.
+- WhatsApp Mac import tools.
+- Relationship extraction and interpretation models.
+- Optional WhatsApp Web outbound sender.
+- A refresh script based on your install-time answers.
+
+## What It Can Do
+
+- Import recent WhatsApp history from the local macOS WhatsApp database.
+- Build relationship profiles from message patterns.
+- Infer provisional roles like parent, family group, work collaborator, close personal contact, or unlabeled contact.
+- Generate "how to continue this relationship" notes.
+- Create AI-readable memory files for future prompts.
+- Draft WhatsApp sends by default, and only send with explicit `--yes`.
+- Enforce an AI-disclosure guard after repeated AI-assisted sends.
+
+## Core Commands
+
+```bash
+digital-brain init ./Digital Brain\ Vault
+digital-brain sync-whatsapp --vault ./Digital Brain\ Vault --days 30
+digital-brain extract --vault ./Digital Brain\ Vault --days 30
+digital-brain interpret --vault ./Digital Brain\ Vault --days 30
+digital-brain send-whatsapp --vault ./Digital Brain\ Vault --to "Name" --message "text"
+```
+
+The sender drafts by default. Add `--yes` to actually send.
+
+If Digital Brain has already sent two AI-assisted messages to the same chat in the last 24 hours, the next send must disclose that AI is helping unless you explicitly bypass the check.
+
+## Automation
+
+Each vault gets:
+
+```bash
+Tools/digital-brain-refresh.sh
+```
+
+Use it with Codex automations, local cron, launchd, or another scheduler. See [docs/AUTOMATIONS.md](docs/AUTOMATIONS.md).
+
+## Example
+
+Before Digital Brain:
+
+> Help me reply to my mom.
+
+Generic AI gives generic advice.
+
+After Digital Brain:
+
+> Help me reply to my mom.
+
+Your AI can use local context: this person is your mother, the tone should be warm, the thread may be logistical, and the reply should not sound like a work update.
+
+## Try Fake Data
+
+```bash
+npm run test:sample
+```
+
+This uses fake WhatsApp-style messages in `examples/sample-vault`.
+
+## Privacy
+
+Digital Brain is local-first. It does not upload messages or notes.
+
+WhatsApp support reads the local macOS WhatsApp database when available. This is experimental and unofficial. Outbound messaging uses WhatsApp Web through `whatsapp-web.js`.
+
+Relationship labels are working notes, not truth. You can edit them with `relationship_overrides.json`.
+
+## Status
+
+Alpha. Expect rough edges.
+
+Do not use this for regulated, emergency, legal, medical, or safety-critical communication.

package/bin/digital-brain.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { copyDir, ensureDir, packageRoot, resolveVault } from "../lib/fs.js";
+
+const root = packageRoot(import.meta.url);
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});
+
+async function main() {
+  const [command = "help", ...argv] = process.argv.slice(2);
+  const args = parseArgs(argv);
+
+  if (command === "init") await init(argv, args);
+  else if (command === "doctor") doctor();
+  else if (command === "sync-whatsapp") runPython("digital_brain_whatsapp_mac_sync.py", argv);
+  else if (command === "extract") runPython("digital_brain_relationship_extractor.py", argv);
+  else if (command === "interpret") runPython("digital_brain_relationship_interpreter.py", argv);
+  else if (command === "send-whatsapp") runNode("whatsapp-web/send.mjs", argv);
+  else help();
+}
+
+async function init(argv, args) {
+  const positional = argv.filter((arg) => !arg.startsWith("--"));
+  const defaultVault = path.resolve(process.cwd(), "Digital Brain Vault");
+  let vault = positional[0] ? path.resolve(positional[0]) : args.yes ? defaultVault : "";
+  let selfName = args["self-name"] || "";
+  let connectAi = toBoolean(args["connect-ai"]);
+  let dataWindowDays = Number(args["data-window-days"] || 30);
+  let focus = args.focus || "";
+  let schedule = args.schedule || "manual";
+  let activeWindow = args["active-window"] || "08:00-12:00";
+  let timezone = args.timezone || Intl.DateTimeFormat().resolvedOptions().timeZone || "local";
+  let outboundMode = args["outbound-mode"] || "draft";
+
+  if (!args.yes) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    vault ||= path.resolve(await ask(rl, "Vault path", defaultVault));
+    selfName ||= await ask(rl, "Your name", "Me");
+    dataWindowDays = Number(await ask(rl, "How much history should Digital Brain import by default? Days", String(dataWindowDays)));
+    focus ||= await ask(rl, "What should it optimize for? relationship-memory / reply-help / work-context", "relationship-memory");
+    schedule = await ask(rl, "How often should refresh guidance run? manual / hourly / every-30-min / daily", schedule);
+    activeWindow = await ask(rl, "Active window for frequent refreshes", activeWindow);
+    outboundMode = await ask(rl, "WhatsApp outbound mode? disabled / draft / send-with-confirmation", outboundMode);
+    connectAi = /^y/i.test(await ask(rl, "Add global AI pointers for Codex/Claude/Gemini?", "y"));
+    rl.close();
+  }
+
+  ensureDir(vault);
+  copyDir(path.join(root, "templates", "vault"), vault);
+  const config = {
+    selfName: selfName || "Me",
+    dataWindowDays,
+    focus: focus || "relationship-memory",
+    schedule,
+    activeWindow,
+    timezone,
+    outboundMode,
+    disclosureRule: {
+      enabled: true,
+      discloseAfterAiAssistedSends: 2,
+      windowHours: 24,
+    },
+  };
+  writeConfig(vault, config);
+  writeRefreshScript(vault, config);
+
+  if (connectAi) {
+    addGlobalPointer(path.join(os.homedir(), ".codex", "AGENTS.md"), vault, "Codex");
+    addGlobalPointer(path.join(os.homedir(), ".claude", "CLAUDE.md"), vault, "Claude");
+    addGlobalPointer(path.join(os.homedir(), ".gemini", "GEMINI.md"), vault, "Gemini");
+  }
+
+  console.log(`Digital Brain vault created: ${vault}`);
+  console.log(`Config: ${path.join(vault, "digital-brain.config.json")}`);
+  console.log(`Refresh script: ${path.join(vault, "Tools", "digital-brain-refresh.sh")}`);
+  console.log("Next:");
+  console.log(`  digital-brain sync-whatsapp --vault "${vault}" --days ${dataWindowDays}`);
+  console.log(`  digital-brain extract --vault "${vault}" --days ${dataWindowDays}`);
+  console.log(`  digital-brain interpret --vault "${vault}" --days ${dataWindowDays}`);
+}
+
+function doctor() {
+  const checks = [
+    ["node", process.version],
+    ["python3", shell("python3", ["--version"])],
+    ["sqlite3", shell("sqlite3", ["--version"])],
+    ["ollama", shell("ollama", ["--version"], true)],
+  ];
+  for (const [name, value] of checks) {
+    console.log(`${name}: ${value || "not found"}`);
+  }
+  const macDb = path.join(os.homedir(), "Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite");
+  console.log(`WhatsApp Mac DB: ${fs.existsSync(macDb) ? macDb : "not found"}`);
+}
+
+function runPython(script, argv) {
+  const resolved = withVault(argv);
+  const result = spawnSync("python3", [path.join(root, "scripts", script), ...resolved], { stdio: "inherit" });
+  process.exit(result.status ?? 1);
+}
+
+function runNode(script, argv) {
+  const result = spawnSync(process.execPath, [path.join(root, script), ...argv], { stdio: "inherit" });
+  process.exit(result.status ?? 1);
+}
+
+function withVault(argv) {
+  if (argv.includes("--vault") || argv.some((arg) => arg.startsWith("--vault="))) return argv;
+  return ["--vault", resolveVault(process.cwd()), ...argv];
+}
+
+function writeConfig(vault, config) {
+  fs.writeFileSync(path.join(vault, "digital-brain.config.json"), `${JSON.stringify(config, null, 2)}\n`);
+}
+
+function writeRefreshScript(vault, config) {
+  const toolsDir = path.join(vault, "Tools");
+  ensureDir(toolsDir);
+  const days = Number(config.dataWindowDays || 30);
+  const content = `#!/usr/bin/env bash
+set -euo pipefail
+
+VAULT="${vault.replace(/"/g, '\\"')}"
+DAYS="${days}"
+
+digital-brain sync-whatsapp --vault "$VAULT" --days "$DAYS" --markdown-mode month
+digital-brain extract --vault "$VAULT" --days "$DAYS"
+digital-brain interpret --vault "$VAULT" --days "$DAYS"
+
+echo "Digital Brain refresh complete for $VAULT"
+`;
+  const scriptPath = path.join(toolsDir, "digital-brain-refresh.sh");
+  fs.writeFileSync(scriptPath, content);
+  fs.chmodSync(scriptPath, 0o755);
+}
+
+function addGlobalPointer(file, vault, label) {
+  ensureDir(path.dirname(file));
+  const block = `
+
+# Digital Brain
+
+Digital Brain vault:
+
+\`${vault}\`
+
+Use it as local personal context when the user asks about preferences, relationships, communication style, or recurring context. Treat generated relationship notes as provisional.
+`;
+  const existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+  if (!existing.includes(vault)) fs.appendFileSync(file, block);
+  console.log(`${label} pointer: ${file}`);
+}
+
+async function ask(rl, label, fallback) {
+  const answer = await rl.question(`${label} (${fallback}): `);
+  return answer.trim() || fallback;
+}
+
+function shell(command, args, optional = false) {
+  const result = spawnSync(command, args, { encoding: "utf8" });
+  if (result.error && optional) return "";
+  if (result.error) return "not found";
+  return (result.stdout || result.stderr).trim().split("\n")[0];
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) continue;
+    const key = arg.slice(2);
+    if (key.includes("=")) {
+      const [k, ...rest] = key.split("=");
+      out[k] = rest.join("=");
+    } else {
+      const next = argv[i + 1];
+      if (!next || next.startsWith("--")) out[key] = true;
+      else out[key] = argv[++i];
+    }
+  }
+  return out;
+}
+
+function toBoolean(value) {
+  if (value === undefined) return false;
+  if (value === true) return true;
+  return !["false", "0", "no", "off"].includes(String(value).toLowerCase());
+}
+
+function help() {
+  console.log(`Digital Brain
+
+Usage:
+  digital-brain init [vault]
+  digital-brain doctor
+  digital-brain sync-whatsapp --vault <path> --days 30
+  digital-brain extract --vault <path> --days 30
+  digital-brain interpret --vault <path> --days 30
+  digital-brain send-whatsapp --vault <path> --to "Name" --message "Text" [--yes]
+`);
+}

package/docs/AUTOMATIONS.md

@@ -0,0 +1,70 @@
+# Automations
+
+Digital Brain can run manually, on your machine, or through an AI/workspace automation system.
+
+The generated vault includes:
+
+```bash
+Tools/digital-brain-refresh.sh
+```
+
+That script runs sync, extract, and interpret using the install-time config.
+
+## Configurable At Install
+
+`digital-brain init` asks:
+
+- vault path
+- your name
+- history window in days
+- primary focus: relationship memory, reply help, work context
+- refresh cadence
+- active time window
+- WhatsApp outbound mode
+- whether to add AI adapter pointers
+
+The answers are saved in:
+
+```bash
+digital-brain.config.json
+```
+
+## Codex App
+
+Use a Codex cron automation pointed at the generated vault.
+
+Prompt:
+
+```text
+Run `Tools/digital-brain-refresh.sh`. Verify completion and report only counts plus output paths. Do not print private message contents.
+```
+
+Example schedule ideas:
+
+- Every morning: `FREQ=DAILY;BYHOUR=8;BYMINUTE=0;BYSECOND=0`
+- Every 30 minutes from 8-12: `FREQ=DAILY;BYHOUR=8,9,10,11;BYMINUTE=0,30;BYSECOND=0`
+- Weekly: `FREQ=WEEKLY;BYDAY=MO;BYHOUR=9;BYMINUTE=0;BYSECOND=0`
+
+## Local Cron
+
+Run every 30 minutes from 8-12:
+
+```cron
+0,30 8-11 * * * /path/to/vault/Tools/digital-brain-refresh.sh >> /path/to/vault/08\ Sources/WhatsApp/.sync-state/cron.log 2>&1
+```
+
+## macOS launchd
+
+Use launchd if you want a native background job. Be aware macOS privacy permissions may block background access to app databases unless Terminal or the runner has Full Disk Access.
+
+## Cloud
+
+Cloud schedulers are useful for notes and non-sensitive sources, but WhatsApp Mac database sync requires the local Mac.
+
+Recommended cloud pattern:
+
+1. Keep WhatsApp ingestion local.
+2. Sync only generated, reviewed memory summaries if you choose.
+3. Run cloud jobs on sanitized vault summaries, not raw chats.
+
+Do not upload raw WhatsApp exports to a cloud automation unless you explicitly want that privacy tradeoff.

package/docs/PRIVACY.md

@@ -0,0 +1,17 @@
+# Privacy Model
+
+Digital Brain is designed for local use.
+
+- Messages are read from local files or local app databases.
+- Relationship models are written as local Markdown and JSON.
+- No cloud API is called by default.
+- Ollama interpretation is local when enabled.
+- WhatsApp sending uses a local WhatsApp Web session.
+
+Things to be careful about:
+
+- Do not commit a generated vault.
+- Do not paste private message exports into GitHub issues.
+- Do not enable outbound sending without understanding the risk.
+- Treat relationship labels as editable working notes, not truth.
+

package/docs/ROADMAP.md

@@ -0,0 +1,9 @@
+# Roadmap
+
+- Local dashboard for relationship models.
+- Reply copilot grounded in relationship memory.
+- Manual correction UI for relationship roles.
+- Safer outbound approval queue.
+- Better importers beyond WhatsApp Mac.
+- Packaged app after CLI validation.
+

package/examples/sample-vault/04 People/Interpreted Relationships/Close Friend.md

@@ -0,0 +1,29 @@
+# Close Friend
+
+Generated: 2026-06-09T22:06:49.488719+00:00
+Role: operational contact
+Role confidence: low
+Closeness: medium
+Conversation difficulty: low
+
+These are private working notes. Edit them where wrong.
+
+## Role / Relationship Label
+- operational contact (low confidence).
+- Reason: logistics-heavy communication.
+
+## Closeness And Importance
+- Closeness: medium.
+- Reciprocity: balanced.
+- Conversation difficulty: low.
+
+## Communication Pattern
+- Messages: 2 (1 inbound, 1 outbound).
+- Tags: direct-chat, light, warm, logistics-heavy.
+
+## How To Continue This Relationship
+- Keep tone neutral until the user labels this relationship.
+- Track open loops, plans, dates, and commitments.
+
+## What Not To Assume
+- Do not expose private summaries unless asked.

package/examples/sample-vault/04 People/Interpreted Relationships/Mom.md

@@ -0,0 +1,30 @@
+# Mom
+
+Generated: 2026-06-09T22:06:49.488023+00:00
+Role: mother
+Role confidence: high
+Closeness: medium
+Conversation difficulty: low
+
+These are private working notes. Edit them where wrong.
+
+## Role / Relationship Label
+- mother (high confidence).
+- Reason: manual override.
+
+## Closeness And Importance
+- Closeness: medium.
+- Reciprocity: balanced.
+- Conversation difficulty: low.
+
+## Communication Pattern
+- Messages: 2 (1 inbound, 1 outbound).
+- Tags: direct-chat, light, warm, logistics-heavy.
+
+## How To Continue This Relationship
+- Use warmer language than a work chat.
+- Do not make the interaction purely transactional.
+- Track open loops, plans, dates, and commitments.
+
+## What Not To Assume
+- Do not expose private summaries unless asked.

package/examples/sample-vault/04 People/Interpreted Relationships/Project Team.md

@@ -0,0 +1,30 @@
+# Project Team
+
+Generated: 2026-06-09T22:06:49.488560+00:00
+Role: work collaborator
+Role confidence: medium
+Closeness: low/unclear
+Conversation difficulty: practical/low-emotional
+
+These are private working notes. Edit them where wrong.
+
+## Role / Relationship Label
+- work collaborator (medium confidence).
+- Reason: matched chat name.
+
+## Closeness And Importance
+- Closeness: low/unclear.
+- Reciprocity: balanced.
+- Conversation difficulty: practical/low-emotional.
+
+## Communication Pattern
+- Messages: 2 (1 inbound, 1 outbound).
+- Tags: group-chat, light, logistics-heavy, question-heavy.
+
+## How To Continue This Relationship
+- Lead with context, next steps, and clear asks.
+- Keep emotional interpretation light.
+- Track open loops, plans, dates, and commitments.
+
+## What Not To Assume
+- Do not expose private summaries unless asked.

package/examples/sample-vault/06 AI Memory/Interpreted Relationship Memory.md

@@ -0,0 +1,7 @@
+# Interpreted Relationship Memory
+
+Generated working notes. Treat as editable, not truth.
+
+- [[Mom]]: mother (high), closeness medium, difficulty low
+- [[Project Team]]: work collaborator (medium), closeness low/unclear, difficulty practical/low-emotional
+- [[Close Friend]]: operational contact (low), closeness medium, difficulty low

package/examples/sample-vault/08 Sources/WhatsApp/Analysis/Interpreted/Close Friend.md

@@ -0,0 +1,29 @@
+# Close Friend
+
+Generated: 2026-06-09T22:06:49.488719+00:00
+Role: operational contact
+Role confidence: low
+Closeness: medium
+Conversation difficulty: low
+
+These are private working notes. Edit them where wrong.
+
+## Role / Relationship Label
+- operational contact (low confidence).
+- Reason: logistics-heavy communication.
+
+## Closeness And Importance
+- Closeness: medium.
+- Reciprocity: balanced.
+- Conversation difficulty: low.
+
+## Communication Pattern
+- Messages: 2 (1 inbound, 1 outbound).
+- Tags: direct-chat, light, warm, logistics-heavy.
+
+## How To Continue This Relationship
+- Keep tone neutral until the user labels this relationship.
+- Track open loops, plans, dates, and commitments.
+
+## What Not To Assume
+- Do not expose private summaries unless asked.

package/examples/sample-vault/08 Sources/WhatsApp/Analysis/Interpreted/Mom.md

@@ -0,0 +1,30 @@
+# Mom
+
+Generated: 2026-06-09T22:06:49.488023+00:00
+Role: mother
+Role confidence: high
+Closeness: medium
+Conversation difficulty: low
+
+These are private working notes. Edit them where wrong.
+
+## Role / Relationship Label
+- mother (high confidence).
+- Reason: manual override.
+
+## Closeness And Importance
+- Closeness: medium.
+- Reciprocity: balanced.
+- Conversation difficulty: low.
+
+## Communication Pattern
+- Messages: 2 (1 inbound, 1 outbound).
+- Tags: direct-chat, light, warm, logistics-heavy.
+
+## How To Continue This Relationship
+- Use warmer language than a work chat.
+- Do not make the interaction purely transactional.
+- Track open loops, plans, dates, and commitments.
+
+## What Not To Assume
+- Do not expose private summaries unless asked.

package/examples/sample-vault/08 Sources/WhatsApp/Analysis/Interpreted/Project Team.md

@@ -0,0 +1,30 @@
+# Project Team
+
+Generated: 2026-06-09T22:06:49.488560+00:00
+Role: work collaborator
+Role confidence: medium
+Closeness: low/unclear
+Conversation difficulty: practical/low-emotional
+
+These are private working notes. Edit them where wrong.
+
+## Role / Relationship Label
+- work collaborator (medium confidence).
+- Reason: matched chat name.
+
+## Closeness And Importance
+- Closeness: low/unclear.
+- Reciprocity: balanced.
+- Conversation difficulty: practical/low-emotional.
+
+## Communication Pattern
+- Messages: 2 (1 inbound, 1 outbound).
+- Tags: group-chat, light, logistics-heavy, question-heavy.
+
+## How To Continue This Relationship
+- Lead with context, next steps, and clear asks.
+- Keep emotional interpretation light.
+- Track open loops, plans, dates, and commitments.
+
+## What Not To Assume
+- Do not expose private summaries unless asked.

package/examples/sample-vault/08 Sources/WhatsApp/Analysis/Relationship Map.md

@@ -0,0 +1,29 @@
+# Relationship Map
+
+Window: last 365 days
+
+Generated signals. Treat as editable working notes.
+
+## Mom
+
+- Guess: warm personal relationship
+- Messages: 2 (1 inbound, 1 outbound)
+- Dates: 2026-01-01 to 2026-01-01
+- Scores: sentiment 0.159, warmth 0.5, friction 0.0, operational 1.5
+- Tags: direct-chat, light, warm, logistics-heavy
+
+## Project Team
+
+- Guess: group, likely social or mixed context
+- Messages: 2 (1 inbound, 1 outbound)
+- Dates: 2026-01-01 to 2026-01-01
+- Scores: sentiment 0, warmth 0.0, friction 0.0, operational 3.0
+- Tags: group-chat, light, logistics-heavy, question-heavy
+
+## Close Friend
+
+- Guess: warm personal relationship
+- Messages: 2 (1 inbound, 1 outbound)
+- Dates: 2026-01-01 to 2026-01-01
+- Scores: sentiment 0.159, warmth 1.0, friction 0.0, operational 0.5
+- Tags: direct-chat, light, warm, logistics-heavy