Getting started

Agent Needle is a small set of Markdown files that gives a coding agent durable context. There is no database or service to maintain.

Add Agent Needle to a project

Copy these files from the canonical iMythms/agent-needle repository:

AGENTS.md
.agent/
.memory/
.gitignore

If you use Claude Code, also copy CLAUDE.md. It imports AGENTS.md, keeping one canonical instruction source.

Configure identity and boundaries

Open .agent/IDENTITY.md and replace every placeholder you intend to rely on. Set the repository scope, responsibility, timezone, and explicit exclusions. Put machine-specific values in .agent/IDENTITY.local.md; it is ignored by Git.

Review .agent/CONFIG.md. The defaults deliberately prevent automatic commits, pushes, deployments, and publishing.

Start the first session

Launch your coding agent from the project root and describe the outcome you want. Agent Needle directs it to:

1. Read identity, configuration, and active work.
2. Retrieve only memory relevant to the request.
3. Inspect the real repository before trusting remembered state.
4. Make the smallest complete change.
5. Verify the outcome and record only durable context.

Repository first. Stored memory is a navigation aid, not automatic truth. Consequential facts must be verified against the current project.

A minimal first task

Add a health-check endpoint. Follow the repository's established patterns,
verify the route, and leave enough context for a later session to resume.

At the end, inspect .memory/ACTIVE.md if work remains. Add a dated episode only when the work produced a meaningful event worth preserving. Any record should be concise, factual, and free of secrets.