Preserving intent in codebases

January 14, 2026·6 min read

developer-toolsdocumentationaiopen-source

I build something to solve my "frustration" and since I decided to tidy it up and open-source it I wanted to also write a blog post to explain why I build it. We've all stood before Chesterton's Fence.

You open a file, stare at a bizarre block of code, and wonder: Why is this here?

  • Is it a brilliant hack to bypass a race condition?
  • A deprecated legacy fix?
  • Or just a mistake?

Git blame finds the author (often you, six months ago), but it only tells you who and when. The code tells you what changed but it rarely tells you why.

Code explains how a machine should execute a task. Version control explains what changed over time and by who. But the intent, the reasoning, the trade-offs, and the dead-ends explored, usually (in the best case) are lost in Jira/Linear tickets, RFC or ADR documents.

In the last 6 months I write code 90% using an agent, either Claude or Cursor, and there are two things that this way of working brings to the table:

  1. We provide context and intent
  2. Agents explain the reasoning behind the changes

My "frustration" though came from the fact that this part (what we ask agents and the chain-of-thought they follow is getting lost), and I believe is very important to preserve it.

I built Lore to fix this.

What is Lore?

Lore Logo

Lore is a reasoning "engine-repository" for code. It creates a high-context repository where AI agents and human developers don't just read code, they read the minds of the engineers/agents who came before them.

We treat documentation as a separate artifact, often disconnected from the reality of the codebase. Lore changes this by treating reasoning as a first-class citizen, sitting right alongside your source files.

It allows you to capture:

  • Intent: A brief description of what you were trying to accomplish.
  • Reasoning Trace: The full chain-of-thought (System 2 thinking).
  • Rejected Alternatives: Crucially, what you tried that didn't work, so future agents don't repeat your mistakes.

Example:

{
  "id": "05408b55-222e-4b61-89c2-0a860c4eea50",
  "target_file": "src/storage.rs",
  "file_hash": "06bff394cb36047294eb9669b9f112bc2a861df1830e15c32cc04ef1bf889463",
  "commit_hash": "698c1cb5dfcefb65bdbfb4335f3fc9bb8a370e5b",
  "agent_id": "claude-opus-4",
  "timestamp": "2026-01-14T15:26:03.858527Z",
  "intent": "Implement append-only merge strategy for handling reasoning conflicts",
  "reasoning_trace": "Implemented Solution 1 from the conflict resolution design:\n\nProblem: When two developers work on different branches and both record reasoning for the same module, traditional merge drivers would choose one version, losing valuable context from the other branch.\n\nSolution: Append-Only Merge Strategy\n\n1. Core Algorithm (storage.rs):\n   - Added merge_lore_indexes() function that combines two LoreIndex objects\n   - Uses HashSet to deduplicate entry IDs from both branches\n   - Preserves all entries from both 'ours' and 'theirs' sides\n   - Maintains entry_count and file structure correctly\n\n2. Git Integration (scripts/lore-merge-driver.sh):\n   - Shell script that acts as a Git merge driver\n   - Receives BASE, OURS, THEIRS parameters from Git\n   - Parses JSON, merges indexes using Python\n   - Outputs merged result to OURS\n   - Requires Python 3 (standard on modern systems)\n\n3. Configuration (.gitattributes):\n   - Tells Git to use the 'lore' merge driver for .lore/index.json\n   - Also configured for .lore/entries/*.json files\n\n4. Git Config:\n   - Set merge.lore.name and merge.lore.driver in local git config\n   - Driver path is relative: ./scripts/lore-merge-driver.sh\n\nWhy this approach:\n- Aligns with Lore's core philosophy: preserve all reasoning\n- No manual conflict resolution needed\n- Both branches treated equally\n- Deduplication prevents duplicate entries if both branches have same ID\n- Scalable: works for any number of concurrent branches\n\nTest Coverage:\n- test_merge_lore_indexes_no_conflict: Ensures merges work when files differ\n- test_merge_lore_indexes_with_conflict: Verifies both entries preserved\n- test_merge_lore_indexes_empty: Edge case with empty indexes\n- test_merge_lore_indexes_deduplication: Verifies duplicate removal\n\nAlternatives Rejected:\n- Last-writer-wins: Would lose reasoning from other branch\n- Conflict markers: Would require manual resolution (defeats purpose)\n- Separate merge branch: Too complex, harder to maintain\n- Manual merge UI: Not automated, requires developer intervention\n\nFuture Enhancements:\n- Merge visualization UI showing side-by-side reasoning\n- Entry-level merge for individual .lore/entries/*.json files\n- Merge statistics reporting (entries merged per file)\n- Agent-aware merging (different strategies for human vs AI agents)\n\nDocumentation (MERGE_STRATEGY.md):\n- Comprehensive guide covering all aspects\n- Usage examples showing before/after merge states\n- Troubleshooting section for common issues\n- Edge cases documentation\n\nAll 70 tests pass (4 new merge tests).\nImplementation is production-ready.",
  "rejected_alternatives": [
    {
      "name": "Last-writer-wins strategy (loses context)"
    },
    {
      "name": "Manual conflict resolution UI (not automated)"
    },
    {
      "name": "Separate merge branch (complex maintenance)"
    },
    {
      "name": "Only preserving most recent entry (loses history)"
    }
  ],
  "tags": [
    "merge-strategy",
    "conflict-resolution",
    "git-integration",
    "append-only"
  ]
}

Lore has a few basic commands:

Commands:
  init     Initialize a new Lore repository
  record   Record reasoning for code changes
  explain  Explain the reasoning behind a file
  search   Search through reasoning history
  list     List all recorded entries

The thing is that we don't want to manually record the reasoning and have to remember to include it as context everytime we make changes, so we need to give access to the tool to the agents. This can be done with rules, e.g. in a Claude.md:

You have access to a tool called `lore`.

Before you edit a file, 
run `lore explain <file>` to understand the hidden context.

After you finish a task, 
run `lore record` to save your chain-of-thought
so future agents understand your decisions.

The "Living Documentation" Philosophy

The concept isn't entirely new, but the execution needed a modern update for the AI era.

In his excellent book Living Documentation, Cyrille Martraire argues that documentation should be "reliable, low-effort, collaborative and insightful." He emphasizes that the best documentation is close to the code and evolves with it.

Four qualities of Living Documentation: Reliable, Low effort, Collaborative, and Insightful

Google follows the same philosophy for years treating documentation as code. In the book Software Engineering at Google there is a whole section on documentation, there they mention:

Four qualities of Living Documentation: Reliable, Low effort, Collaborative, and Insightful

Lore operationalizes this. Instead of a stagnant wiki page that rots, Lore entries are cryptographically linked to file content hashes. If the code changes, the reasoning is preserved as a historical record, creating an immutable history of thought.

AI Agents need context, not just tokens

We are moving into an era where AI agents (like Claude Code or Cursor) act as autonomous developers. But an AI is only as good as its context.

If you ask an agent to "refactor the auth module," it might eagerly suggest a library you already tried and rejected three months ago because of a specific edge case.

Lore integrates directly with these agents. By running lore explain, an agent can ingest the historical reasoning behind a file before it writes a single line of code. It effectively gives the AI "institutional memory".

Give it a try

Lore is open source and available now. You can use it manually via the CLI, or integrate it into your AI workflows with Claude Code and Cursor.