digital-brain 0.1.3 → 1.0.3

package/docs/INTEGRATIONS.md

@@ -0,0 +1,72 @@
+# Integrations
+
+Digital Brain prefers official exports and local files over scraping.
+
+## WhatsApp
+
+```bash
+digital-brain run
+```
+
+WhatsApp support reads the local macOS WhatsApp database when available.
+
+Dependency selected in setup:
+
+- Install/open WhatsApp for Mac and log in: https://faq.whatsapp.com/686469079565350
+- If macOS blocks access, grant Full Disk Access to the terminal app running Digital Brain.
+- If WhatsApp is selected and the database is missing, `digital-brain run` exits with an error.
+
+## Apple iMessage
+
+```bash
+digital-brain sync-imessage --days 30
+digital-brain extract
+digital-brain interpret
+```
+
+iMessage support reads the local macOS Messages database at `~/Library/Messages/chat.db`.
+
+Dependency selected in setup:
+
+- Open Messages on macOS at least once: https://support.apple.com/guide/messages/welcome/mac
+- If macOS blocks access, grant Full Disk Access to the terminal app running Digital Brain.
+- If iMessage is selected and the database is missing, `digital-brain run` exits with an error.
+
+## Slack
+
+Use Slack's official workspace export ZIP or extracted export folder.
+
+```bash
+digital-brain import-slack --input ./slack-export.zip
+digital-brain extract
+digital-brain interpret
+```
+
+Slack export access depends on workspace permissions and plan. Public-channel exports are common; private channels and DMs may require elevated workspace export permissions.
+
+Export guide: https://slack.com/help/articles/201658943-Export-your-workspace-data
+
+## LinkedIn
+
+Use LinkedIn's official data archive ZIP or extracted archive folder.
+
+```bash
+digital-brain import-linkedin --input ./linkedin-archive.zip
+digital-brain extract
+digital-brain interpret
+```
+
+Digital Brain does not scrape LinkedIn or automate the LinkedIn app. LinkedIn controls what appears in the archive, so connections/messages may vary by account and export type.
+
+Data archive guide: https://www.linkedin.com/help/linkedin/answer/a566336
+
+## Useful Next Sources
+
+- Calendar: recurring people, meetings, and relationship cadence.
+- Email export: long-form relationship and work context, but privacy risk is high.
+- GitHub: collaborators, repos, review style, and work graph.
+- Linear/Jira: active projects and operating context.
+- Contacts: canonical names, phones, companies, and relationship labels.
+- Browser bookmarks/read-later: interests and research areas.
+
+The right rule: add sources that improve memory without turning Digital Brain into spyware. Prefer explicit exports, clear consent, and source-specific privacy controls.

package/docs/PRIVACY.md

@@ -7,13 +7,15 @@ Digital Brain is designed for local use.
 - No cloud API is called by default.
 - Ollama interpretation is local when enabled.
 - WhatsApp sending uses a local WhatsApp Web session.
+- Raw source data stays under `08 Sources/`; normal AI context should use `06 AI Memory/` and human notes under `04 People/`.
+- Same-person matching across sources is provisional and file-based; keep source evidence visible when using merged person context.
 
 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 WhatsApp database access and WhatsApp Web automation as unofficial, changeable integrations.
+- Treat WhatsApp database access, iMessage database access, and WhatsApp Web automation as local, permission-sensitive integrations that can change.
 - Always-on mode runs on your machine and inherits your local permissions.
 - You are responsible for consent, privacy, message content, and sends made from your machine.
 - Treat relationship labels as editable working notes, not truth.

package/docs/SETUP.md

