THE DEFINITIVE GUIDE TO PERSONAL AI

Build Your Own AI Assistant That Gets Smarter

UPDATED: Jan 2026 Claude Code Token Efficient Battle-Tested

This guide documents months of real-world iteration building a personal AI assistant called Gizmo. You'll learn how to create a system that remembers your preferences, learns from mistakes, saves tokens, and actually gets better over time—not just a chatbot that forgets everything when the window closes.

!
Why this matters: Without proper memory and learning systems, you're paying for the same corrections over and over. The techniques here have saved thousands of tokens per session and eliminated repetitive mistakes.
$ cat /dev/brain/motivation.txt

# Why Build Your Own AI Assistant?

Out-of-the-box AI assistants are powerful but stateless. Every conversation starts from zero. They don't remember your preferences, your tech stack, or the mistakes they made yesterday.

THE REAL PROBLEM
$
Wasted tokens — Repeating context every session
!
Repeated mistakes — Same errors, different day
?
Lost decisions — "Why did we do it this way again?"
x
No learning — Corrections disappear into the void

A personal AI assistant solves these by creating persistent context, structured learning, and automatic memory. The assistant becomes an extension of your brain—one that doesn't forget.

Default Claude
  • Fresh start every session
  • You re-explain preferences
  • Makes the same mistakes
  • No project context
  • Generic responses
Custom Assistant
  • Remembers everything
  • Knows your style automatically
  • Learns from corrections
  • Deep project context
  • Personalized responses
$ tree ~/.claude --depth=1

# Architecture Overview

A smart AI assistant is built on five pillars. Each one adds a layer of intelligence that compounds over time.

5
MCP Integrations
Connect to external tools (Google Drive, GitHub, databases)
4
Skills System
Reusable workflows for common tasks (/commit, /blog-writer)
3
Memory & Search
Semantic + keyword search across all past sessions
2
Session Continuity
Auto-save state, pick up where you left off
1
CLAUDE.md Foundation
Project instructions, preferences, learnings
THE INTELLIGENCE FORMULA
Effectiveness = Intelligence × Context × Tools
The model's intelligence is fixed. But you control context and tools. That's where the gains are.
$ cat CLAUDE.md | head -100

# The CLAUDE.md Foundation

CLAUDE.md is the heart of your assistant. It's a markdown file that Claude Code reads automatically at the start of every session. Think of it as your assistant's operating manual.

Location: ~/.claude/CLAUDE.md (global) or ./CLAUDE.md (project-specific)
CLAUDE.md structure
# Project Name

## Who You Are
Personal AI assistant for [name]. Built on Claude Code.

## Communication Style
- Direct and concise — no fluff
- Make decisions instead of over-asking
- Builder-to-builder communication

## Technical Preferences
- SvelteKit for web (not React)
- Python 3.12 for ML (not 3.14)
- Supabase for backend

## Don't Do
- Don't use "cohort" — use "intake"
- Don't add emojis unless asked
- Don't over-explain — be brief

## Session Learnings

### Patterns That Work
- [Pattern description] (YYYY-MM-DD)

### Avoid
- [Anti-pattern description] (YYYY-MM-DD)

## Session Log
**2026-01-25** - What was accomplished. See: sessions/file.md
>
Key insight: CLAUDE.md is read automatically. Every preference, every learning, every pattern you add here is applied to every future session. This is where compound learning happens.

Essential Sections

Communication Style

How should the assistant talk to you? Concise or verbose? Technical or simple?

- Prefer action over discussion
- Don't ask for confirmation on small decisions
Technical Preferences

Your tech stack, tool choices, and conventions.

- Use Cloudflare Pages for deployment
- Prefer CSS Grid over Flexbox for layouts
Session Learnings

Patterns that work and mistakes to avoid. Updated after every session.

- Don't use $ in passwords (URL encoding issues)
- Always test DB with psql before debugging code
Don't Do

Explicit prohibitions. Things that waste time or annoy you.

- Don't use value stacks in pricing cards
- Never auto-commit without asking
$ ls ~/.claude/bootstrap/

