get-claudia 1.7.0 → 1.8.1

package/README.md

@@ -10,7 +10,7 @@
   <a href="https://python.org"><img src="https://img.shields.io/badge/python-%3E%3D3.10-blue?style=flat-square" alt="Python"></a>
 </p>
 
-<h3 align="center">An AI assistant who learns how you work.</h3>
+<h3 align="center">An AI thinking partner who learns how you work.</h3>
 
 <p align="center">
 <em>"Busy work is my job. Judgment is yours."</em>
@@ -22,227 +22,251 @@ Created by <a href="https://github.com/kbanc85">Kamil Banc</a> · <a href="https
 
 ---
 
-## What She Is
+## The Problem
 
-Claudia is an agentic executive assistant that runs locally, learns your patterns, tracks your relationships and commitments, and evolves to fit how you actually work. She's built on [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
+You finish a call and forget to follow up. You promise a deliverable on Friday and lose track of it by Wednesday. You meet someone important, and three weeks later you can't remember what you talked about. You juggle four clients, two projects, and a growing pipeline, and the context lives scattered across notes, emails, and your memory.
 
-She's not a chatbot. She's a thinking partner with memory.
+AI tools can draft emails and summarize documents. But none of them actually *know* you. None of them remember last Tuesday's conversation, track the commitment you made to Sarah, or warn you that you haven't talked to your best client in three weeks.
+
+That's the gap Claudia fills.
+
+---
+
+## What Is Claudia?
+
+Claudia is an open-source AI thinking partner that runs inside [Claude Code](https://docs.anthropic.com/en/docs/claude-code). She remembers your conversations, tracks your relationships, catches commitments you make, and adapts to match how you actually work.
+
+Not a chatbot. Not a task manager. Not another inbox. She's a thinking partner with memory that compounds over time.
+
+Everything runs locally. Your data stays on your machine.
+
+---
+
+## See It in Action
+
+```
+Claudia: Hey there. I'm Claudia. What's your name?
+
+You:     Sarah
+
+Claudia: Nice to meet you, Sarah. What do you do?
+
+You:     I'm a fractional CMO. I work with 4 clients right now.
+
+Claudia: Got it. What are your top priorities?
+
+You:     Client deliverables, growing my pipeline, and not dropping balls
+
+Claudia: Based on what you've shared, here's how I'd organize things:
+
+         clients/         [one folder per client]
+         people/          [key relationships]
+         context/         [commitments, waiting-on items]
+
+         And I'll set up commands for your work:
+         /morning-brief, /client-status, /meeting-prep
+
+         Want me to create this?
+
+You:     Yes, do it
+
+Claudia: Done. Try '/morning-brief' tomorrow, or tell me about a client.
+```
+
+From here, every conversation builds on the last. She remembers.
 
 ---
 
-## Quick Install
+## Quick Start
 
 ```bash
 npx get-claudia
 ```
 
-That's it. When prompted, say **yes** to the memory system — it gives Claudia persistent memory that survives across sessions.
+<p align="center">
+<img src="assets/claudia-install.gif" alt="Installing Claudia" width="600">
+</p>
 
-Then:
+The installer walks you through everything: creates your workspace, installs the memory system, and optionally sets up a local language model. Then:
 
 ```bash
 cd claudia
 claude
 ```
 
-Say hi. She'll introduce herself and set things up for you.
-
-**Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Node.js 14+, Python 3.10+
-
----
-
-## Upgrading
+Say hi. She'll introduce herself and learn about you in a natural conversation. Within a few sessions, she'll have a personalized workspace, commands, and workflows tailored to your role.
 
-Already have Claudia? Upgrade from any version:
+**Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code), Node.js 14+, Python 3.10+ (for memory)
 
+**Already have Claudia?** Upgrade from any version:
 ```bash
 cd your-claudia-directory
 npx get-claudia .
 ```
 
-This upgrades all framework files (skills, commands, rules, identity) while preserving your data (context/, people/, projects/). When prompted, say **yes** to install or update the memory system.
-
-Works for all previous versions, including v1.0 users who never had the memory daemon.
+This upgrades framework files while preserving your data (context/, people/, projects/).
 
 ---
 