@@ -0,0 +1,78 @@
+# Setup
+
+Digital Brain is designed to install with one npm command:
+
+```bash
+npx digital-brain init
+```
+
+npm installs the Node dependencies. No pip install is needed; the Python scripts only use the standard library.
+
+## What Init Checks
+
+After the quiz, `init` runs a setup check for:
+
+- Node 20+
+- npm package dependencies
+- Python 3
+- Python sqlite3 support
+- selected live source access:
+  - WhatsApp for Mac local database access
+  - Apple Messages local database access
+- selected import source instructions:
+  - Slack export link
+  - LinkedIn archive link
+- optional Ollama
+
+Run the check again anytime:
+
+```bash
+digital-brain doctor
+```
+
+For a short usage guide:
+
+```bash
+digital-brain tutorial
+```
+
+## What Cannot Be Silently Installed
+
+Digital Brain does not silently install or configure system apps.
+
+- WhatsApp for Mac must be installed and logged in by the user.
+- Apple Messages must be opened by the user before iMessage sync can read `~/Library/Messages/chat.db`.
+- macOS may require Full Disk Access for the terminal app.
+- Ollama is optional and only needed for local LLM workflows.
+
+Useful links:
+
+- Node: https://nodejs.org
+- WhatsApp for Mac: https://faq.whatsapp.com/686469079565350
+- Apple Messages: https://support.apple.com/guide/messages/welcome/mac
+- Slack exports: https://slack.com/help/articles/201658943-Export-your-workspace-data
+- LinkedIn data archive: https://www.linkedin.com/help/linkedin/answer/a566336
+
+Once setup passes, normal use is:
+
+```bash
+digital-brain run
+```
+
+`run` executes the live local sources selected during setup. If a selected live source does not exist or cannot be opened, the command fails with a setup error.
+
+Optional imports:
+
+```bash
+digital-brain import-slack --input ./slack-export.zip
+digital-brain import-linkedin --input ./linkedin-archive.zip
+digital-brain extract
+digital-brain interpret
+```
+
+Useful direct sync commands:
+
+```bash
+digital-brain sync-whatsapp --days 30
+digital-brain sync-imessage --days 30
+```

package/examples/sample-vault/{04 People/Interpreted Relationships/Close Friend.md → 06 AI Memory/Generated Relationship Drafts/Close Friend (WhatsApp).md }

@@ -1,13 +1,14 @@
-# Close Friend
+# Close Friend (WhatsApp)
 
-Generated: 2026-06-09T22:26:26.131803+00:00
+Generated: 2026-06-09T23:15:09.589124+00:00
+Source: WhatsApp
 Role: operational contact
 Role confidence: low
 Closeness: medium
 Conversation difficulty: low
 Typing style: short
 
-These are private working notes. Edit them where wrong.
+Generated draft, not truth. These are private working notes. Edit them where wrong.
 
 ## Role / Relationship Label
 - operational contact (low confidence).

package/examples/sample-vault/{04 People/Interpreted Relationships/Mom.md → 06 AI Memory/Generated Relationship Drafts/Mom (WhatsApp).md }

@@ -1,13 +1,14 @@
-# Mom
+# Mom (WhatsApp)
 
-Generated: 2026-06-09T22:26:26.131148+00:00
+Generated: 2026-06-09T23:15:09.587707+00:00
+Source: WhatsApp
 Role: mother
 Role confidence: high
 Closeness: medium
 Conversation difficulty: low
 Typing style: very short
 
-These are private working notes. Edit them where wrong.
+Generated draft, not truth. These are private working notes. Edit them where wrong.
 
 ## Role / Relationship Label
 - mother (high confidence).

package/examples/sample-vault/{08 Sources/WhatsApp/Analysis/Interpreted/Project Team.md → 06 AI Memory/Generated Relationship Drafts/Project Team (WhatsApp).md }

@@ -1,13 +1,14 @@
-# Project Team
+# Project Team (WhatsApp)
 
-Generated: 2026-06-09T22:26:26.131626+00:00
+Generated: 2026-06-09T23:15:09.588601+00:00
+Source: WhatsApp
 Role: work collaborator
 Role confidence: medium
 Closeness: low/unclear
 Conversation difficulty: practical/low-emotional
 Typing style: short
 
-These are private working notes. Edit them where wrong.
+Generated draft, not truth. These are private working notes. Edit them where wrong.
 
 ## Role / Relationship Label
 - work collaborator (medium confidence).

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

@@ -2,6 +2,6 @@
 
 Generated working notes. Treat as editable, not truth.
 
-- [[Mom]]: mother (high), closeness medium, difficulty low, style very short
-- [[Project Team]]: work collaborator (medium), closeness low/unclear, difficulty practical/low-emotional, style short
-- [[Close Friend]]: operational contact (low), closeness medium, difficulty low, style short
+- [[Mom (WhatsApp)]]: mother (high), closeness medium, difficulty low, style very short
+- [[Project Team (WhatsApp)]]: work collaborator (medium), closeness low/unclear, difficulty practical/low-emotional, style short
+- [[Close Friend (WhatsApp)]]: operational contact (low), closeness medium, difficulty low, style short

package/examples/sample-vault/06 AI Memory/Person Context Index.md