# Bootstrap Files

Bootstrap files are auto-loaded context that gives your assistant immediate situational awareness. Instead of re-explaining your current projects and priorities every session, these files do it automatically.

~/.claude/bootstrap/
├── IDENTITY.md # Who the assistant is
├── USER.md # Your preferences and style
├── CURRENT.md # Active projects this week
└── PRIORITIES.md # Top focus areas
USER.md example
# User Profile: JV

## Communication Style
- Direct and concise — no fluff
- Prefers action over discussion
- Appreciates decisions over over-asking

## Technical Preferences
- SvelteKit for web (not React)
- Python 3.12 for ML/tools
- Cloudflare Pages for deployment

## Don't Do
- Don't use "cohort" — use "intake"
- Don't add emojis unless asked
- Don't over-explain — be brief
CURRENT.md example
# Current Focus (Week of 2026-01-25)

## Active Projects

### Farm Doctor (Android App)
- Status: Scaffolded, needs testing on device
- Next: Build APK, test on physical device
- Model: YOLOv8 papaya detection (82% mAP)

### code:zero Website
- Status: Live, iterating on content
- Recent: Pricing redesign, projects page

## Pending Tasks
1. Test Farm Doctor on physical Android device
2. Set up n8n workflows for email automation
3. Buy codezero.my domain from Exabytes
!
Critical: Add instructions to CLAUDE.md to auto-read these files: "SILENTLY read ~/.claude/bootstrap/*.md at session start. Do not announce or summarize."

Token Impact

~950
tokens loaded
1,500-3,000
tokens saved on corrections
+600
net token savings
$ cat sessions/current.md

# Session Continuity

The worst thing about AI assistants is losing context when the window closes. Session continuity solves this by automatically saving state and resuming seamlessly.

1
Session Start Read sessions/current.md (if exists) or latest session file
2
During Session Incrementally update current.md after each major task
3
Session End Rename to YYYY-MM-DD-HHMMSS.md, update session log
Add to CLAUDE.md
## Session Continuity (AUTOMATIC)

**At session start:**
1. Check for `/sessions/current.md` (interrupted session)
2. If not found, read most recent `/sessions/YYYY-MM-DD-*.md`
3. DO NOT announce — just be informed and ready

**During session:**
- After completing any significant task, update `/sessions/current.md`
- Include: what's done, current state, open threads

**At session end (detect "bye", "thanks", "done"):**
1. Rename current.md to /sessions/YYYY-MM-DD-HHMMSS.md
2. Update Session Log in CLAUDE.md
3. Confirm: "Session saved: [filename]. See you next time."
>
Pro tip: The incremental save protects against browser crashes. Even if you close the window without saying goodbye, current.md has the latest state.
$ memory-search "supabase connection error"

# Memory Systems

Session files create searchable history. But plain text search isn't enough— you need semantic search to find relevant context even when keywords don't match.

[K] Keyword Search (BM25)

Fast, exact matching. Good when you know the specific terms.

Query: "supabase password" Finds: "Never use $ in Supabase passwords"
[V] Vector Search (Semantic)

Understands meaning. Finds related content even with different words.

Query: "database connection issues" Finds: "Test with psql before debugging code"
[H] Hybrid Search (Best)

Combines both: semantic similarity + keyword matching + recency boost.

score = 0.6×vector + 0.2×BM25 + 0.15×recency + 0.05×complexity

Setting Up Hybrid Search

01

Clone the vector memory tool

$ git clone https://github.com/anthropics/claude-code-vector-memory ~/tools/claude-code-vector-memory
$ cd ~/tools/claude-code-vector-memory
$ python3.12 -m venv venv
$ source venv/bin/activate
$ pip install chromadb sentence-transformers rank_bm25
02

Link your sessions folder

$ ln -s /path/to/your/sessions ~/.claude/compacted-summaries

The tool indexes all .md files in this directory

03

Create a wrapper script