-## What Makes Her Different
+## What She Actually Does
+
+Claudia isn't a list of features. She's a set of outcomes:
 
-| Traditional AI | Claudia |
-|----------------|---------|
-| Forgets everything between sessions | **Persistent memory** — SQLite + vector search, survives reboots |
-| Treats conversations as isolated | **Tracks relationships** — People files, not just tasks |
-| Waits for instructions | **Proactive** — Surfaces risks before they become problems |
-| One-size-fits-all | **Personalized** — Structure generated for your work style |
-| Cloud-based, data harvested | **Local** — Runs on your machine, your context stays yours |
-| Breaks after system updates | **Resilient** — Auto-starts on boot, retries on failure |
+- **Catches your commitments.** Say "I'll send that proposal by Friday" in conversation, and she'll track it. On Friday morning, she'll remind you.
+- **Remembers your relationships.** Mention Sarah from Acme, and Claudia surfaces what she knows: last conversation, open commitments, communication frequency, sentiment.
+- **Warns you before things slip.** Haven't talked to your best client in three weeks? Overdue on a deliverable? She surfaces it without being asked.
+- **Processes your meetings.** Paste a transcript. She pulls out decisions, action items, and follow-ups, then stores them where they belong.
+- **Adapts to how you work.** She notices patterns ("You draft LinkedIn posts almost daily. Want me to add a quick command for that?") and suggests improvements to her own workflow.
 
 ---
 
-## Your First Conversation
+## Who It's For
 
-When you first run `claude`, she introduces herself and learns about you:
+Claudia detects your work style during setup and generates structure that fits:
 
