Memory + FORGE.md

IsonForge reads context from a hierarchy of markdown files at session start. Use them to encode standards, architectural decisions, library preferences, and review checklists.

FORGE.md (project memory)

Drop a FORGE.md file at your project root. It's auto-loaded on every session in that project.

# FORGE.md

This is a TypeScript monorepo using pnpm + Turborepo. Targets Node 20.

## Conventions

- All API responses go through `lib/response.ts` for consistent error format.
- Prefer Zod for validation. No manual `if (!x)` chains.
- Database access via `src/db/` only. Never import drizzle directly from routes.

## Don't

- Don't add lodash. Use native JS.
- Don't introduce a new ORM. Drizzle stays.
- Don't write code without tests.

## Test commands

- `pnpm test` - all unit tests
- `pnpm test:int` - integration tests (requires `docker compose up -d`)

IsonForge loads the first 4 KB. Keep it focused on what's surprising or non-obvious about the project. Architecture, build commands, and team conventions are great. Generic best-practice rules (use prettier, write tests) waste tokens.

Generate a starter with:

isonforge init
# or inside REPL:
/init

This analyzes the codebase (tree, package.json, README, tsconfig, etc.) and writes a FORGE.md you can refine.

Edit later:

/memory

Opens FORGE.md in your $EDITOR.

Hierarchy

IsonForge walks up directories at session start, loading every FORGE.md it finds. Closer scopes override farther ones.

Path Scope
~/.isonforge/FORGE.md Global - applies to every project
<parent>/FORGE.md Parent directories up to home
<project-root>/FORGE.md Project - highest priority

This lets a monorepo set conventions at the root that nested packages can extend.

Global memory (#note shorthand)

Type #text at the prompt to append a note to ~/.isonforge/global-memory.md:

> #the deploy script needs `--env=staging` flag, easy to forget

Saved with timestamp and source-project name. Read later, or include in ~/.isonforge/FORGE.md via:

## Recent notes
{see ~/.isonforge/global-memory.md}

Per-session ephemeral

Anything you say in the conversation persists for that session only. To make a rule permanent, write it to FORGE.md.

What IsonForge does NOT remember

By default IsonForge does not write to memory automatically. It doesn't summarize past sessions, learn from corrections across runs, or surface "I noticed last time you said X." That's intentional - you control what persists.

If you want pattern-learning behavior, set up a hook on Stop that distills the session into FORGE.md updates.

Loading from --add-dir directories

Extra directories added with --add-dir are surfaced to the model as "additional working directories" in project metadata. FORGE.md files inside them are NOT auto-loaded by default. To include them, copy or reference them from your main FORGE.md.

Best practices