Learning System

Fnord builds a searchable knowledge base about your project as it researches your questions, improving its ability to answer complex questions over time.

How It Works

As fnord researches your questions, it:

Makes observations about your code
Draws inferences about architecture and patterns
Saves facts organized by topic
Makes this knowledge searchable for future questions

This accumulated knowledge helps fnord:

Answer complex questions faster
Make better connections between code components
Understand project-specific terminology and patterns
Provide more accurate and contextual responses

Viewing Learned Knowledge

See what fnord has learned about your project:

fnord notes --project myproject

Output is markdown, so pipe through a markdown viewer:

fnord notes --project myproject | glow

Notes Organization

Notes are organized by topic:

Architecture - System design, component relationships
Patterns - Coding patterns, conventions observed
Domain Knowledge - Business logic, terminology
Technical Details - APIs, data structures, algorithms
Testing - Test strategies, coverage areas

Priming the Knowledge Base

Generate an initial set of learnings without asking specific questions:

fnord prime --project myproject

What priming does:

Explores project structure and organization
Identifies key components and their relationships
Documents common patterns and conventions
Creates initial set of searchable facts

Options:

# Use more research rounds for deeper analysis (default: 3)
fnord prime --project myproject --rounds 5

# Prime and view results
fnord prime --project myproject && fnord notes --project myproject | glow

When to prime:

After initial indexing of a new project
After major refactoring or architecture changes
When notes become stale or outdated

Knowledge Growth Over Time

The knowledge base grows naturally through use:

Ask questions - Each research session adds new facts
Follow-up questions - Builds deeper understanding
Cross-file insights - Connects related components
Pattern recognition - Identifies recurring structures

Example progression:

# First question
fnord ask -p myproject -q "Where is authentication handled?"
# Learns: auth module location, basic structure

# Follow-up
fnord ask -p myproject --follow <ID> -q "How does it integrate with the database?"
# Learns: database integration patterns, models used

# Later question
fnord ask -p myproject -q "What's the pattern for adding a new API endpoint?"
# Can now reference learned patterns and conventions

Managing Knowledge

Knowledge Storage

Notes are stored in: ~/.fnord/projects/<project>/notes.md

Structure:

~/.fnord/projects/myproject/
└── notes.md          # Consolidated learned knowledge

Dealing with Staleness

As your codebase evolves, some learned facts may become outdated:

Signs of stale knowledge:

Fnord references old code that's been refactored
Architecture descriptions don't match current state
Pattern recommendations no longer apply

Solutions:

Re-prime - Regenerate knowledge base

# Backup old notes if desired
mv ~/.fnord/myproject/notes ~/.fnord/myproject/notes.backup

# Re-prime
fnord prime --project myproject --rounds 5

Targeted updates - Ask specific questions about changed areas

fnord ask -p myproject -q "The authentication module has been refactored. Please analyze its new structure and update your understanding."

Re-index - Refresh semantic index to match current code
```
fnord index --project myproject
```

Dealing with Redundancy

Over time, notes may accumulate redundant or overlapping information.

Current approach:

Manual review via fnord notes
Re-priming periodically to consolidate

Note: Automatic deduplication/consolidation is a potential future enhancement.

Integration with Semantic Search

The learning system complements semantic search:

Feature	Purpose	When Used
Semantic Index	Find relevant code	Every search and ask
Learned Notes	Understand context	Complex questions requiring connections
Git History	Track changes	Historical questions

Together, these create a comprehensive understanding of your project.

Best Practices

Prime after indexing - Start with a solid knowledge foundation

fnord index --project myproject
fnord prime --project myproject

Let it grow naturally - Ask questions as they arise, knowledge accumulates
Use follow-up questions - Builds deeper, more connected understanding
Re-prime periodically - After major changes or when notes feel stale
Review notes occasionally - Understand what fnord knows about your project
```
fnord notes --project myproject | glow > project-knowledge.md
```

More rounds for depth - Use --rounds for thorough analysis

fnord ask -p myproject --rounds 5 -q "complex architectural question"

Technical Details

Storage Format

Notes are stored as structured markdown with topic categorization and metadata for semantic search integration.

Research Process

When fnord researches a question:

Searches learned notes for relevant context
Performs semantic search on code
Executes tool calls as needed
Synthesizes findings
Saves new insights to notes

Learning Scope

Fnord learns:

✅ Code structure and organization
✅ Patterns and conventions
✅ Component relationships
✅ Domain-specific terminology
❌ Not: Sensitive data, credentials, secrets

Troubleshooting

Notes command returns nothing

Cause: No knowledge has been accumulated yet

Solution:

# Prime the knowledge base
fnord prime --project myproject

# Or ask some questions first
fnord ask -p myproject -q "What is the overall architecture of this project?"

Notes seem outdated

Cause: Code has changed since notes were generated

Solution: Re-prime or ask targeted update questions (see Managing Knowledge above)

Too much redundant information

Cause: Overlapping learning from multiple research sessions

Solution: Re-prime to consolidate:

mv ~/.fnord/myproject/notes ~/.fnord/myproject/notes.old
fnord prime --project myproject --rounds 5

Future Enhancements

Potential improvements to the learning system:

Automatic fact consolidation and deduplication
Versioned knowledge tracking (matching git commits)
Knowledge export/import for team sharing
Confidence scoring for learned facts
Active learning (requesting clarification)