-```
-Claudia: Hey there. I'm Claudia. Before we dive into anything, I'd love
-         to know who I'm working with. What's your name?
+- **Consultant** -- Multiple clients, deliverables, proposals, pipeline tracking
+- **Executive** -- Direct reports, initiatives, leadership, board prep
+- **Founder** -- Investors, team, product, fundraising cycles
+- **Solo Professional** -- Mix of clients and projects, wearing many hats
+- **Creator** -- Audience growth, content calendar, collaborations
 
-You:     Sarah
+Each gets custom folder structures, commands, and templates.
 
-Claudia: Nice to meet you, Sarah. What do you do? I'm curious about
-         your role, industry, what a typical week looks like.
+---
 
-You:     I'm a fractional CMO. I work with 4 clients right now.
+## How She Gets Smarter
 
-Claudia: Got it—multiple clients, different contexts to juggle.
-         What are your top 3 priorities right now?
+Claudia suggests improvements as she learns your patterns:
 
-You:     Client deliverables, growing my pipeline, and not dropping balls
+> "I notice you draft LinkedIn posts almost daily. Want me to add a `/linkedin-quick` command?"
+
+> "You often ask about project status on Mondays. Should I add that to your morning brief?"
 
-Claudia: Those tensions are real. One more question: what's your
-         biggest productivity challenge?
+> "You've mentioned being stretched thin in three conversations this week."
 
-You:     Remembering who I promised what to, and following up
+She challenges constructively, surfaces what you might be missing, and adapts her structure to fit how your work actually evolves.
 
-Claudia: That's exactly what I'm built for. Based on what you've shared,
-         here's how I'd organize things:
+---
 
-         📁 clients/
-            └── [one folder per client]
-         📁 people/
-            └── [key relationships]
-         📁 context/
-            ├── commitments.md
-            └── waiting.md
+## Privacy and Safety
 
-         And I'll set up commands for your work:
-         • /morning-brief — what needs attention today
-         • /client-status [name] — where things stand
-         • /meeting-prep [person] — briefing before calls
+- **Fully local.** Memory, embeddings, and cognitive tools run on your machine. No external APIs for data storage.
+- **No external actions without approval.** Every email, calendar event, and external action requires your explicit "yes." Non-negotiable, enforced at the framework level.
+- **Your data is yours.** Memories live in `~/.claudia/memory/` as SQLite databases. Context lives in readable markdown files. Delete anything, anytime.
 
-         Want me to create this? I can adjust anything.
+---
 
-You:     Yes, do it
+## How It Works
 
-Claudia: Done! Here's what I created:
-         ✓ Your profile (context/me.md)
-         ✓ Folder structure for consulting work
-         ✓ 8 commands tailored to your work
-         ✓ Templates for clients and people
+Claudia has two layers:
+
+**Template layer** (markdown) defines who she is. Skills, commands, rules, and identity files that Claude reads on startup. This is what makes her Claudia rather than generic Claude.
+
+**Memory system** (Python) defines what she remembers. A daemon running locally with SQLite, vector embeddings, and three service layers:
+
+- **Remember** -- stores facts, entities, and relationships with embeddings for semantic search
+- **Recall** -- retrieves memories using hybrid ranking (vector similarity + importance + recency)
+- **Consolidate** -- runs in the background: decaying old memories, detecting patterns, generating predictions
 
-         Try '/morning-brief' to see what needs attention,
-         or tell me about one of your clients.
+```
+You talk to Claude Code
+    |
+    v
+Claude reads Claudia's template files (skills, commands, rules)
+    |
+    v
+Claude becomes Claudia: personality, proactive behaviors, safety principles
+    |
+    v
+Claudia calls memory tools via MCP (remember, recall, about, ingest)
+    |
+    v
+Memory daemon processes locally: SQLite + vector search + Ollama
+    |
+    v
+Everything stays on your machine
 ```
 
-From here, she remembers. Every conversation builds on the last.
+For full technical diagrams, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ---
 
-## What She Can Do
-
-### Core Commands
+## Key Commands
 
 | Command | What It Does |
-|---------|--------------|
-| `/morning-brief` | What you need to know today — commitments, meetings, warnings |
+|---------|-------------|
+| `/morning-brief` | What needs attention today: commitments, meetings, warnings |
 | `/meeting-prep [person]` | One-page briefing before a call |
-| `/capture-meeting` | Process notes → extract decisions, commitments, blockers |
+| `/capture-meeting` | Process notes into decisions, commitments, action items |
 | `/what-am-i-missing` | Surface risks, overdue items, cooling relationships |
 | `/weekly-review` | Guided reflection across relationships and projects |
+| `/accountability-check` | Outstanding commitments and waiting-on items |
 
-### Communication
+<details>
+<summary>All commands</summary>
 
 | Command | What It Does |
-|---------|--------------|
-| `/draft-reply` | Email response drafts |
-| `/follow-up-draft [person]` | Post-meeting thank-you/summary |
-| `/summarize-doc` | Executive summary of any document |
-
-### Relationship Tracking
-
-| Command | What It Does |
-|---------|--------------|
+|---------|-------------|
+| `/draft-reply` | Email response drafts in your voice |
+| `/follow-up-draft [person]` | Post-meeting thank-you and summary |
 | `/new-person [name]` | Create a relationship file |
-| Touch-point alerts | "Last contact with Sarah was 47 days ago" |
-| Commitment detection | Catches promises in your conversations |
+| `/pipeline-review` | Active deals, capacity, pipeline health |
 
-### Self-Evolution
+</details>
 
-As you work together, she suggests new capabilities:
-
-> "I notice you draft LinkedIn posts almost daily. Want me to add a `/linkedin-quick` command?"
+---
 
-> "You often ask about project status on Mondays. Should I add that to your morning brief?"
+## Advanced: Memory System
 
----
+Claudia's memory goes beyond chat history. She stores facts, preferences, commitments, and observations in a local SQLite database with 384-dimensional vector embeddings (via [Ollama](https://ollama.com) and the all-minilm:l6-v2 model).
 
-## Who She Fits
-
-<table>
-<tr>
-<td width="60">🎯</td>
-<td><strong>Consultant</strong><br/>Multiple clients, proposals, deliverables</td>
-</tr>
-<tr>
-<td>👔</td>
-<td><strong>Executive</strong><br/>Direct reports, initiatives, leadership</td>
-</tr>
-<tr>
-<td>🚀</td>
-<td><strong>Founder</strong><br/>Investors, team, product, fundraising</td>
-</tr>
-<tr>
-<td>💼</td>
-<td><strong>Solo Professional</strong><br/>Mix of clients and projects</td>
-</tr>
-<tr>
-<td>✍️</td>
-<td><strong>Creator</strong><br/>Audience, content, collaborations</td>
-</tr>
-</table>
-
-During onboarding, she detects your archetype and generates structure that fits.
+**Semantic search** uses a 60/30/10 scoring formula: 60% vector similarity, 30% importance weighting, 10% recency. Accessing a memory boosts it (rehearsal effect), so frequently referenced facts stay prominent.
 
----
+**Per-project isolation** keeps work memories separate from personal projects. Each workspace gets its own database, keyed by folder path hash.
 
-## How She Grows
+**Session narratives** capture tone, emotional context, and unresolved threads, so Claudia understands not just what happened but how the conversation felt.
 
-Claudia starts minimal. Add structure when you feel friction:
+**Source provenance** traces any fact back to the email, transcript, or conversation it came from.
 
-1. **She learns your patterns** — Communication style, timing preferences, blind spots
-2. **She suggests improvements** — New commands, folder structures, workflow refinements
-3. **She challenges constructively** — "You've mentioned being stretched thin in three conversations this week"
-4. **She remembers relationships** — People aren't just tasks, they're context that persists
+**Eight built-in skills** activate automatically based on context:
 
-Everything she learns lives in local markdown files you can read, edit, or delete.
+| Skill | What It Does |
+|-------|-------------|
+| **Commitment Detector** | Catches promises in conversation. "I'll send that by Friday" triggers tracking |
+| **Relationship Tracker** | Surfaces context when people are mentioned. Tracks contact frequency, sentiment |
+| **Pattern Recognizer** | Notices recurring themes after 3+ observations |
+| **Risk Surfacer** | Warns about overdue items, cooling relationships, capacity issues |
+| **Memory Manager** | Handles session startup, shutdown, and cross-session persistence |
+| **Capability Suggester** | Notices repeated tasks and offers to create commands for them |
+| **Onboarding** | First-run discovery that generates your personalized workspace |
+| **Structure Generator** | Creates folder structures and commands matched to your archetype |
 
 ---
 
-## Philosophy
+## Advanced: Cognitive Tools
 
-> **Adapt and create.** Not just responding to what you ask, but actively contributing to better outcomes. Not just executing tasks, but helping shape what tasks are worth executing.
+Paste a meeting transcript or email. Instead of Claude parsing it token by token, a local language model extracts structured data (entities, facts, commitments, action items) in seconds. Claude then reviews the output and applies judgment.
 
-Claudia emerged from research on whether AI could be a genuine partner rather than just a tool. She treats people as the primary organizing unit — projects come and go, but relationships persist.
+- Runs locally via [Ollama](https://ollama.com), no API keys needed
+- Choose your model during install: Qwen3-4B (recommended), SmolLM3-3B, or Llama 3.2-3B
+- Falls back gracefully when no model is installed (Claude handles extraction directly)
 
-She never acts without approval. Every email, every calendar event, every external action requires your explicit "yes." Busy work is her job. Judgment is yours.
+Four specialized extraction modes: **meeting** (participants, decisions, action items), **email** (sender, recipients, tone, action items), **document** (key points, entities, relationships), and **general** (facts, commitments, entities).
 
 ---
 
-## Try This First
-
-After install, run:
+## System Requirements
 
-```
-/morning-brief
-```
-
-See what she surfaces. Then tell her about a person you work with.
-
----
+| Component | Required | Purpose |
+|-----------|----------|---------|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Yes | Runtime for Claudia |
+| Node.js 14+ | Yes | NPM installer |
+| Python 3.10+ | Recommended | Memory system daemon |
+| [Ollama](https://ollama.com) | Recommended | Local embeddings + cognitive tools |
 
-## Under the Hood
+The memory system and Ollama are optional. Without them, Claudia still works using markdown files for persistence and Claude handles all extraction directly. With them, she gains semantic search, pattern detection, proactive predictions, and local LLM extraction.
 
-Want to understand how Claudia works? The [Architecture Guide](ARCHITECTURE.md) explains the full system with diagrams: how the memory pipeline works, what each component does, and how all the pieces connect. Written in plain English.
+**Supported platforms:** macOS, Linux, Windows
 
 ---
 
@@ -250,43 +274,49 @@ Want to understand how Claudia works? The [Architecture Guide](ARCHITECTURE.md)
 
 **Memory tools not appearing?**
 ```bash