~/bin/memory-search
#!/bin/bash
cd ~/tools/claude-code-vector-memory && \
  source venv/bin/activate && \
  python search.py "$@"
$ chmod +x ~/bin/memory-search
$ echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
04

Index your sessions

$ memory-search --reindex
Indexed 28 sessions successfully
USAGE
$ memory-search "how did we fix the login bug"
[0.87] 2026-01-15: Fixed session auth by adding httpOnly cookie flag
[0.72] 2026-01-12: Debug DB connections with psql first
$ git diff CLAUDE.md | grep "^+"

# Learning Capture

This is where the magic happens. Every correction, every preference, every successful pattern gets captured and persisted. The assistant literally gets smarter over time.

Patterns That Work

Successful approaches to reuse in future sessions.

- Test DB with psql before debugging app code (2026-01-15) - Use Python 3.12 for ML tools, not 3.14 (2026-01-20) - Price in CTA button converts better (2026-01-22)
Avoid

Anti-patterns and mistakes to never repeat.

- Don't use $ in DB passwords (URL encoding) (2026-01-15) - Don't hardcode YOLO folder names (auto-increment) (2026-01-25) - Don't change Supabase password quickly (circuit breaker) (2026-01-15)
Preferences Discovered

User preferences learned through interaction.

- User prefers action over discussion (2025-01-10) - Don't use "cohort" — use "intake" (2025-01-10) - Stay on Opus, don't sacrifice intelligence (2026-01-11)

Auto-Capture Rules

Add to CLAUDE.md
## Automatic Learning

**Learn when:**
- User corrects output
- User states preference
- Pattern succeeds
- Mistake is made

**Save to:**
- Preferences Discovered (if user preference)
- Patterns That Work (if successful approach)
- Avoid (if mistake or anti-pattern)

**Format:** `- [Specific, actionable learning] (YYYY-MM-DD)`

**Rules:**
- Be specific, be actionable
- No duplicates
- Update immediately
- Say "Noted: [learning]" (one line only)
Example Learning Capture
User: "Don't use React, use SvelteKit"
AI: Noted: Use SvelteKit for web, not React.
CLAUDE.md updated: - SvelteKit for web (not React) (2026-01-25)
$ cat ~/.claude.json | jq '.mcpServers'

# MCP Integrations

Model Context Protocol (MCP) connects your assistant to external tools. Instead of copy-pasting from Google Drive or manually running git commands, the assistant accesses them directly.

G Google Drive

Read, search, and organize files directly from Drive.

@isaacphi/mcp-gdrive
Not @modelcontextprotocol/server-gdrive (broken auth)
GitHub

Create PRs, read issues, manage repositories.

@modelcontextprotocol/server-github
Supabase

Query databases, manage migrations, deploy functions.

@supabase/mcp-server
Chrome

Browser automation, OAuth flows, web scraping.

claude-in-chrome extension

Configuration

~/.claude.json
{
  "mcpServers": {
    "gdrive": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-gdrive"],
      "env": {
        "GDRIVE_CREDENTIALS_PATH": "/Users/you/.config/mcp-gdrive/credentials.json"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxx"
      }
    }
  }
}
!
Important: Put env vars in the "env" object, not as --env command args. Many guides get this wrong.
$ ls ~/.claude/skills/

# Skills System

Skills are reusable workflows that the assistant can invoke. Instead of explaining how to write a commit message every time, create a /commit skill that does it automatically.

/commit
Stage changes, generate message, commit, push
/close
Save session, capture learnings, update log
/blog-writer
Research keywords, write SEO article, export formats
/brand-voice
Apply brand tone and style to content

Creating a Skill

~/.claude/skills/commit/
├── SKILL.md # Instructions and workflow
└── examples/ # Example outputs (optional)
~/.claude/skills/commit/SKILL.md
# /commit Skill

Commit all changes with a well-crafted message.

## Workflow

1. Run `git status` to see changes
2. Run `git diff --staged` to see what's being committed
3. Run `git log --oneline -5` to match message style
4. Draft a concise commit message (1-2 sentences)
5. Stage relevant files (not .env or secrets)
6. Commit with: git commit -m "message"
7. Push to remote