@@ -0,0 +1,26 @@
+# Person Context Index
+
+Window: last 365 days
+
+Canonical people matched across sources. Treat matches as provisional unless manually confirmed.
+
+## Mom
+
+- Canonical key: `person::mom`
+- Aliases: Mom
+- Sources: WhatsApp
+- Messages: 2
+- Dates: 2026-01-01 to 2026-01-01
+- Source-specific context:
+  - WhatsApp / Mom: warm personal relationship; 2 messages; style very short; avg 4.0 words; lowercase 0.0; emoji 0.0; slang none
+
+## Close Friend
+
+- Canonical key: `person::close friend`
+- Aliases: Close Friend
+- Sources: WhatsApp
+- Messages: 2
+- Dates: 2026-01-01 to 2026-01-01
+- Source-specific context:
+  - WhatsApp / Close Friend: warm personal relationship; 2 messages; style short; avg 5.0 words; lowercase 0.0; emoji 0.0; slang none
+

package/examples/sample-vault/06 AI Memory/Person Reply Context.md

@@ -0,0 +1,26 @@
+# Person Reply Context
+
+Use this first when responding to a specific person. It merges confirmed-looking matches across sources while keeping each source visible.
+
+## Mom
+
+- Canonical key: `person::mom`
+- Aliases: Mom
+- Sources: WhatsApp
+- Total messages: 2
+- Source-specific guidance:
+  - WhatsApp / Mom: mother (high), closeness medium, difficulty low.
+    Style: very short.
+    Reply: Keep replies very short unless context demands detail. Match style without exaggerating or parodying the person.
+
+## Close Friend
+
+- Canonical key: `person::close friend`
+- Aliases: Close Friend
+- Sources: WhatsApp
+- Total messages: 2
+- Source-specific guidance:
+  - WhatsApp / Close Friend: operational contact (low), closeness medium, difficulty low.
+    Style: short.
+    Reply: Keep replies very short unless context demands detail. Match style without exaggerating or parodying the person.
+

package/examples/sample-vault/08 Sources/{WhatsApp/Analysis/Interpreted/Close Friend.md → Analysis/Interpreted/Close Friend (WhatsApp).md }

@@ -1,13 +1,14 @@
-# Close Friend
+# Close Friend (WhatsApp)
 
-Generated: 2026-06-09T22:26:26.131803+00:00
+Generated: 2026-06-09T23:15:09.589124+00:00
+Source: WhatsApp
 Role: operational contact
 Role confidence: low
 Closeness: medium
 Conversation difficulty: low
 Typing style: short
 
-These are private working notes. Edit them where wrong.
+Generated draft, not truth. These are private working notes. Edit them where wrong.
 
 ## Role / Relationship Label
 - operational contact (low confidence).

package/examples/sample-vault/08 Sources/{WhatsApp/Analysis/Interpreted/Mom.md → Analysis/Interpreted/Mom (WhatsApp).md }

@@ -1,13 +1,14 @@
-# Mom
+# Mom (WhatsApp)
 
-Generated: 2026-06-09T22:26:26.131148+00:00
+Generated: 2026-06-09T23:15:09.587707+00:00
+Source: WhatsApp
 Role: mother
 Role confidence: high
 Closeness: medium
 Conversation difficulty: low
 Typing style: very short
 
-These are private working notes. Edit them where wrong.
+Generated draft, not truth. These are private working notes. Edit them where wrong.
 
 ## Role / Relationship Label
 - mother (high confidence).

package/examples/sample-vault/{04 People/Interpreted Relationships/Project Team.md → 08 Sources/Analysis/Interpreted/Project Team (WhatsApp).md }

@@ -1,13 +1,14 @@
-# Project Team
+# Project Team (WhatsApp)
 
-Generated: 2026-06-09T22:26:26.131626+00:00
+Generated: 2026-06-09T23:15:09.588601+00:00
+Source: WhatsApp
 Role: work collaborator
 Role confidence: medium
 Closeness: low/unclear
 Conversation difficulty: practical/low-emotional
 Typing style: short
 
-These are private working notes. Edit them where wrong.
+Generated draft, not truth. These are private working notes. Edit them where wrong.
 
 ## Role / Relationship Label
 - work collaborator (medium confidence).

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

