The BIUMIND.md memory file¶

BIUMIND.md is a persistent instruction file injected into every conversation — it tells the model the conventions, terminology, and "read this first" pointers for this project / this user. What you write here is sent to the model as part of the system prompt and takes precedence over default behavior.

biu also has a separate layer of auto-memory (/remember, ~/.biumind/memory/) that the model accumulates on its own across sessions. The division of labor between the two is in the comparison table at the end.

Loading hierarchy¶

At startup (and on /memory reload), biu collects memory files in the following order — files closer to the current directory are placed later, giving them more of the model's attention weight:

Layer	Path	Description
user	`~/.biumind/BIUMIND.md`	Your global personal preferences, shared across all projects
project	`BIUMIND.md` and `.biumind/BIUMIND.md` in every level from the filesystem root down to the current directory	Suited to monorepos: subdirectory conventions naturally override parent ones
local	`<current-dir>/BIUMIND.local.md`	Private to this machine; add to `.gitignore` and keep team-shared content out

Additionally, the BIUMIND.md and .biumind/BIUMIND.md inside extra working directories — registered via /add-dir, --add-dir, or permissions.additionalDirectories in settings.json — are also loaded (files duplicating the current directory are not injected twice).

All file contents are concatenated into one system prompt, each section annotated with its source, like:

Contents of /path/to/BIUMIND.md (project memory):
…

Size limits¶

Each file (including content expanded from @include) is capped at 40,000 characters; anything beyond is truncated and marked …(truncated). Convention-style content should never come close to this; if you find yourself truncated, that's the signal to move the detail into a separate document and pull it in on demand with @include.

The `@include` directive¶

An @path on its own line expands the target file's contents in place:

# Project conventions

@./docs/coding-style.md

@~/notes/domain-glossary.md

@/etc/example/absolute.md

Resolution rules:

@./xxx or @xxx — relative to the directory of the file containing it;
@~/xxx — expands to your home directory;
@/xxx — absolute path;
only an @ on its own line is a directive; an @someone mention embedded in prose is never expanded by mistake;
circular references are blocked automatically (each file is expanded at most once).

What to write¶

The template generated by biu init --with-memory gives the general advice:

Conventions that must be followed (code style, naming);
A domain glossary;
Key files / a "read this first" path index.

Some practical examples:

# Project notes

- Environment variables are always snake_case.
- Tests live in `./test/`, not `./tests/`.
- The entry point of the auth flow is `internal/auth/handler.go`.
- Commit messages use Conventional Commits.

[!TIP] For a new project you can simply run /init in the REPL: biu detects the project type (language, build tool, test commands) and generates a BIUMIND.md pre-filled with build / test / lint commands. Use /init --force to overwrite an existing one, or /init --dry-run to preview.

Excluding specific directories¶

claudeMdExcludes in settings.json keeps BIUMIND.md files under certain paths from being loaded (for example, some enormous monorepo subtree):

{
  "claudeMdExcludes": ["~/work/giant-monorepo/**"]
}

Patterns support *, ?, and ** (any depth) globs; strings without wildcards are matched as substrings against the absolute path. Entries from the three settings.json layers are merged and deduplicated.

REPL commands¶

Command	Purpose
`/memory`	List every loaded `BIUMIND.md` (source, path, character count) and the auto-memory status
`/memory reload`	Re-read after editing the files and hot-update the engine's system prompt, no restart needed
`/remember [-t <type>] <text>`	Save an auto-memory entry (default type=user)

Auto-memory¶

Auto-memory is a per-user persistent knowledge store that the model reads and writes on its own during conversations, rooted at ~/.biumind/memory/:

~/.biumind/memory/
  MEMORY.md       # Index: always loaded, capped at 200 lines / 25 KB
  <name>.md       # Individual memory entries with frontmatter; the model reads them with the Read tool on demand

The MEMORY.md index is always injected into the system prompt (truncated with a warning if over the limit); individual entries are not all preloaded — the model learns the directory's location and when to read/write from a primer and reads them itself when needed. If the index doesn't exist, the primer still applies and the model can create it during the conversation.

Division of labor with BIUMIND.md¶

	`BIUMIND.md`	Auto-memory
Describes	The project	The user, collaboration history, your feedback
Written by	You	The model (you can also append manually with `/remember`)
Scope	Per directory hierarchy (project / local)	Global (`~/.biumind/memory/`)
Loading	Full file contents injected	Index always resident; entries read on demand