Skip to content

An always-on second brain you talk to. Voice notes in Telegram → typed, linked knowledge in your Obsidian vault. Runs 24/7 on the Claude subscription you already have.

docs: rewrite README for humans, not engineers

Serge Shima20da24ae5e72
diff --git a/README.md b/README.md
index 1c283d0..9dfe022 100644
--- a/README.md
+++ b/README.md
@@ -8,258 +8,216 @@
<img alt="Agent Second Brain" src="https://github.com/user-attachments/assets/5b3611d9-11ba-40a1-92fc-8dc78d78d75b" />
</p>
-A voice-first AI assistant that turns your Telegram messages into an organized knowledge base. Send voice notes, text, photos, or forwarded messages — the agent classifies everything, creates tasks in Todoist, saves thoughts to an Obsidian vault, tracks your goals, and sends you a daily report. Your personal second brain that runs 24/7 on a $5 VPS.
+**Send a voice note to Telegram. Get an organized knowledge base, completed tasks, and a daily report back.** That's it. That's the whole idea.
-[&#x1F1F7;&#x1F1FA; Читать на русском](README.ru.md)
+[🇷🇺 Читать на русском](README.ru.md)
---
-## What's New in v2
+## The problem
-- **Conversational Agent** — Talk to the bot like a real assistant. No need to press buttons — just send a voice note or text message and have a natural dialogue. Ask follow-up questions, clarify, change your mind. The agent remembers context within the session and has full access to your vault, goals, and Todoist.
-- **Agent Memory** — Ebbinghaus forgetting curve with tiered decay. Memory cards move through tiers (core / active / warm / cold / archive) based on access patterns and time.
-- **Vault Health** — Automated health scoring, Map of Content (MOC) generation, broken link repair, and orphan detection across your entire vault.
-- **3-Phase Pipeline** — Processing is now split into CAPTURE, EXECUTE, and REFLECT phases with structured JSON handoff between each stage.
-- **Processing Rules** — Configurable formatting rules for Obsidian markdown and weekly reflections.
-- **Memory Config** — `.memory-config.json` file for fine-tuning decay rates, tier thresholds, and type inference rules.
+Every productivity system dies the same way. You set it up on a Sunday, use it for two weeks, then slowly stop because the overhead of maintaining it is more work than the work itself.
----
+You have notes everywhere. Voice memos you never re-listen to. Ideas that disappear into chat history. Tasks you forget to write down. And even when you do capture something, it sits in a folder you'll never open again.
-## Architecture
+The real issue: organizing takes more effort than thinking. So the thinking never gets organized.
-```
-Telegram (voice / text / photo / forwarded messages)
- |
- v
-Telegram Bot (Node.js) --> Deepgram (voice-to-text)
- |
- v
-Claude Code (--print --dangerously-skip-permissions)
- |
- v
-+-- CAPTURE: classify entries --> JSON
-+-- EXECUTE: Todoist tasks + vault writes --> JSON
-+-- REFLECT: HTML report + MEMORY update
- |
- v
-+-- Todoist (tasks)
-+-- Obsidian vault (thoughts, CRM, goals)
-+-- Telegram (HTML report)
-+-- GitHub (git push)
-```
+## What this actually does
-The bot runs as a systemd service on a VPS. A daily timer (21:00 UTC) triggers the 3-phase processing pipeline via `scripts/process.sh`. Each phase receives the previous phase's output as structured JSON, ensuring reliable handoff and auditability.
+You talk to a Telegram bot. Voice, text, photos, forwarded messages - whatever is natural. You don't think about categories, tags, or where things go.
----
+The agent handles everything else:
-## Skills Catalog
+- **Transcribes** your voice notes (Deepgram, takes seconds)
+- **Classifies** each entry - task, idea, client note, goal update, random thought
+- **Creates tasks** in Todoist with the right priority and due date
+- **Saves everything** to an Obsidian vault with proper links and tags
+- **Sends you a daily report** at 9pm - what happened, what got done, what's still hanging
+- **Remembers what matters, forgets what doesn't** - memory fades over time like a real brain
-| Skill | Purpose |
-|-------|---------|
-| **dbrain-processor** | Core pipeline: classify voice/text entries, create tasks, save thoughts |
-| **agent-memory** | Ebbinghaus decay engine: tiered search, creative recall, memory stats |
-| **vault-health** | Health scoring, MOC generation, link repair, orphan detection |
-| **graph-builder** | Knowledge graph analysis, entity relationships, domain mapping |
-| **todoist-ai** | Task management via mcp-cli (Todoist MCP integration) |
+The bot runs 24/7 on a $5 VPS. You don't maintain it. You just talk to it.
-Skills live in `vault/.claude/skills/` and are invoked automatically by Claude Code during processing.
-
-> **Want just the memory engine?** See [agent-memory-skill](https://github.com/smixs/agent-memory-skill) — standalone, zero dependencies.
-
----
+## Talk to it like a person
-## Quick Start
+This isn't a button-pressing bot. You have a conversation.
-### 1. Fork this repo
+> **You:** what did I write about the marketing project last week?
+>
+> **Bot:** *finds and shows relevant entries*
+>
+> **You:** turn the second idea into a task for Monday
+>
+> **Bot:** *creates the task in Todoist*
+>
+> **You:** actually make it high priority and add a subtask for the presentation
+>
+> **Bot:** *updates the task*
-Go to [github.com/smixs/agent-second-brain](https://github.com/smixs/agent-second-brain) and click **Fork**. Make the fork **private** — it will contain your personal data.
+It has access to your entire vault, all your goals, and your Todoist. Ask it anything about your own notes, and it'll find the answer.
-### 2. Clone to your machine
+## Memory that works like memory
-```bash
-git clone https://github.com/YOUR_USERNAME/agent-second-brain.git
-cd agent-second-brain
-```
+Most AI systems either remember everything forever (drowning you in noise) or forget everything between sessions.
-### 3. Fill in templates
+Agent Second Brain uses the Ebbinghaus forgetting curve - the same model that describes how human memory works. Every piece of information starts strong and gradually fades unless you access it again.
-Open the following files and replace the placeholders with your information:
+Five tiers, from always-on to nearly forgotten:
-- `vault/goals/0-vision-3y.md` — 3-year vision
-- `vault/goals/1-yearly.md` — yearly goals
-- `vault/goals/2-monthly.md` — monthly priorities
-- `vault/goals/3-weekly.md` — weekly focus (ONE Big Thing)
-- `vault/.claude/skills/dbrain-processor/references/about.md` — your profile
-- `vault/.claude/skills/dbrain-processor/references/classification.md` — entry categories
+| Tier | What happens |
+|------|-------------|
+| **Core** | Always in context. Your current projects, active clients, key goals. |
+| **Active** | Checked regularly. Recent ideas, ongoing conversations. |
+| **Warm** | Found when you search. Last month's notes, past decisions. |
+| **Cold** | Only surfaces in deep searches. Old projects, archived plans. |
+| **Archive** | Almost gone - but sometimes randomly recalled for creative connections. |
-### 4. Get API keys
+The archive tier is the interesting one. Occasionally, the agent pulls a random old memory and connects it to something current. Sometimes it's noise. Sometimes it's the best idea you forgot you had.
-| Token | Where to get it |
-|-------|-----------------|
-| Telegram Bot Token | [@BotFather](https://t.me/BotFather) in Telegram |
-| Your Telegram ID | [@userinfobot](https://t.me/userinfobot) in Telegram |
-| Deepgram API Key | [console.deepgram.com](https://console.deepgram.com/) |
-| Todoist API Token | [todoist.com](https://todoist.com) → Settings → Integrations → Developer |
+## Vault health - your notes maintain themselves
-### 5. Deploy to VPS
+Over time, note systems rot. Links break. Files become orphans. Tags diverge. You end up with a graveyard of markdown files that nobody, including you, can navigate.
-Follow the detailed server setup guide: **[docs/vps-setup.md](docs/vps-setup.md)**
+The vault-health system runs automatically:
-Short version:
+- Scores your vault on a 100-point scale
+- Finds orphan notes (no links in or out) and suggests connections
+- Repairs broken wiki-links
+- Generates Maps of Content (MOCs) for each domain
+- Flags files missing descriptions
-```bash
-ssh root@YOUR_SERVER_IP
-# Create a user, install dependencies, clone repo, configure .env
-curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/agent-second-brain/main/bootstrap.sh | bash
-```
+You don't run maintenance. The agent does.
----
+## What you send, what happens
-## Configuration
+| You send | Agent does |
+|----------|-----------|
+| Voice note about a client call | Transcribes, creates CRM card, adds follow-up task |
+| Quick text: "idea for the Q2 campaign" | Saves to ideas folder, links to related notes |
+| Forwarded article from a chat | Saves with source, extracts key points |
+| Photo of a whiteboard | Saves with AI-generated description |
+| "Process" button | Runs the full pipeline right now |
+| "What are my priorities this week?" | Reads your goals and Todoist, gives you a straight answer |
-| File | Purpose |
-|------|---------|
-| `.env` | API tokens for Telegram, Deepgram, Todoist (copy from `.env.example`) |
-| `.memory-config.json` | Decay rates, tier thresholds, type inference rules for agent memory |
-| `mcp-config.json` | MCP server configuration (Todoist and other integrations) |
-| `vault/.claude/CLAUDE.md` | Agent instructions, session bootstrap sequence, navigation rules |
-| `vault/.claude/skills/dbrain-processor/references/about.md` | Your personal profile — helps the agent understand context |
+## How it works (for the curious)
-All secrets go into `.env` which is gitignored. Never commit API tokens to the repository.
+The daily processing runs in three phases:
----
+1. **Capture** - reads today's entries, classifies each one (task? idea? CRM update? goal progress?)
+2. **Execute** - creates Todoist tasks, writes vault files, updates cards
+3. **Reflect** - generates a summary report, updates long-term memory, sends it to Telegram
-## Vault Structure
+Each phase produces a clean JSON that the next phase picks up. If something breaks, you can see exactly where and why.
```
-vault/
-├── daily/ # Daily entries (voice transcripts, notes)
-├── goals/ # Vision, yearly, monthly, weekly goals
-├── business/
-│ ├── crm/ # Client cards
-│ └── network/ # Professional contacts
-├── projects/
-│ ├── clients/ # Client project notes
-│ └── leads/ # Sales pipeline
-├── thoughts/
-│ ├── ideas/ # Ideas and brainstorms
-│ ├── learnings/ # Lessons learned
-│ └── reflections/ # Personal reflections
-├── templates/ # Card templates (CRM, daily)
-├── MOC/ # Maps of Content (auto-generated)
-├── MEMORY.md # Long-term memory (hot context)
-└── .claude/ # Agent configuration
- ├── skills/ # 5 skills (processor, memory, health, graph, todoist)
- ├── rules/ # Formatting rules (obsidian-markdown, weekly-reflection)
- └── docs/ # Reference documentation
+Telegram → Deepgram → Claude Code → Todoist + Obsidian vault → Telegram report
```
-The vault follows a Zettelkasten-inspired structure. Each domain has an `_index.md` hub file. Navigation starts from hubs and follows wiki-links.
+## What it costs
----
-
-## How It Works
+| Service | Cost |
+|---------|------|
+| Claude Pro | $20/mo |
+| VPS (any cheap one works) | ~$5/mo |
+| Deepgram | Free tier ($200 credit) |
+| Todoist | Free plan works |
+| **Total** | **~$25/mo** |
-### 3-Phase Pipeline
+$25/month for a personal assistant that organizes your life, never sleeps, and gets better the more you use it.
-The daily processing pipeline runs in three isolated phases:
+## Quick start
-1. **CAPTURE** — Reads `daily/YYYY-MM-DD.md`, classifies each entry (task, thought, idea, CRM update, goal progress), and outputs structured JSON.
-2. **EXECUTE** — Takes the classification JSON, creates Todoist tasks, writes vault files, updates CRM cards, and outputs an execution report as JSON.
-3. **REFLECT** — Generates an HTML summary report, updates `MEMORY.md` with key decisions, and sends the report to Telegram.
-
-Each phase runs as a separate Claude Code invocation. JSON is passed between phases via files, ensuring clean boundaries and debuggability.
+### 1. Fork this repo
-### Memory Decay
+Click **Fork** at the top of this page. Make it **private** - it will contain your personal data.
-Agent memory follows the Ebbinghaus forgetting curve with linear decay:
+### 2. Clone it
-- **Decay rate:** 0.015 per day
-- **Floor:** 0.1 (memories never fully disappear)
-- **Formula:** `strength = max(floor, initial - rate * days_since_access)`
+```bash
+git clone https://github.com/YOUR_USERNAME/agent-second-brain.git
+cd agent-second-brain
+```
-Memory cards move through five tiers based on their current strength:
+### 3. Fill in your info
-| Tier | Strength Range | Behavior |
-|------|---------------|----------|
-| **core** | 0.9 - 1.0 | Always loaded into context |
-| **active** | 0.7 - 0.9 | Included in heartbeat searches |
-| **warm** | 0.4 - 0.7 | Included in normal searches |
-| **cold** | 0.1 - 0.4 | Only in deep searches |
-| **archive** | 0.0 - 0.1 | Candidates for creative recall |
+Open these files and replace the placeholders:
-### Tiered Search
+- `vault/goals/` - your vision, yearly goals, monthly priorities, weekly focus
+- `vault/.claude/skills/dbrain-processor/references/about.md` - tell the agent about yourself
+- `vault/.claude/skills/dbrain-processor/references/classification.md` - how you want entries sorted
-Different search depths retrieve different tiers:
+### 4. Get four API keys
-- **heartbeat** — core + active (fast, low-cost)
-- **normal** — core + active + warm (default)
-- **deep** — all tiers (thorough)
-- **creative** — random sampling from cold/archive (serendipity)
+| What | Where | Time |
+|------|-------|------|
+| Telegram Bot Token | [@BotFather](https://t.me/BotFather) | 2 min |
+| Your Telegram ID | [@userinfobot](https://t.me/userinfobot) | 30 sec |
+| Deepgram API Key | [console.deepgram.com](https://console.deepgram.com/) | 3 min |
+| Todoist API Token | Todoist → Settings → Integrations → Developer | 1 min |
-### Health Scoring
+### 5. Deploy
-Vault health is scored on a 100-point scale:
+Follow the [VPS setup guide](docs/vps-setup.md), or run:
+```bash
+ssh root@YOUR_SERVER_IP
+curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/agent-second-brain/main/bootstrap.sh | bash
```
-health = 100 - orphan_penalty - broken_penalty - density_penalty - desc_penalty
-```
-
-- **orphan_penalty** — files with no incoming or outgoing links
-- **broken_penalty** — wiki-links pointing to non-existent files
-- **density_penalty** — low average link count per file
-- **desc_penalty** — files missing retrieval filter descriptions in frontmatter
-The vault-health skill auto-generates MOCs, repairs broken links, and suggests connections for orphans.
+That's it. The bot starts, you send it a message, and the system is alive.
---
-## Cost Breakdown
+## Vault structure
-| Service | Cost | Purpose |
-|---------|------|---------|
-| Claude Pro | $20/mo | AI processing (Claude Code) |
-| VPS | ~$5/mo | 24/7 bot hosting |
-| Deepgram | Free ($200 credit) | Voice transcription |
-| Todoist | Free / $4/mo Pro | Task management |
-| **Total** | **~$25/mo** | |
+```
+vault/
+├── daily/ # Your daily entries (voice, text, photos)
+├── goals/ # Vision → yearly → monthly → weekly
+├── business/
+│ ├── crm/ # Client cards
+│ └── network/ # Professional contacts
+├── projects/ # Client work, leads, pipeline
+├── thoughts/
+│ ├── ideas/ # Ideas and brainstorms
+│ ├── learnings/ # Lessons learned
+│ └── reflections/ # Personal reflections
+├── MOC/ # Maps of Content (auto-generated)
+└── MEMORY.md # Agent's long-term memory
+```
----
+## Skills
-## Bot Commands
+The agent has five built-in skills:
-The Telegram bot presents an inline keyboard with the following buttons:
+| Skill | What it does |
+|-------|-------------|
+| **dbrain-processor** | Classifies entries, creates tasks, saves notes |
+| **agent-memory** | Ebbinghaus decay engine - remembers, forgets, recalls |
+| **vault-health** | Scores vault health, fixes links, generates MOCs |
+| **graph-builder** | Maps relationships between notes, finds clusters |
+| **todoist-ai** | Manages tasks, projects, priorities |
-| Button | Action |
-|--------|--------|
-| 📊 Status | Show today's entry count and processing status |
-| ⚙️ Process | Run the 3-phase processing pipeline on demand |
-| 📅 Week | Generate and send a weekly digest |
-| ✨ Query | Ask the agent anything — it reads your vault and Todoist |
-| ❓ Help | Show available commands and usage tips |
+Want just the memory engine? See [agent-memory-skill](https://github.com/smixs/agent-memory-skill) - works standalone, no dependencies.
-### Talk to it like a real assistant
+## Configuration
-Buttons are just shortcuts. You can **message the bot directly** — voice or text — and have a full conversation. Ask follow-up questions, clarify, argue, brainstorm. It remembers context within the session and has access to your entire vault, goals, and Todoist.
+| File | What it controls |
+|------|-----------------|
+| `.env` | API tokens (copy from `.env.example`) |
+| `.memory-config.json` | How fast memories decay, tier boundaries |
+| `mcp-config.json` | External tool connections |
+| `vault/.claude/CLAUDE.md` | Agent personality and rules |
-**What you can send:**
+All secrets stay in `.env`, which is gitignored. Don't commit tokens.
-- **Voice notes** — transcribed via Deepgram, saved to daily file
-- **Text** — links, quotes, quick thoughts
-- **Photos** — saved with AI-generated descriptions
-- **Forwarded messages** — saved with source attribution
+---
-**Example conversation:**
+## Built by
-> You: "What did I write about the marketing project last week?"
-> Bot: *finds and shows relevant entries*
-> You: "Turn the second idea into a Todoist task for Monday"
-> Bot: *creates the task*
-> You: "Actually make it high priority and add a subtask for the presentation"
-> Bot: *updates the task*
+[Serge Shima](https://shima.me) - 20 years in marketing (BBDO, Publicis), now running an AI creative agency in Central Asia and teaching businesses how to work with AI at [aimasters.me](https://aimasters.me).
----
+This system runs my actual life. 1,100+ vault cards, 5 AI agents, daily reports. It started as a weekend project and became infrastructure.
## License
-[MIT](LICENSE)
+[MIT](LICENSE) - do whatever you want with it.
diff --git a/README.ru.md b/README.ru.md
index 1a9f298..b41d2a3 100644
--- a/README.ru.md
+++ b/README.ru.md
@@ -1,379 +1,221 @@
-# Agent Second Brain v2
+# Agent Second Brain
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Stars](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2Fsmixs%2Fagent-second-brain&query=%24.stargazers_count&label=stars&logo=github&color=blue)](https://github.com/smixs/agent-second-brain/stargazers)
[![Forks](https://img.shields.io/github/forks/smixs/agent-second-brain?style=flat&logo=github)](https://github.com/smixs/agent-second-brain/forks)
<p align="center">
- <img alt="Agent Second Brain" src="https://github.com/user-attachments/assets/ea384e65-436b-48a1-a4e1-2b003cafcdbf" />
+ <img alt="Agent Second Brain" src="https://github.com/user-attachments/assets/5b3611d9-11ba-40a1-92fc-8dc78d78d75b" />
</p>
-**Персональный AI-ассистент с долговременной памятью и кривой забывания.**
+**Отправь голосовое в Telegram - получи организованную базу знаний, выполненные задачи и дневной отчёт.** Всё. Вся идея в одном предложении.
-Записывайте голосовые, текст и фото в Telegram -- агент сам классифицирует записи, создаст задачи в Todoist, сохранит мысли в Obsidian и отправит HTML-отчёт. Во второй версии добавлена система памяти на основе кривой Эббингауза, автоматический скоринг здоровья vault и трёхфазный pipeline обработки.
-
-[Read in English](README.md)
-
----
-
-## Главное перед началом
-
-| Параметр | Значение |
-|----------|----------|
-| **Время на настройку** | 2--3 часа. Не торопитесь -- лучше один раз сделать правильно. |
-| **Стоимость** | ~$25/мес (Claude Pro $20 + VPS $5) |
-| **Приватность** | Это ваш личный сервер. Никто, кроме вас, не имеет доступа к записям и задачам. |
-
----
-
-## Оглавление
-
-- [Что нового в v2](#что-нового-в-v2)
-- [Архитектура](#архитектура)
-- [Каталог скиллов](#каталог-скиллов)
-- [Быстрый старт](#быстрый-старт)
-- [Конфигурация](#конфигурация)
-- [Структура vault](#структура-vault)
-- [Как это работает](#как-это-работает)
-- [Стоимость](#стоимость)
-- [Команды бота](#команды-бота)
-- [Помощь](#помощь)
-- [Лицензия](#лицензия)
-
----
-
-## Что нового в v2
-
-- **Диалоговый агент** -- Общайтесь с ботом как с реальным ассистентом. Не нужно нажимать кнопки — просто отправьте голосовое или текст и ведите естественный диалог. Задавайте уточняющие вопросы, меняйте решения, просите переделать. Агент помнит контекст в рамках сессии и имеет полный доступ к vault, целям и Todoist.
-- **Agent Memory** -- кривая забывания Эббингауза с пятью уровнями затухания: core, active, warm, cold, archive. Карточки памяти теряют вес со временем, а обращение к ним возвращает их в активный слой.
-- **Vault Health** -- автоматический скоринг здоровья хранилища, генерация Maps of Content, починка битых ссылок, поиск orphan-заметок без связей.
-- **3-фазный Pipeline** -- обработка разделена на CAPTURE, EXECUTE и REFLECT с передачей JSON между фазами. Каждая фаза изолирована и может быть перезапущена отдельно.
-- **Правила форматирования** -- obsidian-markdown, weekly-reflection и другие правила в `.claude/rules/` для единообразия записей.
-- **Конфиг памяти** -- файл `.memory-config.json` позволяет настроить скорость затухания, пороги уровней и автоматическое определение типа карточки.
+[🇬🇧 Read in English](README.md)
---
-## Архитектура
+## Проблема
-```
-Telegram (голос/текст/фото)
- |
-Telegram Bot (Node.js) --> Deepgram (голос-->текст)
- |
-Claude Code (--print --dangerously-skip-permissions)
- |
-+-- CAPTURE: классификация записей --> JSON
-+-- EXECUTE: задачи Todoist + записи в vault --> JSON
-+-- REFLECT: HTML-отчёт + обновление MEMORY
- |
-+-- Todoist (задачи)
-+-- Obsidian vault (мысли, CRM, цели)
-+-- Telegram (HTML-отчёт)
-+-- GitHub (git push)
-```
+Любая система продуктивности умирает одинаково. Настраиваешь в воскресенье, пользуешься две недели, потом бросаешь - потому что поддержка системы отнимает больше сил, чем сама работа.
-Бот работает на VPS и доступен 24/7. Ежедневно в 21:00 запускается автоматическая обработка через systemd timer. Все изменения коммитятся в Git и синхронизируются с GitHub.
+Заметки раскиданы везде. Голосовые, которые никогда не переслушаешь. Идеи, утонувшие в истории чатов. Задачи, которые забыл записать. А если записал - они лежат в папке, которую ты больше не откроешь.
----
+Корень проблемы: организовывать сложнее, чем думать. Поэтому мысли остаются неорганизованными.
-## Каталог скиллов
+## Что делает эта штука
-| Скилл | Назначение |
-|-------|------------|
-| **dbrain-processor** | Основной pipeline: классификация записей, создание задач, сохранение мыслей |
-| **agent-memory** | Движок затухания Эббингауза: поиск по уровням, креативный recall, статистика |
-| **vault-health** | Скоринг здоровья, генерация MOC, починка ссылок, поиск orphan-заметок |
-| **graph-builder** | Анализ графа знаний, связи между сущностями, маппинг доменов |
-| **todoist-ai** | Управление задачами через mcp-cli (интеграция Todoist MCP) |
+Ты пишешь боту в Telegram. Голосовые, текст, фото, пересланные сообщения - как удобно. Не думаешь про категории, теги или куда что положить.
-Каждый скилл описан в `vault/.claude/skills/<name>/SKILL.md` и может быть вызван агентом автоматически или по запросу пользователя.
+Агент разбирается сам:
----
+- **Расшифровывает** голосовые (Deepgram, пара секунд)
+- **Классифицирует** каждую запись - задача, идея, заметка о клиенте, прогресс по цели, случайная мысль
+- **Создаёт задачи** в Todoist с нужным приоритетом и датой
+- **Сохраняет всё** в Obsidian-хранилище с правильными ссылками и тегами
+- **Присылает дневной отчёт** в 21:00 - что произошло, что сделано, что висит
+- **Помнит важное, забывает ненужное** - память угасает со временем, как у живого человека
-## Быстрый старт
+Бот работает 24/7 на сервере за $5. Ты его не обслуживаешь. Ты просто с ним разговариваешь.
-### 1. Сделайте Fork
+## Разговаривай как с человеком
-Откройте [репозиторий](https://github.com/smixs/agent-second-brain) и нажмите кнопку **Fork** в правом верхнем углу.
+Это не бот с кнопками. Это разговор.
-> **Важно:** Сделайте репозиторий приватным. Ваши цели, мысли и записи не должны быть публичными.
-> Settings -> Danger Zone -> Change visibility -> Private.
+> **Ты:** что я писал про маркетинговый проект на прошлой неделе?
+>
+> **Бот:** *находит и показывает записи*
+>
+> **Ты:** вторую идею превращай в задачу на понедельник
+>
+> **Бот:** *создаёт задачу в Todoist*
+>
+> **Ты:** сделай высокий приоритет и добавь подзадачу на презентацию
+>
+> **Бот:** *обновляет задачу*
-### 2. Клонируйте на компьютер
+У агента доступ ко всему хранилищу, всем целям и Todoist. Спроси что угодно про свои записи - найдёт.
-```bash
-git clone https://github.com/YOUR_USERNAME/agent-second-brain.git
-cd agent-second-brain
-```
+## Память, которая работает как память
-### 3. Заполните шаблоны
+Большинство AI-систем либо помнят всё навсегда (утопая в шуме), либо забывают всё между сессиями.
-Откройте и отредактируйте под себя:
+Agent Second Brain использует кривую забывания Эббингауза - ту же модель, что описывает работу человеческой памяти. Каждая запись начинает с максимальной «яркости» и постепенно тускнеет, если к ней не возвращаются.
-- `vault/goals/0-vision-3y.md` -- видение на 3 года
-- `vault/goals/1-yearly.md` -- цели на год
-- `vault/goals/2-monthly.md` -- приоритеты на месяц
-- `vault/goals/3-weekly.md` -- фокус на неделю (ONE Big Thing)
-- `vault/.claude/skills/dbrain-processor/references/about.md` -- ваш профиль
-- `vault/.claude/skills/dbrain-processor/references/classification.md` -- категории записей
+Пять уровней - от «всегда под рукой» до «почти забыто»:
-> **Совет:** Скопируйте содержимое шаблона в Claude или ChatGPT и попросите заполнить. AI задаст уточняющие вопросы по одному и вернёт готовый файл. Это самый быстрый способ -- не нужно придумывать формулировки самому.
+| Уровень | Что происходит |
+|---------|---------------|
+| **Ядро** | Всегда в контексте. Текущие проекты, активные клиенты, ключевые цели. |
+| **Активные** | Проверяются регулярно. Свежие идеи, текущие разговоры. |
+| **Тёплые** | Находятся при поиске. Заметки за прошлый месяц, принятые решения. |
+| **Холодные** | Всплывают только при глубоком поиске. Старые проекты, архивные планы. |
+| **Архив** | Почти забытые - но иногда случайно вспоминаются для неожиданных связей. |
-### 4. Получите API-ключи
+Архив - самое интересное. Иногда агент достаёт случайную старую запись и связывает с чем-то текущим. Бывает - мимо. А бывает - это лучшая идея, которую ты забыл.
-| Токен | Где получить | Как выглядит |
-|-------|-------------|--------------|
-| Telegram Bot Token | [@BotFather](https://t.me/BotFather) в Telegram | `7123456789:AAH...` |
-| Telegram ID | [@userinfobot](https://t.me/userinfobot) в Telegram | `123456789` |
-| Deepgram API Key | [console.deepgram.com](https://console.deepgram.com/) | Длинная строка |
-| Todoist API Token | [todoist.com](https://todoist.com) -> Settings -> Integrations | 40 символов |
+## Здоровье хранилища - заметки сами себя чинят
-### 5. Разверните на VPS
+Со временем любая система заметок гниёт. Ссылки ломаются. Файлы становятся сиротами. Теги расползаются. В итоге - кладбище маркдаун-файлов, по которому не может пройти никто.
-Подключитесь к серверу и запустите bootstrap-скрипт:
+Система здоровья работает автоматически:
-```bash
-curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/agent-second-brain/main/bootstrap.sh | bash
-```
+- Оценивает хранилище по 100-балльной шкале
+- Находит сироты (файлы без связей) и предлагает ссылки
+- Чинит сломанные вики-линки
+- Генерирует карты содержимого (MOC) для каждой области
+- Отмечает файлы без описаний
-Скрипт сам скачает проект, спросит все токены, создаст `.env`, настроит автозапуск и запустит бота.
+Ты не занимаешься обслуживанием. Агент занимается.
-Если нужна пошаговая ручная настройка: [docs/vps-setup.md](docs/vps-setup.md)
+## Что отправляешь - что получаешь
----
+| Ты отправляешь | Агент делает |
+|----------------|-------------|
+| Голосовое о звонке с клиентом | Расшифровывает, создаёт CRM-карточку, добавляет follow-up задачу |
+| Текст: «идея для Q2 кампании» | Сохраняет в папку идей, связывает с похожими заметками |
+| Пересланная статья из чата | Сохраняет с источником, вытаскивает ключевые мысли |
+| Фото доски | Сохраняет с AI-описанием |
+| Кнопка «Process» | Запускает полный цикл обработки прямо сейчас |
+| «Какие приоритеты на эту неделю?» | Читает цели и Todoist, даёт прямой ответ |
-## Конфигурация
+## Как это работает (для любопытных)
-| Файл | Назначение |
-|------|------------|
-| `.env` | API-токены (Telegram, Deepgram, Todoist). Создаётся из `.env.example` |
-| `.memory-config.json` | Скорость затухания, пороги уровней, автоматическое определение типа карточки |
-| `mcp-config.json` | Конфигурация MCP-серверов (Todoist и другие) |
-| `vault/.claude/CLAUDE.md` | Инструкции агента, session bootstrap, навигация по vault |
-| `vault/.claude/skills/dbrain-processor/references/about.md` | Ваш профиль для контекста обработки |
-
-### Пример .memory-config.json
-
-```json
-{
- "decay": {
- "rate": 0.015,
- "floor": 0.1
- },
- "tiers": {
- "core": { "min": 0.85 },
- "active": { "min": 0.60 },
- "warm": { "min": 0.35 },
- "cold": { "min": 0.15 },
- "archive": { "min": 0.00 }
- }
-}
-```
+Ежедневная обработка идёт в три фазы:
----
+1. **Захват** - читает записи за день, классифицирует каждую (задача? идея? обновление CRM? прогресс по цели?)
+2. **Исполнение** - создаёт задачи в Todoist, пишет файлы в хранилище, обновляет карточки
+3. **Рефлексия** - генерирует сводный отчёт, обновляет долговременную память, отправляет в Telegram
-## Структура vault
+Каждая фаза создаёт чистый JSON, который подхватывает следующая. Если что-то ломается - видно где именно и почему.
```
-vault/
-+-- daily/ # Ежедневные записи (транскрипты голосовых, заметки)
-+-- goals/ # Видение, годовые, месячные, недельные цели
-+-- business/
-| +-- crm/ # Карточки клиентов
-| +-- network/ # Профессиональные контакты
-+-- projects/
-| +-- clients/ # Заметки по клиентским проектам
-| +-- leads/ # Воронка продаж
-+-- thoughts/
-| +-- ideas/ # Идеи и мозговые штурмы
-| +-- learnings/ # Выученные уроки
-| +-- reflections/ # Личные рефлексии
-+-- templates/ # Шаблоны карточек (CRM, daily)
-+-- MOC/ # Maps of Content (авто-генерация)
-+-- MEMORY.md # Долгосрочная память (hot context)
-+-- .claude/ # Конфигурация агента
- +-- skills/ # 5 скиллов
- +-- rules/ # Правила форматирования
- +-- docs/ # Справочная документация
+Telegram → Deepgram → Claude Code → Todoist + Obsidian → Telegram отчёт
```
-Агент умеет навигироваться по vault через hub-файлы (`_index.md` в каждой папке) и wiki-links. Чем больше связей между заметками -- тем точнее контекст и лучше качество обработки.
-
----
-
-## Как это работает
-
-### 3-фазный pipeline
-
-Обработка записей разделена на три изолированные фазы:
-
-1. **CAPTURE** -- чтение `daily/*.md` за сегодня, классификация каждой записи (задача, мысль, идея, CRM, вопрос и т.д.), формирование JSON с результатами.
-2. **EXECUTE** -- на основе JSON из CAPTURE создаёт задачи в Todoist, сохраняет мысли в соответствующие папки vault, обновляет CRM-карточки, добавляет wiki-links.
-3. **REFLECT** -- генерирует HTML-отчёт за день, обновляет MEMORY.md, отправляет отчёт в Telegram, коммитит все изменения в Git.
-
-Каждая фаза получает на вход JSON предыдущей и выдаёт свой JSON. Если фаза упала -- можно перезапустить только её, не теряя результаты предыдущих.
-
-### Затухание памяти
-
-Система использует линейную модель затухания, вдохновлённую кривой Эббингауза:
-
-- **Скорость затухания:** rate = 0.015 в день
-- **Минимальный вес:** floor = 0.1 (карточка никогда не исчезает полностью)
-- **Формула:** `weight = max(floor, 1.0 - rate * days_since_last_access)`
-
-Пять уровней по весу:
-
-| Уровень | Диапазон веса | Описание |
-|---------|---------------|----------|
-| core | 0.85 -- 1.00 | Только что созданные или недавно использованные |
-| active | 0.60 -- 0.84 | Регулярно используемые |
-| warm | 0.35 -- 0.59 | Периодически всплывающие |
-| cold | 0.15 -- 0.34 | Давно не использованные |
-| archive | 0.00 -- 0.14 | Практически забытые, но не удалённые |
+## Сколько стоит
-Обращение к карточке (recall) сбрасывает вес обратно до 1.0 -- как повторение материала в реальной жизни.
+| Сервис | Цена |
+|--------|------|
+| Claude Pro | $20/мес |
+| VPS (любой дешёвый) | ~$5/мес |
+| Deepgram | Бесплатно ($200 кредит) |
+| Todoist | Бесплатный план работает |
+| **Итого** | **~$25/мес** |
-### Поиск по уровням
+$25 в месяц за личного ассистента, который организует твою жизнь, никогда не спит и становится лучше с каждым днём использования.
-В зависимости от типа запроса агент ищет по разным слоям памяти:
-
-| Режим | Уровни | Когда используется |
-|-------|--------|--------------------|
-| **heartbeat** | core + active | Быстрый ответ на повседневные вопросы |
-| **normal** | core + active + warm | Стандартный поиск по запросу |
-| **deep** | все уровни | Глубокий анализ, ретроспектива |
-| **creative** | случайная выборка из cold | Генерация неожиданных связей и идей |
+## Быстрый старт
-Режим **creative** особенно полезен: агент случайно достаёт давно забытые карточки и находит неочевидные пересечения с текущим контекстом.
+### 1. Форкни репо
-### Скоринг здоровья vault
+Нажми **Fork** вверху страницы. Сделай форк **приватным** - в нём будут твои личные данные.
-Здоровье vault оценивается по шкале от 0 до 100:
+### 2. Склонируй
+```bash
+git clone https://github.com/YOUR_USERNAME/agent-second-brain.git
+cd agent-second-brain
```
-health = 100 - orphan_penalty - broken_penalty - density_penalty - desc_penalty
-```
-
-| Метрика | Что проверяет |
-|---------|---------------|
-| **orphan_penalty** | Заметки без входящих и исходящих связей |
-| **broken_penalty** | Битые `[[wiki-links]]`, ведущие в никуда |
-| **density_penalty** | Низкая плотность связей между заметками |
-| **desc_penalty** | Отсутствие description в frontmatter (нужен для поиска) |
-
-Скилл vault-health запускается автоматически и генерирует отчёт с конкретными рекомендациями: какие заметки связать, какие ссылки починить, где добавить описание.
-
----
-
-## Стоимость
-
-| Сервис | Стоимость | Назначение |
-|--------|-----------|------------|
-| Claude Pro | $20/мес | AI-обработка записей и запросы |
-| VPS | ~$5/мес | Хостинг бота 24/7 |
-| Deepgram | Бесплатно ($200 кредит) | Транскрипция голосовых сообщений |
-| Todoist | Бесплатно / $4/мес Pro | Управление задачами |
-| **Итого** | **~$25/мес** | |
-
----
-
-## Команды бота
-
-Кнопки в Telegram:
-
-| Кнопка | Действие |
-|--------|----------|
-| 📊 Статус | Показать количество записей за сегодня |
-| ⚙️ Обработать | Запустить pipeline обработки |
-| 📅 Неделя | Недельный дайджест |
-| ✨ Запрос | Задать вопрос агенту |
-| ❓ Помощь | Показать справку |
-
-### Что можно отправлять
-
-- **Голосовые** -- основной способ ввода. Просто наговорите мысль.
-- **Текст** -- ссылки, цитаты, быстрые заметки.
-- **Фото** -- скриншоты, фотографии досок, документов.
-- **Пересланные сообщения** -- из любых чатов и каналов.
-
-### Общайтесь как с реальным ассистентом
-Кнопки — это просто шорткаты. Вы можете **писать боту напрямую** — голосом или текстом — и вести полноценный диалог. Задавайте уточняющие вопросы, спорьте, просите переделать. Бот помнит контекст в рамках сессии и имеет доступ ко всему vault, целям и Todoist.
+### 3. Заполни свою информацию
-**Примеры:**
+Открой эти файлы и замени шаблоны на свои данные:
-- «Найди заметку про маркетинг с прошлой недели»
-- «Перенеси просроченные задачи на понедельник»
-- «Что я записывал вчера?»
-- «Покажи задачи на сегодня»
-- «Создай задачу: позвонить в банк завтра в 10:00»
-- «Посоветуй, на чём сфокусироваться сегодня»
-- «Какие задачи на этой неделе не сделаны?»
+- `vault/goals/` - видение, годовые цели, месячные приоритеты, фокус недели
+- `vault/.claude/skills/dbrain-processor/references/about.md` - расскажи агенту о себе
+- `vault/.claude/skills/dbrain-processor/references/classification.md` - как сортировать записи
-**Пример диалога:**
+### 4. Получи четыре API-ключа
-> Вы: «Что я записывал про маркетинг на прошлой неделе?»
-> Бот: *находит и показывает записи*
-> Вы: «Вторую идею оттуда превратить в задачу на понедельник»
-> Бот: *создаёт задачу в Todoist*
-> Вы: «Сделай её высоким приоритетом и добавь подзадачу на презентацию»
-> Бот: *обновляет задачу*
+| Что | Где взять | Время |
+|-----|----------|-------|
+| Telegram Bot Token | [@BotFather](https://t.me/BotFather) | 2 мин |
+| Твой Telegram ID | [@userinfobot](https://t.me/userinfobot) | 30 сек |
+| Deepgram API Key | [console.deepgram.com](https://console.deepgram.com/) | 3 мин |
+| Todoist API Token | Todoist → Settings → Integrations → Developer | 1 мин |
----
-
-## Помощь
-
-### Бот не отвечает в Telegram
+### 5. Разверни
-Подключитесь к серверу и проверьте статус:
+Следуй [инструкции по настройке VPS](docs/vps-setup.md), или:
```bash
-sudo systemctl status d-brain-bot
+ssh root@YOUR_SERVER_IP
+curl -fsSL https://raw.githubusercontent.com/YOUR_USERNAME/agent-second-brain/main/bootstrap.sh | bash
```
-Должно показать `active (running)`. Если нет -- перезапустите:
+Бот запускается, ты отправляешь ему сообщение - система живёт.
-```bash
-sudo systemctl restart d-brain-bot
-```
+---
-Посмотреть логи для диагностики:
+## Структура хранилища
-```bash
-sudo journalctl -u d-brain-bot -f --no-pager -n 50
+```
+vault/
+├── daily/ # Дневные записи (голосовые, текст, фото)
+├── goals/ # Видение → год → месяц → неделя
+├── business/
+│ ├── crm/ # Карточки клиентов
+│ └── network/ # Профессиональные контакты
+├── projects/ # Клиентские проекты, лиды, пайплайн
+├── thoughts/
+│ ├── ideas/ # Идеи и мозговые штурмы
+│ ├── learnings/ # Уроки
+│ └── reflections/ # Рефлексии
+├── MOC/ # Карты содержимого (генерируются автоматически)
+└── MEMORY.md # Долговременная память агента
```
-### Голосовые не распознаются
-
-Проверьте Deepgram API Key в файле `.env`. Убедитесь, что ключ актуален и не истёк стартовый кредит ($200).
-
-### Ошибки Claude
+## Навыки агента
-Проверьте авторизацию:
+| Навык | Что делает |
+|-------|-----------|
+| **dbrain-processor** | Классифицирует записи, создаёт задачи, сохраняет заметки |
+| **agent-memory** | Движок памяти Эббингауза - помнит, забывает, вспоминает |
+| **vault-health** | Оценка здоровья, починка ссылок, генерация MOC |
+| **graph-builder** | Карта связей между заметками, поиск кластеров |
+| **todoist-ai** | Управление задачами, проектами, приоритетами |
-```bash
-claude auth status
-```
+Нужен только движок памяти? Смотри [agent-memory-skill](https://github.com/smixs/agent-memory-skill) - работает отдельно, без зависимостей.
-Если нужно авторизоваться заново:
+## Конфигурация
-```bash
-claude auth login
-```
+| Файл | За что отвечает |
+|------|----------------|
+| `.env` | API-токены (скопируй из `.env.example`) |
+| `.memory-config.json` | Скорость угасания памяти, границы уровней |
+| `mcp-config.json` | Подключения к внешним инструментам |
+| `vault/.claude/CLAUDE.md` | Личность и правила агента |
-### Интерактивная отладка
+Все секреты в `.env`, который в gitignore. Не коммить токены.
-Самый быстрый способ разобраться с любой проблемой -- запустить Claude прямо в директории проекта:
+---
-```bash
-cd ~/agent-second-brain
-claude
-```
+## Кто сделал
-Опишите проблему, и агент сам прочитает конфигурацию, проверит логи и предложит решение.
+[Сергей Шима](https://shima.me) - 20 лет в маркетинге (BBDO, Publicis), сейчас руководит AI-креативным агентством в Центральной Азии и учит бизнес работать с AI на [aimasters.me](https://aimasters.me).
----
+Эта система работает в моей реальной жизни. 1,100+ карточек в хранилище, 5 AI-агентов, ежедневные отчёты. Начиналось как проект на выходных - стало инфраструктурой.
## Лицензия
-[MIT](LICENSE)
+[MIT](LICENSE) - делай с этим что хочешь.