Chat Card Context: Making Your AI Smarter with Index Cards

Overview

The AI2U chat system automatically searches your index cards and includes relevant ones as context when responding to your messages. This means the AI can reference your personal knowledge base, making it much more helpful for your specific needs.

How It Works

Smart Message Analysis

When you send a message, the system intelligently decides whether to search your cards:

Casual greetings are skipped: Messages like "hi", "hey", "thanks" won't trigger a search
Meaningful questions trigger searches: "Tell me about Docker" will search for Docker-related cards
Mixed messages work perfectly: "Hey, can you explain kubernetes?" will search for kubernetes (ignoring the "hey")

What Gets Searched

The system searches three parts of your cards:
- Card titles (weighted most heavily - worth up to 2 points)
- Card content (body text - worth up to 1 point)
- Card tags (exact matches add +1 point each, capped at 2 points total)

How Cards Are Selected - The Hybrid Scoring System

Our advanced hybrid scoring system combines NLP (Natural Language Processing) with keyword matching to find the most relevant cards:

1. NLP Scoring (Primary Component: 0-10 points)

The system uses multiple AI algorithms to understand semantic meaning:
- TF-IDF similarity (40% weight): Term frequency analysis
- Jaccard similarity (20% weight): Set-based similarity matching
- Fuzzy matching (20% weight): Handles typos and variations
- Tag matching (15% weight): Semantic tag similarity
- Card type boost (5% weight): Prioritizes main cards over subcards

2. Keyword Boost (1-3 points)

Direct keyword matches add bonus points:
- Title matches: 0-2 points (0.5 per term, max 2.0)
- Content matches: 0-1 point (0.25 per term, max 1.0)
- Multiple matches compound the score

3. Tag Bonus (0-2 points)

Exact tag matches provide additional points:
- +1 point per exact tag match
- Capped at 2 points to prevent score inflation
- Tags must match exactly (case-insensitive)

The Complete Scoring Formula

Total Score = NLP Score + Keyword Boost + Tag Bonus
- Maximum possible score: 15 points
- Minimum threshold: 0.3 points (cards below this are filtered out)
- Top 10 cards by score are included in context

What the Scores Mean

With the hybrid scoring system (0-15 points total):
- 12.0 or higher: Exceptional match - strong NLP similarity + keyword matches + tags
- 8.0 to 11.9: Highly relevant - good semantic match with some keyword/tag bonuses
- 4.0 to 7.9: Moderately relevant - decent NLP score or strong keyword matches
- 0.3 to 3.9: Lower relevance - weak matches, but still included if in top 10
- Below 0.3: Filtered out - not relevant enough to include

Why Some Cards Score Higher Than Others

Understanding the scoring hierarchy:
- NLP similarity is primary - Semantic understanding drives most of the score (0-10 points)
- Title matches beat content - Title keywords worth 1 point each, content only 0.5
- Exact tag matches add bonus - Each matching tag adds 1 point (max 2)
- Parent-child relationships matter - Subcards get 20% boost if parent main card scores well
- Card type affects score - Main cards get slight preference over subcards
- Nano cards are special - Never appear in search directly, only included with parent subcards

Card Hierarchy System

The system intelligently handles three types of cards:

Main Cards (M-XXXXXX)

Primary knowledge units
Scored normally in searches
Can boost their related subcards

Sub Cards (S-XXXXXX)

Detailed breakdowns of main cards
Scored independently
Get 20% score boost if their parent main card scores above threshold
Automatically bring their nano children when selected

Nano Cards (N-XXXXXX)

Granular details and examples
Never appear directly in search results
Automatically included when parent subcard is selected
Inherit 50% of parent subcard's score

This hierarchy ensures you get complete context - when a subcard is relevant, its nano details come along automatically.

Auto-Promotion System

The chat includes an intelligent auto-promotion feature:

How Auto-Promotion Works

The #1 highest-scoring card is automatically promoted to conversation context
Appears with a ✨ sparkle indicator
Shows toast notification when promoted
Maximum 5 auto-promotions per conversation (configurable)

Benefits

Most relevant information stays accessible throughout conversation
Promoted cards are excluded from future searches (no duplicates)
Reduces repetitive context switching
AI maintains awareness of key topics

Managing Auto-Promoted Cards

View promoted cards in the conversation context modal
Remove auto-promoted cards if not needed
Manually add additional cards alongside auto-promoted ones

Context Exclusion System

Cards already in your conversation context are intelligently excluded:

What Gets Excluded

Auto-promoted cards - Already in context, no need to search again
Manually enabled cards - Cards you've explicitly added
Removed cards temporarily excluded - If you remove an auto-promoted card, it can appear in searches again

Why This Matters

Prevents duplicate information in AI responses
Allows discovery of new relevant cards
Keeps context fresh and diverse
Maximizes the 10-card limit effectiveness

Making Your Cards More Findable

Best practices for creating cards that the system can easily find:

1. Write Descriptive Titles

The title is your card's most important feature for search:
- Include the main topic or concept
- Use the terms you'd naturally search for
- Be specific rather than generic

Examples:
- ✅ Good: "Docker Container Commands"
- ❌ Poor: "Notes from Tuesday"

2. Use Consistent Terminology

Keep your vocabulary consistent across related cards:
- Pick one term and stick with it (e.g., always "Kubernetes" or always "K8s")
- Create a "terminology card" for projects to maintain consistency
- Include common variations in the content

3. Tag Thoughtfully

Tags give your cards a relevance boost:
- Use tags for the main topic area (e.g., "docker", "python", "react")
- Add project-specific tags (e.g., "storm-dev", "client-x")
- Keep tags simple and lowercase for best matching