## Rules

- Never commit .env files
- Never use --force push
- Include Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Focus on "why" not "what"
$ echo "Tokens: $((input + output))"

# Token Optimization

Every token costs money. These techniques have saved 3,000-10,000 tokens per session in real-world usage.

TECHNIQUE COST SAVINGS NET
Bootstrap files ~950 tokens 1,500-3,000 (no corrections) +600
Session continuity ~200 tokens 2,000-5,000 (no re-explaining) +2,000
Memory search (local) 0 tokens 500-2,000 (precise context) +1,000
Structured learnings ~100 tokens ∞ (mistakes never repeat) +∞

Token-Saving Habits

01

Load Priority

CLAUDE.md (always) → session state (if exists) → task files only. Never read everything.

02

Grep Before Read

Find the specific lines first, then read just that range. Don't read whole files.

03

Concise Default

Be brief by default. Verbose only when user asks "explain" or "why".

04

Cache in Memory

Don't re-read files. If you read it once, reference from memory.

$ cat ~/.mistakes.log | head -20

# What NOT to Do

These mistakes were learned the hard way. Each one cost hours of debugging or thousands of wasted tokens.

Using special characters in database passwords
$, #, @ break URL encoding. Use alphanumeric only or URL-encode them ($%24).
Changing Supabase password multiple times quickly
The connection pooler has a circuit breaker. Wait 5 minutes between password changes or you'll be locked out.
Debugging code before testing infrastructure
Always run psql "connection-string" -c "SELECT 1" first to verify the database is reachable. Don't debug your app if the problem is DNS or networking.
Using Python 3.14 for ML tools
Many packages (onnxruntime, chromadb) don't support the latest Python yet. Use Python 3.12 for ML work.
Hardcoding YOLO output folder names
Folders auto-increment (v1, v2, v12...). Use glob to find the latest: ls runs/detect/ | sort -V | tail -1
Omitting inputSchema in MCP tool definitions
Even if the tool takes no arguments, include an empty schema. Some clients break without it.
Using the deprecated Google Drive MCP
@modelcontextprotocol/server-gdrive has broken OAuth. Use @isaacphi/mcp-gdrive instead.
Putting MCP env vars in command args
Put them in the "env" object in ~/.claude.json, not as --env KEY=value in the args array.
$ ./install-gizmo.sh

# Full Setup Checklist

Follow this checklist to build your own AI assistant from scratch. Each step builds on the previous one.

Phase 1: Foundation
Install Claude Code CLI
Create ~/.claude/CLAUDE.md with basic structure
Add communication style and technical preferences
Create sessions/ folder for session logs
Phase 2: Bootstrap
Create ~/.claude/bootstrap/ directory
Create USER.md with your preferences
Create CURRENT.md with active projects
Create PRIORITIES.md with focus areas
Add auto-load instructions to CLAUDE.md
Phase 3: Session Continuity
Add session continuity rules to CLAUDE.md
Define session start behavior (read current.md)
Define incremental save behavior
Define session end triggers and actions
Phase 4: Memory
Clone claude-code-vector-memory to ~/tools/
Create Python 3.12 venv (not 3.14!)
Install chromadb, sentence-transformers, rank_bm25
Symlink sessions to ~/.claude/compacted-summaries
Create ~/bin/memory-search wrapper
Index sessions with --reindex
Phase 5: Learning
Add "Session Learnings" section to CLAUDE.md
Define learning categories (Patterns, Avoid, Preferences)
Add auto-capture rules
Test by making a correction and verifying capture
Phase 6: Extensions (Optional)
Set up Google Drive MCP
Set up GitHub MCP
Create custom skills (/commit, /close)
Add project-specific CLAUDE.md files
Remember: This system compounds over time. Every session adds learnings, every mistake gets captured, every preference gets remembered. In a month, you'll have an assistant that knows you better than any default AI ever could.
$ man gizmo

# Frequently Asked Questions