@@ -0,0 +1,38 @@
+# Relationship Map
+
+Window: last 365 days
+
+Generated signals. Treat as editable working notes.
+
+## Mom (WhatsApp)
+
+- Source: WhatsApp
+- Canonical person: Mom (person::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
+- Typing style: very short; avg 4.0 words; lowercase 0.0; emoji 0.0; slang none
+
+## Project Team (WhatsApp)
+
+- Source: WhatsApp
+- Canonical person: Project Team (group::whatsapp::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
+- Typing style: short; avg 6.0 words; lowercase 0.0; emoji 0.0; slang none
+
+## Close Friend (WhatsApp)
+
+- Source: WhatsApp
+- Canonical person: Close Friend (person::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
+- Typing style: short; avg 5.0 words; lowercase 0.0; emoji 0.0; slang none

package/examples/sample-vault/08 Sources/Analysis/interpreted_relationship_models.json

@@ -0,0 +1,175 @@
+[
+  {
+    "chatName": "Mom",
+    "sourceSystem": "WhatsApp",
+    "displayName": "Mom (WhatsApp)",
+    "identityName": "Mom",
+    "canonicalPersonKey": "person::mom",
+    "identityConfidence": "medium",
+    "identityEvidence": "WhatsApp direct chat identity",
+    "messageCount": 2,
+    "inbound": 1,
+    "outbound": 1,
+    "outboundShare": 0.5,
+    "firstSeen": "2026-01-01",
+    "lastSeen": "2026-01-01",
+    "isGroup": false,
+    "sentimentScore": 0.159,
+    "warmthScore": 0.5,
+    "frictionScore": 0.0,
+    "operationalScore": 1.5,
+    "questionCount": 0,
+    "relationshipGuess": "warm personal relationship",
+    "tags": [
+      "direct-chat",
+      "light",
+      "warm",
+      "logistics-heavy"
+    ],
+    "typingStyle": {
+      "sampleSize": 1,
+      "avgChars": 24.0,
+      "avgWords": 4.0,
+      "lowercaseShare": 0.0,
+      "uppercaseShare": 0.0,
+      "questionShare": 0.0,
+      "exclamationShare": 0.0,
+      "emojiShare": 0.0,
+      "slang": [],
+      "signature": "very short"
+    },
+    "role": "mother",
+    "roleConfidence": "high",
+    "roleReason": "manual override",
+    "closeness": "medium",
+    "conversationDifficulty": "low",
+    "reciprocity": "balanced",
+    "howToContinue": [
+      "Use warmer language than a work chat.",
+      "Do not make the interaction purely transactional.",
+      "Track open loops, plans, dates, and commitments."
+    ],
+    "boundaries": [
+      "Do not expose private summaries unless asked."
+    ],
+    "replyStyle": [
+      "Keep replies very short unless context demands detail.",
+      "Match style without exaggerating or parodying the person."
+    ]
+  },
+  {
+    "chatName": "Project Team",
+    "sourceSystem": "WhatsApp",
+    "displayName": "Project Team (WhatsApp)",
+    "identityName": "Project Team",
+    "canonicalPersonKey": "group::whatsapp::project team",
+    "identityConfidence": "medium",
+    "identityEvidence": "group chat kept source-specific",
+    "messageCount": 2,
+    "inbound": 1,
+    "outbound": 1,
+    "outboundShare": 0.5,
+    "firstSeen": "2026-01-01",
+    "lastSeen": "2026-01-01",
+    "isGroup": true,
+    "sentimentScore": 0,
+    "warmthScore": 0.0,
+    "frictionScore": 0.0,
+    "operationalScore": 3.0,
+    "questionCount": 1,
+    "relationshipGuess": "group, likely social or mixed context",
+    "tags": [
+      "group-chat",
+      "light",
+      "logistics-heavy",
+      "question-heavy"
+    ],
+    "typingStyle": {
+      "sampleSize": 1,
+      "avgChars": 33.0,
+      "avgWords": 6.0,
+      "lowercaseShare": 0.0,
+      "uppercaseShare": 0.0,
+      "questionShare": 0.0,
+      "exclamationShare": 0.0,
+      "emojiShare": 0.0,
+      "slang": [],
+      "signature": "short"
+    },
+    "role": "work collaborator",
+    "roleConfidence": "medium",
+    "roleReason": "matched chat name",
+    "closeness": "low/unclear",
+    "conversationDifficulty": "practical/low-emotional",
+    "reciprocity": "balanced",
+    "howToContinue": [
+      "Lead with context, next steps, and clear asks.",
+      "Keep emotional interpretation light.",
+      "Track open loops, plans, dates, and commitments."
+    ],
+    "boundaries": [
+      "Do not expose private summaries unless asked."
+    ],
+    "replyStyle": [
+      "Use concise replies with one clear point.",
+      "Match style without exaggerating or parodying the person."
+    ]
+  },
+  {
+    "chatName": "Close Friend",
+    "sourceSystem": "WhatsApp",
+    "displayName": "Close Friend (WhatsApp)",
+    "identityName": "Close Friend",
+    "canonicalPersonKey": "person::close friend",
+    "identityConfidence": "medium",
+    "identityEvidence": "WhatsApp direct chat identity",
+    "messageCount": 2,
+    "inbound": 1,
+    "outbound": 1,
+    "outboundShare": 0.5,
+    "firstSeen": "2026-01-01",
+    "lastSeen": "2026-01-01",
+    "isGroup": false,
+    "sentimentScore": 0.159,
+    "warmthScore": 1.0,
+    "frictionScore": 0.0,
+    "operationalScore": 0.5,
+    "questionCount": 0,
+    "relationshipGuess": "warm personal relationship",
+    "tags": [
+      "direct-chat",
+      "light",
+      "warm",
+      "logistics-heavy"
+    ],
+    "typingStyle": {
+      "sampleSize": 1,
+      "avgChars": 30.0,
+      "avgWords": 5.0,
+      "lowercaseShare": 0.0,
+      "uppercaseShare": 0.0,
+      "questionShare": 0.0,
+      "exclamationShare": 0.0,
+      "emojiShare": 0.0,
+      "slang": [],
+      "signature": "short"
+    },
+    "role": "operational contact",
+    "roleConfidence": "low",
+    "roleReason": "logistics-heavy communication",
+    "closeness": "medium",
+    "conversationDifficulty": "low",
+    "reciprocity": "balanced",
+    "howToContinue": [
+      "Keep tone neutral until the user labels this relationship.",
+      "Track open loops, plans, dates, and commitments."
+    ],
+    "boundaries": [
+      "Do not expose private summaries unless asked."
+    ],
+    "replyStyle": [
+      "Keep replies very short unless context demands detail.",
+      "Match style without exaggerating or parodying the person."
+    ]
+  }
+]

package/examples/sample-vault/08 Sources/Analysis/person_identity_map.json

@@ -0,0 +1,78 @@
+[
+  {
+    "canonicalPersonKey": "person::mom",
+    "displayName": "Mom",
+    "aliases": [
+      "Mom"
+    ],
+    "sources": [
+      "WhatsApp"
+    ],
+    "sourceProfiles": [
+      {
+        "sourceSystem": "WhatsApp",
+        "chatName": "Mom",
+        "displayName": "Mom (WhatsApp)",
+        "messageCount": 2,
+        "firstSeen": "2026-01-01",
+        "lastSeen": "2026-01-01",
+        "relationshipGuess": "warm personal relationship",
+        "typingStyle": {
+          "sampleSize": 1,
+          "avgChars": 24.0,
+          "avgWords": 4.0,
+          "lowercaseShare": 0.0,
+          "uppercaseShare": 0.0,
+          "questionShare": 0.0,
+          "exclamationShare": 0.0,
+          "emojiShare": 0.0,
+          "slang": [],
+          "signature": "very short"
+        },
+        "identityConfidence": "medium",
+        "identityEvidence": "WhatsApp direct chat identity"
+      }
+    ],
+    "totalMessages": 2,
+    "firstSeen": "2026-01-01",
+    "lastSeen": "2026-01-01"
+  },
+  {
+    "canonicalPersonKey": "person::close friend",
+    "displayName": "Close Friend",
+    "aliases": [
+      "Close Friend"
+    ],
+    "sources": [
+      "WhatsApp"
+    ],
+    "sourceProfiles": [
+      {
+        "sourceSystem": "WhatsApp",
+        "chatName": "Close Friend",
+        "displayName": "Close Friend (WhatsApp)",
+        "messageCount": 2,
+        "firstSeen": "2026-01-01",
+        "lastSeen": "2026-01-01",
+        "relationshipGuess": "warm personal relationship",
+        "typingStyle": {
+          "sampleSize": 1,
+          "avgChars": 30.0,
+          "avgWords": 5.0,
+          "lowercaseShare": 0.0,
+          "uppercaseShare": 0.0,
+          "questionShare": 0.0,
+          "exclamationShare": 0.0,
+          "emojiShare": 0.0,
+          "slang": [],
+          "signature": "short"
+        },
+        "identityConfidence": "medium",
+        "identityEvidence": "WhatsApp direct chat identity"
+      }
+    ],
+    "totalMessages": 2,
+    "firstSeen": "2026-01-01",
+    "lastSeen": "2026-01-01"
+  }
+]