Help the AI find your cards by including variations:
- Spell out acronyms: "Kubernetes (K8s)"
- Include related concepts: "PostgreSQL database SQL"
- Add common misspellings if relevant

5. Write Naturally

The AI understands context, not just keywords:
- Write complete thoughts and explanations
- Include examples and use cases
- Don't just list keywords - explain concepts

Advanced Search Tips

1. Use Quoted Phrases for Exact Searches

If you want to find specific cards, use quotes in your message:
- "Docker networking" will prioritize cards with that exact phrase
- Without quotes, it searches for "Docker" and "networking" separately

2. Leverage Your Tags

Since tags now contribute to scoring:
- Search by tag name to find all cards in a category
- Combine tags with other terms for precise results
- Example: "docker production" finds production Docker cards

3. Mix Natural Language with Keywords

The system understands both:
- Natural: "How do I deploy my app with Docker?"
- Keywords: "Docker deployment production"
- Both work well, use what feels natural

The AI understands relationships:
- Searching "container" may also find "Docker" cards
- "Database" searches might surface "PostgreSQL" or "MySQL" cards
- The system connects related concepts automatically

User Experience

What You'll See

When the system finds relevant cards, you'll see activity indicators:
1. "Searching X index cards..." - The system is looking through your cards
2. "Found X relevant cards" - Cards have been found and will be included
3. The AI response will then incorporate information from those cards

When Cards Won't Be Searched

You won't see any search activity for:
- Simple greetings ("hi", "hello", "thanks")
- Very short messages with only common words
- Messages with no meaningful search terms

Examples

Example 1: Technical Question

You write: "How do I use Docker volumes?"

What happens:
1. System extracts: "docker", "volumes"
2. NLP scoring finds semantically related cards (0-10 points)
3. Cards with "Docker" in title get +1-2 point boost
4. Cards mentioning "volumes" in content get +0.5 point boost
5. Tagged cards (#docker) get +1 point bonus
6. Example scores: "Docker Volumes Guide" (12.5), "Docker Basics" (8.2), "Container Storage" (6.1)
7. Top card auto-promoted with ✨ indicator
8. AI responds with your specific Docker notes plus its knowledge

Example 2: Casual Greeting

You write: "hey there"

What happens:
1. System recognizes this as a greeting
2. No card search is performed
3. AI responds normally without card context

Example 3: Greeting + Question

You write: "Hi! Can you help me understand Python decorators?"

What happens:
1. System ignores "hi", "can", "help", "me" (stop words)
2. Extracts: "understand", "python", "decorators"
3. NLP scoring evaluates all cards for semantic similarity
4. Example scores: "Python Decorators Explained" (13.2), "Python Functions" (7.8), "Advanced Python" (5.4)
5. If "Python Decorators Explained" has subcards, they get 20% boost
6. Any nano cards under selected subcards automatically included
7. #1 card auto-promoted, others included up to 10 total

Best Practices

Organizing Your Knowledge Base

Create cards as you learn - Don't wait to create "perfect" cards
Update cards regularly - Keep information current
Link related concepts - Mention related topics in card content
Use consistent terminology - Pick one term and stick with it

Getting Better Results

Be specific in your questions - "Docker networking" beats "Docker stuff"
Use the terminology from your cards - If your card says "Kubernetes", don't search for "K8s"
Ask follow-up questions - The context builds throughout the conversation

Managing Card Volume

The system includes up to 10 cards per message
Most relevant cards are prioritized automatically
If you have many similar cards, the best matches will be selected
Consider consolidating very similar cards for better results

Technical Details

The Hybrid Scoring Algorithm

The system uses sophisticated NLP techniques:

TF-IDF (Term Frequency-Inverse Document Frequency):
- Measures word importance in your cards
- Common words get lower weight
- Unique, specific terms score higher

Jaccard Similarity:
- Compares word sets between query and cards
- Intersection over union calculation
- Good for short, precise matches

Fuzzy String Matching:
- Handles typos and variations
- "Kuberentes" still finds "Kubernetes" cards
- Levenshtein distance calculation

Vector Caching:
- Computed vectors are cached for performance
- Instant searches even with hundreds of cards
- Cache cleared when cards are updated

Configuration

The scoring system is configurable:
- maxCardsForContext: 10 (how many cards to include)
- minRelevanceScore: 0.3 (minimum score threshold)
- maxAutoPromotions: 5 (per conversation)
- Algorithm weights: Adjustable for different use cases

Privacy and Performance

Your Data Stays Local

Cards are stored in your browser's localStorage
Searches happen entirely on your device
Only relevant cards are sent with your message
You control what information the AI sees

Performance Considerations

Searching is instant even with hundreds of cards
No network requests needed for card search
Results are cached during your conversation
The system is optimized for speed

Future Enhancements

Coming soon:
- Semantic search: Find cards by meaning, not just keywords
- Learning from usage: The system will learn which cards you find most useful
- Custom contexts: Create card collections for specific projects
- Card suggestions: AI will suggest new cards based on your conversations

Troubleshooting

Cards Not Appearing in Context?

Check if cards exist: Open the Index Cards app and verify you have cards
Use meaningful search terms: Avoid very common words
Check your spelling: The search is exact match
Look at card titles: Make sure key terms are in titles, not just content

Too Many Irrelevant Cards?

Be more specific: Add more search terms to narrow results
Use quotes: "exact phrase" for precise matching
Update card titles: Make them more descriptive and unique

System Not Searching at All?

Add more content: "Hey" alone won't search, but "Hey, tell me about X" will
Avoid pure greetings: The system skips courtesy messages
Include actual topics: Make sure your message has searchable terms

This intelligent card context system makes your AI assistant truly personal - it knows what YOU know!