keeponfirst-local-brain

🧠 A local-first brain capture system with AI assistance.

Capture happens at the moment of thought, not after.

Project Introduction: KOF-LocalBrain

KOF-LocalBrain is a Local-first brain capture system designed for developers, solving the problem of context loss during development. Unlike cloud-dependent note-taking tools, it keeps data ownership completely local, ensuring maximum privacy and security.

Core Value:

1. IDE-First Workflow: Capture fleeting thoughts without leaving your coding environment.
2. AI-Assisted Structuring: Uses existing IDE AI to transform raw notes into standardized records (decisions, worklogs, backlogs) with explicit human confirmation.

NotebookLM MCP: Research-to-Action

With NotebookLM MCP, KOF-LocalBrain expands from "thought capture" to deep "knowledge integration":

• Dedicated Research Workspace: Use NotebookLM to digest external knowledge without cluttering your local context.
• Seamless Context Retrieval: Talk to your external knowledge base directly from your IDE via MCP.
• Structured Action: Transform insights from NotebookLM into local structured records (e.g., generate a Decision record from research docs), closing the loop between research and development.

---

Philosophy

• Capture at the moment of thought — Not after, when context is lost
• AI assists, never writes without permission — Human-in-the-loop always
• Local-first — Your data stays on your machine
• Preview & Confirm — Every write requires explicit approval

---

🚀 New Features (v1.2)

1. Bi-Directional Brain (Read & Search)

Powered by Notion MCP, your agent can now read your past records to provide context-aware assistance.

• /search <query> - Search across your entire brain
• /recall <timeframe> - Summarize past activities (e.g., "Recall last week")
• /trace <topic> - Visualize the timeline of an idea (Idea → Decision → Worklog)
• Context-Aware Capture - Automatically suggests related past records when you're writing.

2. Rich Content Rendering

• Code Blocks: Syntax highlighting for 20+ languages
• Link Previews: Standalone URLs become visual bookmarks

3. NotebookLM Integration

• Programmatic Control: Create notebooks, add sources, and query content via MCP tools.
• Auto-Research: Turn research questions into structured local decisions.

---

MCP Integrations

This project supports MCP (Model Context Protocol) servers for extended capabilities.

MCP Server	Status	Purpose
Notion MCP	✅ Ready	Read/search past records from Notion
NotebookLM MCP	✅ Ready	Use Google NotebookLM as research workspace

Notion MCP (Ready)

Enables bi-directional interaction with your Notion brain. See Notion MCP Setup.

NotebookLM MCP (Ready)

Use Google NotebookLM as a research scratchpad with AI-powered Q&A.

• Standalone Repo: keeponfirst/kof-notebooklm-mcp
• PyPI: kof-notebooklm-mcp
  • README.md - 安裝與使用指南

Available tools:

• health_check - Verify connection and authentication
• list_notebooks - List all notebooks
• get_notebook - Get notebook details
• list_sources - List sources in a notebook
• add_source - Add URL or text sources
• create_notebook - Create new notebooks programmatically
• ask - Query notebook with AI and get cited answers

---

Quick Start

1. Clone & Setup

git clone https://github.com/keeponfirst/keeponfirst-local-brain.git
cd keeponfirst-local-brain

# Create Python virtual environment
python3 -m venv .venv
source .venv/bin/activate
pip install -r scripts/requirements.txt

# Configure environment
cp .env.example .env

2. Configure Backend (Notion)

1. Go to Notion Integrations
2. Create a new integration, copy the token
3. Create a page in Notion, share it with your integration

Edit .env:

NOTION_TOKEN=secret_xxxxx
NOTION_PARENT=your-page-id-here
NOTION_MODE=page

NOTION_MODE=page

### 3. Configure Notion MCP (Optional but Recommended)
To enable read/search capabilities:

1. Follow the [Notion MCP Setup Guide](docs/NOTION_MCP_SETUP.md)
2. Restart your agent environment
3. Try `/search Hello` to verify

### Centralized Storage & Logs

This system uses a **Central Home** for all your records and logs, regardless of where you capture them from.

- **Storage Location**: Records are saved to `records/` inside your Central Home.
- **Log Location**: Execution logs are saved to `.agentic/logs/` inside your Central Home.
- **Configuration**:
  - **Inside this repo**: Automatically detected via `.agentic/CENTRAL_LOG_MARKER`.
  - **Outside this repo**: You will be asked to specify the Central Home location once (stored in `config.json`).

This allows you to use `/kof-cap` in any project directory, and notes will be consolidated back here.

---

## Record Typesrify Setup

```bash
source .venv/bin/activate
python scripts/write_record.py --dry-run --input tests/example_idea.json

---

Install as Global Skill

Install once, use from any workspace:

cp -r skills/keeponfirst-local-brain-skill ~/.gemini/antigravity/skills/

Initialize in a New Project

~/.gemini/antigravity/skills/keeponfirst-local-brain-skill/scripts/init.sh

Triggers

Trigger	Action
/kof-cap	Capture with auto-classification
/kof-decision	Force decision record
/kof-idea	Force idea record
/kof-backlog	Force backlog record
/kof-worklog	Force worklog record
/kof-note	Raw capture (fallback)

Example:

/kof-cap Decided to use Supabase because pricing is more transparent
/kof-idea New feature: voice input for capture
/kof-worklog Completed API integration

---

Record Types

Type	Emoji	Use For
Decision	⚖️	Choices, trade-offs
Worklog	📝	Daily activities
Idea	💡	Inspirations
Backlog	📋	Future tasks
Note	📄	Raw capture

---

Project Structure

.
├── skills/
│   └── keeponfirst-local-brain-skill/
│       ├── SKILL.md
│       └── scripts/
├── scripts/
│   ├── config.py
│   ├── notion_api.py
│   ├── write_record.py
│   └── init_brain.py
├── packages/
│   └── kof-notebooklm-mcp/       # NotebookLM MCP server (planned)
├── docs/
│   ├── NOTION_MCP_SETUP.md
│   └── kof-notebooklm-mcp/       # NotebookLM MCP documentation
├── records/
│   ├── decisions/
│   ├── worklogs/
│   ├── ideas/
│   └── backlogs/
├── .env.example
└── README.md

---

Local Storage

Every record saves locally:

• {timestamp}_{type}_{slug}.md — Human-readable
• {timestamp}_{type}_{slug}.json — Machine-readable

Your data stays on your machine.

---

License

MIT