Status: Current
ThinkForge projects can include persistent instructions for AI clients that work with the project through the ThinkForge MCP. The instructions travel with the project and are independent of a particular AI provider.
The Instructions File
Create one file named THINKFORGE.md directly in the physical project root:
Project Name/
THINKFORGE.md
.fire/
other project files...
The file is optional and uses ordinary Markdown. ThinkForge does not treat AGENTS.md, CLAUDE.md, .cursor/rules, TF Rules.md, or similarly named files as substitutes.
Retrieving Instructions
The MCP exposes get_project_instructions. Call it once before using other ThinkForge tools for a project.
The optional project parameter selects a named project. If omitted, ThinkForge uses the active project. Retrieving instructions does not require or initialize SK Memory for that project.
Example response when instructions exist:
{
"project": "Think Forge Docs",
"status": "loaded",
"has_instructions": true,
"file_name": "THINKFORGE.md",
"content": "# ThinkForge Project Instructions\n...",
"content_hash": "sha256-value",
"reload_policy": "restart_thinkforge",
"error": null
}
Example response when the project has no instructions file:
{
"project": "Project Name",
"status": "not_found",
"has_instructions": false,
"file_name": "THINKFORGE.md",
"content": null,
"content_hash": null,
"reload_policy": "restart_thinkforge",
"error": null
}
A missing file is normal and does not prevent other project tools from working.
Read-Once Behavior
ThinkForge reads THINKFORGE.md at most once per project while the application is running. It also caches missing, empty, and failed results.
If the file is created, edited, renamed, or deleted after its first access, restart ThinkForge before expecting clients to receive the change. There is no cache-refresh tool or automatic instruction reload.
The set_project_instructions tool can create or safely replace the physical file. Replacing an existing file requires the content_hash returned by get_project_instructions, preventing accidental overwrite of a newer version. The tool refuses to write while THINKFORGE.md is open in ThinkForge, saves atomically, and waits for SK Memory indexing.
A successful write returns reload_required: true; it deliberately does not alter the process-lifetime cached copy. The general get_document_by_path, update_document, and move_document tools reject THINKFORGE.md, keeping all reads and writes behind the dedicated read-once contract.
The file must be valid UTF-8 and no larger than 64 KB.
What to Put in the File
Use project instructions for guidance that should remain relevant across many tasks:
- Preferred terminology and writing style
- Folder and document organization
- Coding and architecture conventions
- Required validation steps
- Canonical source documents
- Expectations for keeping documentation current
Keep instructions concise, concrete, and free of temporary task details. Store project knowledge in normal project documents and reusable task procedures in skills.
Instructions Are Guidance
Project instructions are behavioral context, not an enforcement boundary. ThinkForge makes the content available and tells MCP clients to retrieve it, but the external client controls how instructions enter its model context.
Use application permissions and deterministic server validation for restrictions that must be enforced regardless of model behavior.
Relationship to Other Concepts
Project Instructions are persistent guidance for working with one project.
Skills are reusable procedures loaded for relevant tasks.
Policies are restrictions enforced by software.
SK Memory is indexed project knowledge used for search and retrieval.
These concepts can complement one another but are not interchangeable.