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:

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

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
Provide feedback - Correct the LLM with --follow when it makes a mistake, confuses concepts, or breaks conventions
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

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

Project context

If present in the project root, FNORD.md and FNORD.local.md are injected as system instructions each session. The local file is appended after the shared file and takes precedence on conflicts unless the user's prompt explicitly overrides. We recommend adding FNORD.local.md to .gitignore as a per-user configuration file.

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: Provide feedback:

fnord ask -p myproject -q "Review your memories. Use the memory tool to remove redundant, dated, and incorrect information."

Solution: Re-prime to consolidate:

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

Solution: Edit notes manually: As a final resort, you can directly edit the notes file:

nvim ~/.fnord/projects/<myproject>/notes.md

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)