The Genome

The Genome is a map of your codebase that Empryo builds when you open a project. It lists your files, the symbols they export and how files depend on each other, ranked by importance. A compact version of the map goes at the top of every prompt.

Because the agent can see the map, it rarely needs to spend a turn asking "where does auth live?" It starts from the right files.

What the agent seesLink to this section

A slice of the map looks like this:

src/services/auth/session.ts (→12)
  +SessionManager  Tracks active sessions, refresh tokens, expiry
  +SessionStore

• + marks an exported symbol.
• (→12) means 12 other files depend on this one.
• [NEW] marks a file changed in the last 48 hours.
• The text after a symbol name is a one-line summary, when summaries are on.

How files are rankedLink to this section

• Dependencies. Files that many other files import rank higher.
• Your current work. Files you just edited or mentioned get a boost for that turn.
• Git history. Files that usually change together are pulled in together.
• Live updates. When a file changes, the map is updated right away.

The scanner understands dozens of languages and file formats, including TypeScript, JavaScript, Python, Rust, Go, Java, C, C++, C#, Ruby, PHP, Swift and Kotlin.

SettingsLink to this section

The Genome works without any setup. Open /genome to see its status, rebuild or clear the index, or turn it off.

To change it in config:

{
  "genome": true,
  "semanticSummaries": "synthetic"
}

What gets scannedLink to this section

The scan sees what git sees: tracked and untracked files, minus anything your .gitignore excludes. Build output (node_modules, dist, build, target, coverage and similar) and dot-directories such as .github are skipped even if they are tracked. Outside a git repository, the same rules apply to a plain folder scan.

To bring a dot-directory back, negate it in .empryoignore, for example !Configs/.local/. Build output and internal folders such as .git stay out either way.

Keep files out of the mapLink to this section

Some files should stay in git but not in the map: test fixtures, benchmark inputs, a folder of SVGs. List them in a `.empryoignore` file at the project root. It uses the same syntax as .gitignore, including ! negations and **:

# Keep these in git, but out of the Genome
testenvs/
bench/
assets/
public/

Some files stay out in every project without any .empryoignore: package lockfiles (bun.lock, package-lock.json, Cargo.lock and the like), minified and bundled JavaScript, test snapshots, generated protobuf and Dart files, Xcode asset catalogs, and vendored folders such as vendor/, venv/, Pods/ and DerivedData/. A ! line in .empryoignore brings any of them back.

What happens:

• Matching files drop out of the map and out of code-wide file listings.
• The agent can still read or grep them by explicit path. They are hidden from discovery, not blocked.
• Saving .empryoignore or .gitignore triggers a quick rescan. Unchanged files are skipped, so it takes seconds.
• If a change would remove more than 80% of the index at once, Empryo treats it as a mistake and refuses. Use clear in /genome to force a rebuild.

Large repositoriesLink to this section

The map holds up to 10,000 files. In bigger repositories, the most recently changed files win, and /genome tells you the cap was reached. Excluding noise with .empryoignore makes sure the cap cuts fixtures rather than source code.

Skip the scanLink to this section

For a quick one-off question in headless mode, you can skip the scan:

empryo --headless --no-genome "what's the version?"

Setting the environment variable EMPRYO_NO_GENOME=1 does the same.