Architecture Overview

A comprehensive breakdown of how the Lore CLI is structured internally across its five core layers.

The Directory Structure

The lore-memory codebase is split into five main conceptual areas inside the src/ directory, designed around the Unix philosophy: do one thing well, be highly modular, and enable standard piping.

Lore/
├── bin/
│   └── lore.js          # The CLI entry point and interactive menu
├── src/
│   ├── commands/        # CLI wrappers for every command (e.g. `lore log`, `lore why`)
│   ├── lib/             # The core "engine" (file parsing, AI embeddings, scoring)
│   ├── watcher/         # The passive automation engine (AST parsing, graph building)
│   ├── mcp/             # The Model Context Protocol integration for Claude/Cursor
│   └── ui/              # The local web dashboard frontend
└── package.json

1. The Entry Point (bin/)

This acts as the front door for the application.

• Uses the commander package to register and parse all CLI subcommands.
• Provides an Interactive Menu (via inquirer) if the user simply types lore.
• Includes a custom Fuzzy Command Matcher utilizing Levenshtein distance. If a user mistypes a command (e.g., lore servee), it gracefully suggests or aliases the correct command.

2. The Core Engine (src/lib/)

This directory is the absolute backbone of Lore, containing the business logic for reading, writing, and scoring knowledge entries.

• entries.js & index.js: Manage the .lore/ directory. Handle reading/writing the actual Markdown/JSON files and maintaining a fast lookup index.
• relevance.js: Implements the Blast Radius Algorithm — scoring how relevant an entry is to a specific file based on graph weighting.
• embeddings.js: The AI semantic layer. Talks recursively to a local Ollama instance (nomic-embed-text) to convert entries into vector embeddings.
• budget.js: Intelligently truncates contexts (starting with lowest relevance entries) to ensure the MCP server never blows up an LLM's context window.

3. The Commands (src/commands/)

These files act as thin wrappers. They parse user input from the CLI, format the output with chalk, and pass the real work down into src/lib/.

• init.js: Bootstraps the `.lore/` folder and dynamically injects the Architect-in-the-Loop hook into Git.
• prompt.js: Takes a natural language query, runs semantic search, and builds a strictly formatted system prompt.

4. The Passive Engine (src/watcher/)

This directory is what enables Lore's automated "magical" feeling.

• comments.js: Uses the Babel Parser to build an AST of Javascript/Typescript files, extracting comments against signal words to generate drafts.
• graph.js: AST parser that traverses import statements to build a living dependency graph.
• staleness.js: Compares the mtime of source files against the timestamps of Lore entries.

5. The MCP Server (src/mcp/)

Allows Lore to talk directly to AI coding assistants using the Model Context Protocol.

• server.js: Exposes Lore internal functions as secure "tools" over stdio.
• tools/why.js: Maps Claude's `lore_why` tool request directly to internal relevance logic.