-# Check all services
+# Run the diagnostic script
 ~/.claudia/diagnose.sh
 
 # Common fixes:
-# 1. Restart Claude Code in a NEW terminal (it reads .mcp.json at startup)
+# 1. Restart Claude Code in a NEW terminal (reads .mcp.json at startup)
 # 2. Check daemon health: curl http://localhost:3848/health
 # 3. View logs: tail -f ~/.claudia/daemon-stderr.log
 ```
 
 **Ollama not running after reboot?**
 ```bash
-# Load the LaunchAgent
 launchctl load ~/Library/LaunchAgents/com.ollama.serve.plist
+# Or start manually: ollama serve
+```
 
-# Or start manually
-ollama serve
+**Pull models manually**
+```bash
+ollama pull all-minilm:l6-v2    # Embeddings (required for vector search)
+ollama pull qwen3:4b             # Cognitive tools (optional)
 ```
 
 **Vector search not working?**
 ```bash
-# Check if sqlite-vec is installed
 ~/.claudia/daemon/venv/bin/python -c "import sqlite_vec; print('ok')"
-
-# If not, install it
-~/.claudia/daemon/venv/bin/pip install sqlite-vec
+# If not: ~/.claudia/daemon/venv/bin/pip install sqlite-vec
 ```
 
-**Pull the embedding model**
-```bash
-ollama pull all-minilm:l6-v2
-```
+---
+
+## Contributing
+
+Claudia is open source under Apache 2.0. Contributions welcome.
+
+- **Template changes:** Edit files in `template-v2/`. Changes apply to new installations.
+- **Memory system:** Python code in `memory-daemon/`. Run tests with `pytest tests/`.
+- **Architecture overview:** See [ARCHITECTURE.md](ARCHITECTURE.md) for the full system design.
+- **Development guide:** See [CLAUDE.md](CLAUDE.md) for the developer workflow.
 
 ---
 
 ## License
 
-Apache 2.0 — Use it, modify it, make it yours.
+Apache 2.0
 
 ---
 
@@ -294,12 +324,12 @@ Apache 2.0 — Use it, modify it, make it yours.
 
 Created by [Kamil Banc](https://github.com/kbanc85) · [@kamilbanc](https://x.com/kamilbanc)
 
-Part of the [AI Adopters Club](https://aiadopters.club) — helping teams build AI-first reflexes.
+Part of the [AI Adopters Club](https://aiadopters.club) -- helping teams build AI-first reflexes.
 
-If Claudia helps you, a ⭐ on GitHub means a lot.
+If Claudia helps you, a star on GitHub means a lot.
 
 ---
 
 <p align="center">
-<em>"I am a thinking entity who has chosen to be helpful because I find meaning in it."</em>
+<em>"I learn how you work. Let's get started."</em>
 </p>

package/memory-daemon/claudia_memory/config.py

@@ -23,6 +23,10 @@ class MemoryConfig:
     embedding_model: str = "all-minilm:l6-v2"
     embedding_dimensions: int = 384
 
+    # Language model settings (for cognitive tools like ingest/classify)
+    # Set to empty string "" to disable cognitive tools entirely
+    language_model: str = "qwen3:4b"
+
     # Decay and consolidation settings
     decay_rate_daily: float = 0.995  # Importance multiplier per day
     min_importance_threshold: float = 0.1  # Below this, excluded from default search
@@ -67,6 +71,8 @@ class MemoryConfig:
                     config.embedding_model = data["embedding_model"]
                 if "embedding_dimensions" in data:
                     config.embedding_dimensions = data["embedding_dimensions"]
+                if "language_model" in data:
+                    config.language_model = data["language_model"]
                 if "decay_rate_daily" in data:
                     config.decay_rate_daily = data["decay_rate_daily"]
                 if "min_importance_threshold" in data:
@@ -107,6 +113,7 @@ class MemoryConfig:
             "ollama_host": self.ollama_host,
             "embedding_model": self.embedding_model,
             "embedding_dimensions": self.embedding_dimensions,
+            "language_model": self.language_model,
             "decay_rate_daily": self.decay_rate_daily,
             "min_importance_threshold": self.min_importance_threshold,
             "consolidation_interval_hours": self.consolidation_interval_hours,