Stop Re-Reading the Whole Repo: How to Give Borg a Long-Term Memory

TL;DR

• borg learn creates a BORG.md context file that captures your project's architecture, so the agent doesn't re-index the entire repo on every session.
• You can run borg with a local Ollama model to slash token usage and keep your code private; the BORG.md file further reduces the context needed.
• The BORG.md file persists on disk, giving borg a long-term mental model of your project that survives terminal closes and system reboots.

borg learn solves this: it builds a BORG.md context file, letting the agent skip re-reading the entire codebase and instead load a concise summary. We run borg on our own xShellz fleet, where it saves our engineers hours of repeated context-loading.

how do i stop my ai coding agent from re-reading my entire codebase every time i start a new session?

Run borg learn in your project root. Borg will scan the repository, identify the key files, patterns, and architecture, and write a single BORG.md file that distills the whole codebase into a structured summary. The next time you start a session with borg, the agent reads that file instead of crawling every source file. The result is a massive reduction in both token consumption and time-to-first-useful-response. Borg is a single static Go binary, so you can drop it into any project and get a memory that outlasts the session.

what is borg learn and how does it work?

borg learn is a subcommand of the borg terminal coding agent that studies your repository and writes a project context file called BORG.md. It does not merely list files; it builds a high-level mental model of the codebase: entry points, module boundaries, dependencies, and conventions. Once the file exists, every subsequent borg session (both the REPL and one-shot tasks like borg "fix the failing test") loads it automatically, giving the model a head start without reading thousands of lines of raw code. The file lives in your repo root, so it moves with the project and can be reviewed or tweaked by hand.

how do i make borg create a BORG.md file for my project?

Open your terminal, navigate to the project root, and run:

borg learn

Borg will analyze the directory and write BORG.md. The command finishes quickly, even on large codebases, because it works with the model you have configured. You can then inspect the file with a text editor. If you later restructure the project, re-run borg learn to refresh the context. From that point on, any borg command or REPL session will load the summary, skipping the expensive full-tree re-read.

can i use borg with a local ollama model to save on token costs?

Yes. Borg is bring-your-own-model. If you point it at a local Ollama instance, you pay zero per-token fees and keep your code entirely on your machine. The BORG.md file cuts the context the model needs to ingest, so even with a modest local model you get fast, relevant responses. You can run borg learn with Ollama just as you would with any other backend; the command works identically. Configuration is stored in ~/.config/borg/ and can be set via BORG_* environment variables.

will borg remember my project structure if i close the terminal?

Absolutely. The BORG.md file is a plain text file on disk, not a piece of volatile session state. It persists across reboots, terminal closes, and even across machines if you commit it to version control. When you pick up a session later with borg --resume or start a fresh REPL, the agent immediately loads the file, regaining the same high-level understanding of your project. You are not starting from scratch every morning.

Frequently asked questions

Do I need to run borg learn every time I change the codebase?

Not automatically. You choose when to refresh the context. After a major refactor or adding a new subsystem, re-run borg learn to update the BORG.md file. Borg will always use the latest version on disk, and the command is fast enough to run as often as you like.

Can I use borg learn with a hosted model like Chuppa Flash?

Yes. First log in with borg auth login, then run borg learn as usual. The command works with any supported model backend: Ollama, LM Studio, OpenAI, OpenRouter, or the hosted xShellz models (Chuppa Flash, Chuppa Pro, Floko, Axiom). The resulting BORG.md file is model-agnostic.

Does BORG.md work with other AI coding agents, or only borg?

BORG.md is a plain Markdown file that any agent can be pointed at, but only borg knows to read it automatically and understands its internal structure. You can feed it manually to other tools as a project summary, though the seamless session-to-session memory is a borg-specific feature.