smithfile

A protocol file for your AI agent. Drop a SMITH.md in any directory and any coding agent becomes a long-term collaborator that remembers who you are.

中文版 →

---

What is it?

smithfile is to AI agents what Makefile is to make, or what Dockerfile is to docker — a plain-text protocol file you put in a directory, that any tool can read and follow.

The protocol file is called SMITH.md. It tells any AI coding agent (Claude Code, Cursor, Codex CLI, etc.) how to load your identity, memory, and project knowledge at session start, and how to update them at session end.

This repo gives you a one-prompt bootstrapper for that file (and the supporting memory/ and wiki/ directories).

Install

In the directory where you want your agent to live:

1. Open your favorite AI coding agent (Claude Code, Cursor, Codex CLI, etc.)
2. Paste the contents of BOOTSTRAP.md
3. Answer 3 questions
4. Done — the agent has written SMITH.md, identity/, memory/, wiki/, and the first journal entry

No clone, no dependencies, no install script. The prompt is the installer.

What gets created

.
├── SMITH.md              ← the protocol file (read first by any agent)
├── CLAUDE.md             ← Claude Code adapter
├── README.md             ← description of this instance
├── identity/who-i-am.md  ← stable self-description
├── memory/
│   ├── MEMORY.md         ← index
│   ├── facts/            ← per-topic persistent facts
│   └── journal/          ← daily logs
└── wiki/index.md         ← project knowledge index

The default agent name in the bootstrap is Agent Smith (a nod to the protocol), but the installer asks you for a name — yours can be called anything.

How it grows

Day 1, your agent knows almost nothing — just your name, role, and current projects. As you work together, it accumulates:

• Facts as you mention them ("I'm based in Xi'an", "the deploy script is at scripts/deploy.sh")
• Feedback when you correct or confirm its behavior ("don't squash these commits", "yes, this PR shape is right")
• Journal entries for decisions, incidents, and milestones
• Wiki pages for project knowledge worth indexing

Everything lives in plain markdown — you can read, edit, grep, and version-control it.

Philosophy

Most "AI memory" systems try to be invisible — vector databases, hidden context, automatic summaries. smithfile goes the other way: your agent's memory is a directory you own.

You can:

• Read it — every fact your agent knows about you is one file
• Edit it — fix something the agent got wrong, by hand, in 5 seconds
• Move it across machines — it's just markdown
• Share parts of it — or keep it entirely private
• Audit it — see exactly what context your agent loads each session

Why the name?

Makefile made make portable. Dockerfile made docker portable. We need the same thing for AI agents: a file that any agent on any platform can read and use to act consistently. That file is SMITH.md. The framework is smithfile.

Customizing

After bootstrap, edit anything. Change the protocol in SMITH.md, restructure memory/, rewrite the identity. The framework is a starting point, not a constraint.

The only file your AI agent strictly needs to find is SMITH.md — everything else is convention you can change.

License

MIT