Don't Let Your Agent Re-Learn Your Repo: Use BORG.md for Instant Context

TL;DR

• Run borg learn once to generate a BORG.md file that summarizes your repo and is loaded at the start of every borg session.
• BORG.md cuts token usage by replacing a full codebase scan with one compact context file, saving input tokens on each run.
• Edit BORG.md manually or rerun borg learn after major changes to keep the agent's memory current.

To stop your AI coding agent from re-reading your entire codebase every time you start a new session, run borg learn once in your repo. It writes a BORG.md file that summarizes the project, so each new session loads one file instead of scanning thousands. We build and operate xShellz, including the borg terminal agent, and everything below is what we run in production ourselves.

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

Run borg learn once per repository. The command scans your project and writes a BORG.md file to the repo root. From then on, every borg session reads BORG.md first, so the agent starts with your project structure, key files, and commands already in context instead of exploring from scratch. This is the core of borg, the terminal coding agent from xShellz. If the repo changes substantially, rerun borg learn to refresh the file. No other setup is required; the one command is the entire mechanism.

how to give borg ai agent long term memory

The long term memory is the BORG.md file itself. After you run borg learn, that file persists in the repository root, and every new borg session loads it automatically. You can also edit BORG.md by hand to add notes the automated scan missed, such as coding conventions, known issues, or deployment steps. The file is plain Markdown, not a model weight or a vector database, so it is easy to inspect and version control. That simplicity is intentional: long term memory should be readable and auditable, not a black box.

what is borg learn command

borg learn is a borg subcommand that studies the current directory and writes a BORG.md context file. It is a one-shot command, meaning it runs and exits; you do not need to stay in the borg REPL. The typical usage is simply:

borg learn

After it finishes, the BORG.md file appears in the repo root. The command scans the project layout, identifies entry points, build systems, and important configuration, then writes a concise summary. You can run it once per repo and forget it until the structure changes. For comparison, a one-shot agentic task looks like borg "fix the failing test", but borg learn is specifically for creating the persistent context file.

how to reduce llm token usage with borg.md

BORG.md reduces token usage because the agent reads one compact file instead of the entire repository on every session start. Without it, the model spends input tokens re-reading files it has already seen, which costs money and adds latency. With BORG.md, the agent gets the project summary in a few hundred tokens, then loads only the specific files it needs to answer a question or make a change. Context is the most expensive part of an LLM call; the Model Context Protocol is one standardization effort, but a static BORG.md file is the simplest fix for a single repo.

how to make ai agent remember project structure

The BORG.md file stores the project structure: directories, entry points, build commands, and key modules. borg learn generates that summary automatically by reading the filesystem and common config files. You can then open BORG.md and add your own structural notes, like which folder holds tests or where generated code lives. Every new borg session loads this file before doing any work, so the agent knows the layout without exploring. If you reorganize the codebase, rerun borg learn to produce an updated file. No daemon or server is needed; it is just a file in the repo.

does borg ai agent support persistent context

Yes, borg supports persistent context in two ways. The BORG.md file provides long term repo knowledge across sessions, and the borg --resume flag continues the most recent conversation, preserving short term state. BORG.md is static and versionable, while --resume is ephemeral and tied to your last session. Together they cover both kinds of context an agent needs: what the project is, and what you were just doing. Both features work with any model, local or hosted.

Frequently asked questions

Does borg learn work without entering the interactive REPL?

Yes. borg learn is a one-shot command that runs, writes BORG.md, and exits. You can run it from a shell script or CI job without starting the borg REPL.

Do I need an API key before running borg learn?

You need any configured model to run borg, but borg learn itself just uses that model to generate the summary. Bring your own key for Ollama, LM Studio, OpenAI, or OpenRouter, or log in for hosted xShellz models with borg auth login.

Can I manually edit the BORG.md file after generating it?

Yes. BORG.md is plain Markdown in the repo root. Add custom instructions, known gotchas, or links to docs. The next borg session will load your edited version, so manual changes persist until you rerun borg learn.