Project structure · Agent Needle

The canonical repository begins small. Additional memory directories appear only when they contain something useful.

Canonical structure

AGENTS.md
CLAUDE.md
README.md
LICENSE
.gitignore
.agent/
├── IDENTITY.md
└── CONFIG.md
.memory/
├── INDEX.md
└── ACTIVE.md

Root files

File	Purpose
`AGENTS.md`	Canonical lifecycle, execution, memory, and safety instructions.
`CLAUDE.md`	Optional Claude Code adapter that imports `AGENTS.md` without duplicating it.
`README.md`	Human-facing overview, installation summary, structure, attribution, and license link.
`LICENSE`	MIT license terms for using and adapting Agent Needle.
`.gitignore`	Excludes machine-local identity/configuration and temporary memory processing artifacts.

`.agent/`

IDENTITY.md defines stable agent purpose, operator context, repository scope, responsibility, and exclusions. It must not be treated as complete until placeholders are replaced.

CONFIG.md defines repository-level defaults for memory retrieval, redaction, persistence, and verification. Explicit operator instructions and higher-priority policies always win.

`.memory/`

INDEX.md is a routing table. It tells the agent where different kinds of durable knowledge live without forcing every memory file into each session.

ACTIVE.md is the concise resumption point: objective, status, verified progress, remaining work, blocker, next action, and relevant files.

The following directories are created only when needed:

.memory/
├── episodes/     Dated records of meaningful work
├── state/        Current verified facts
└── decisions/    Consequential choices and rationale

Keeping optional directories absent until useful makes the initial install small and prevents empty structure from masquerading as knowledge.