Agent Foundry

Agent Foundry is a small, safe, portable one-time seed for repositories built with coding agents. Copy it once, initialize or adopt its policy deliberately, and let the resulting repository own that policy without automatic template updates.

It is not a generator, dependency manager, memory platform, or autonomous-agent runtime. It does not choose a product, stack, hosting service, or external memory deployment for you.

Lifecycle

The source starts with Template state: template in AGENTS.md. In that state, only explicit template maintenance and initialization are allowed; placeholder command values must never be executed and unrelated project work must wait.

Initialization is the one-time transition to Template state: initialized. It resolves the project and command fields, selects a memory profile, replaces this source README wholesale with the real project README, and verifies the result. Adoption into an existing repository merges the policy instead and never overwrites that repository's README. Copied repositories own their initialized policy; Agent Foundry does not synchronize later changes.

File disposition

Path	New repository	Existing repository
README.md	Replace wholesale	Never overwrite
AGENTS.md	Initialize	Merge deliberately
CLAUDE.md	Retain when Claude is supported	Merge/import deliberately
.claude/settings.json	Retain; attribution suppression is intentional	Retain only if that shared policy is wanted
.gitignore	Extend for the stack	Merge, never replace
docs/LOCALRECALL.md	Retain only for an enabled LocalRecall profile	Copy only with an enabled profile
.codex/agents/memory-curator.toml	Retain only for localrecall-automatic	Copy only with localrecall-automatic
.claude/agents/memory-curator.md	Retain only for localrecall-automatic with Claude support	Copy only with localrecall-automatic and Claude support
scripts/verify-agent-config.sh	Retain	Copy with adopted policy
tests/verify-agent-config.sh	Source-maintainer tests; optional downstream	Do not copy during ordinary adoption
docs/superpowers/	Source design history	Do not copy during ordinary adoption
LICENSE	Retain; note the source commit	Preserve the MIT notice, with the source commit, for copied substantial portions

For none, remove docs/LOCALRECALL.md and both curator adapters. CLAUDE.md and .claude/settings.json follow their own rows above, not the memory policy.

CLAUDE.md is the minimal Claude Code import bridge. The tracked .claude/settings.json deliberately suppresses commit and pull-request attribution; an existing repository should retain it only when that shared policy is desired. Machine-local Claude settings belong in .claude/settings.local.json, which is ignored.

The source commit noted beside the MIT notice is advisory and never validated. It lets a later deliberate re-adoption start from a diff of the source between that commit and its head instead of a full re-read.

Initialize a new repository

1. Create a repository from this template, or copy the tracked payload into a new repository, note the source commit beside the MIT notice, and begin in a fresh agent session.
2. Read README.md, AGENTS.md, existing code, and available project or CI evidence before deciding values.
3. Resolve the project name, purpose, architecture, and setup, test, and verify commands from evidence or explicit user decisions. Ask rather than invent material product or stack choices.
4. Select one memory profile from the table below. No explicit operational memory decision means none, regardless of bundled documentation or visible tools. For an enabled profile, name the collection and operator and follow docs/LOCALRECALL.md.
5. Apply the memory rows of the file disposition table for the selected profile.
6. Change the template state to initialized, resolve every active token, and replace this README completely with a project-specific README that has no source marker.
7. Extend .gitignore for the chosen stack, and retain the agent adapters only for the products the repository supports.
8. Remove docs/superpowers/ and the source-maintainer test harness unless the downstream owner explicitly wants them.
9. Run the validator, then each configured setup, test, and verify command not marked not-applicable. The named operator completes the preflight in docs/LOCALRECALL.md before any enabled memory operation.

A blank repository may gain an approved minimal skeleton during initialization, but the agent must ask before making material product or stack choices. Do not begin feature work until initialization validates.

Adopt into an existing repository

1. Inspect the source template read-only and read the target repository's root and nested agent instructions, Claude instructions, README, ignore rules, build files, and CI configuration.
2. Never overwrite the target README.md. Merge AGENTS.md deliberately, preserve project-specific and more-specific nested rules, remove duplication, and report conflicts that cannot be reconciled.
3. Merge .gitignore; copy the validator with the adopted policy. Do not copy source-maintainer tests or docs/superpowers/ during ordinary adoption.
4. Merge or import CLAUDE.md only when Claude is supported. Retain .claude/settings.json only when its shared attribution policy is wanted.
5. Select a memory profile deliberately. No explicit operational memory decision means none; never infer an enabled profile from bundled documentation, an MCP registration, a collection-shaped name, or available tools. Apply the file disposition table, and keep endpoint, credential, and deployment configuration out of the repository.
6. Resolve all adopted fields from target evidence or user decisions, validate the result, and preserve the MIT notice, with the source commit, when copying substantial portions.

Memory profile

External memory is optional and disabled by default. The Memory profile field is the only stored selector; docs/LOCALRECALL.md derives tools, registrations, and file disposition from it.

Profile	Primary tools	Curator tools	Writes
none	none	none	none
localrecall-read-only	search,list_files,get_entry	none	outside coding agents
localrecall-automatic	search,list_files,get_entry	search,list_files,get_entry,add_document,delete_entry	curator subagent only

Primary agents read through the localrecall-reader MCP registration. localrecall-automatic additionally registers localrecall-curator for the dedicated curator subagent, which writes with the verified-replace procedure after substantial verified work. create_collection, list_collections, collection reset, and source ingestion appear in no agent allowlist. get_entry is a read-only fork extension of the LocalRecall MCP server that exposes an entry's body and chunk_count; the deployment must provide it, as the contract records.

Enforcement is client-side tool allowlisting; stock LocalRecall has no per-principal authorization. That trade-off is accepted because memory is a non-authoritative cache, reset is never available to agents, and the operator maintains backups. Collection names use underscores only (project_<slug>_memory); LocalRecall does not distinguish hyphenated and underscored forms of a name, so a hyphenated twin silently shares the index. Collection and operator values are non-secret logical identifiers; endpoints, credentials, and deployment details never enter the repository.

Migrate project memory policy

Migration from an earlier Agent Foundry memory policy is a deliberate edit protected by Git and verified by the validator; there is no migration script. When the repository notes the source commit it copied from, diff the source from that commit to its head to see every change to re-apply.

Legacy declaration	Replacement
localrecall-single-writer	localrecall-read-only
localrecall-gateway, either update mode	choose localrecall-read-only or localrecall-automatic deliberately
Ten-field memory tuple	the three memory fields
external-manual, curator-manual, curator-automatic	delete; behavior derives from the profile
Curator adapter allowlist without get_entry	re-vendor both adapters from the source

1. Choose the new profile with the user; never infer it from documentation or visible tools.
2. In AGENTS.md, keep exactly three memory fields — Memory profile, Logical collection, Memory operator — and delete every other legacy memory field line.
3. Apply the file disposition table: for none, delete docs/LOCALRECALL.md and both adapters; for localrecall-read-only, keep only docs/LOCALRECALL.md; for localrecall-automatic, keep the contract and the adapters for supported products. Delete any legacy docs/localrecall/ directory.
4. Re-vendor the current scripts/verify-agent-config.sh and, for localrecall-automatic, both curator adapters from the Agent Foundry source, and delete any vendored scripts/migrate-agent-memory.sh; the retired migrator and the old ten-field validator predate this model.
5. Run scripts/verify-agent-config.sh; it names any remaining legacy declaration.
6. Review the diff and commit through the repository's normal Git workflow. The named operator repeats the preflight before enabled memory use resumes.

Worked example

An initialized AGENTS.md for a small project resolves the tokens like this; every other section carries over from the template unchanged:

- Template state: `initialized`

## Project

- Name: `shortlist`
- Purpose: `Command-line tool that ranks reading lists from plain-text notes`
- Architecture: `Single Python package with a Click CLI and a pytest suite`

## Project memory

- Memory profile: `localrecall-read-only`
- Logical collection: `project_shortlist_memory`
- Memory operator: `external:memory_platform`

## Commands

- Setup: `python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'`
- Test: `.venv/bin/pytest`
- Verify: `.venv/bin/pytest && .venv/bin/ruff check .`

The repository keeps docs/LOCALRECALL.md, has no curator adapters, and its README carries no source marker.

Command fields

Each initialized Setup, Test, and Verify field contains the real command. When a command is genuinely absent, use not-applicable: reason with a concrete reason. Bare none is invalid. Command fields describe repository-root commands and are never executed while they still contain template tokens.

Validation

The validator requires Git, Bash, standard POSIX text utilities, and either jq or python3 when the repository tracks JSON. Its success establishes static repository consistency only: it does not contact LocalRecall, verify collection existence, test credentials, or inspect actual coding-agent tool registration, and therefore does not establish runtime readiness.

Verify the Agent Foundry source with:

bash tests/verify-agent-config.sh
scripts/verify-agent-config.sh
git diff --check
git status --short

For an initialized repository, run scripts/verify-agent-config.sh first, then the configured Setup, Test, and Verify commands, skipping only fields that use the explicit not-applicable: reason form. Finish with git diff --check and review of the complete diff.

Upstream references

• Codex repository instructions
• Claude Code memory and instruction files
• LocalRecall
• LocalAI
• LocalAI documentation
• LocalRecall MCP server