ContextForge

Persistent project memory for AI coding assistants.

Every AI session starts from zero. You re-explain your architecture, your decisions, your current tasks — every single time. ContextForge stores all of that once, in version-controlled markdown files your AI can read directly.

---

How it works

dart run contextforge init          # stores project context in .contextforge/
dart run contextforge task add      # log what you're working on
# tell your AI: "read .contextforge/ai_context.md, then implement task-1"

Your AI reads the context file, implements the task, and you log the decision. Next session — or the next developer — picks up exactly where you left off.

---

Requirements

Before installing, make sure you have:

• Dart SDK 3.0+ — install here
• Node.js — required for the MCP server
• One of VS Code, Cursor, or Windsurf

---

Installation

dart pub global activate contextforge
dart run contextforge init

---

IDE integration (MCP)

ContextForge runs a local MCP server that gives your AI assistant direct access to project context. This means the AI reads your architecture, tasks, and decisions automatically at the start of every session — you never paste context manually.

dart run contextforge init auto-configures the server for your IDE:

IDE	Flag	Config file created
VS Code	(default)	.vscode/mcp.json
Cursor	--ide cursor	.cursor/mcp.json
Windsurf	--ide windsurf	.windsurf/mcp.json

Once connected, open any project and your AI assistant has full context immediately.

If the server shows "not initialized"

After dart run contextforge init, the MCP server config is written automatically. Follow the steps for your IDE:

VS Code

1. Install the GitHub Copilot extension if you haven't already
2. Run dart run contextforge init in your project root
3. Open the Command Palette (Cmd+Shift+P)
4. Search for MCP: List Servers and open it
5. You should see contextforge listed — click Start
6. If it doesn't appear, run Developer: Reload Window from the Command Palette and check again

Config written to: .vscode/mcp.json

---

Cursor

1. Run dart run contextforge init --ide cursor in your project root
2. Fully quit and restart Cursor (not just reload)
3. Open Settings → Features → MCP
4. You should see contextforge with a green active indicator
5. If it shows red, click the refresh icon next to the server name

Config written to: .cursor/mcp.json

---

Windsurf

1. Run dart run contextforge init --ide windsurf in your project root
2. Fully quit and restart Windsurf
3. Open Windsurf Settings → Cascade → MCP Servers
4. Confirm contextforge appears and shows as connected
5. If not connected, click Refresh next to the server entry

Config written to: .windsurf/mcp.json

---

Verifying the connection

Run this in any IDE's AI chat after connecting:

Commands

Command	What it does
init	Set up ContextForge in the current repo
task add / list	Manage tasks with todo → in-progress → done workflow
feature add / list	Track features and their status
decision add / list	Log architectural decisions with rationale
analyze	Scan repo, detect tech stack, update ai_context.md
context	Regenerate ai_context.md from current project state
status	Show project overview
update	Interactively log development progress
prompt	Generate a full context prompt to paste into any AI tool
map	Print the project directory tree
focus	Set focus areas for the current session
doctor	Verify setup and diagnose issues
upgrade	Update the MCP server to the latest version

---

What gets created

Running dart run contextforge init creates a .contextforge/ directory that lives alongside your code. The key file is ai_context.md — this is what your AI reads at the start of every session. Everything else feeds into it: tasks, decisions, architecture notes. You maintain those; ContextForge keeps ai_context.md current.

.contextforge/
├── ai_context.md        ← the file your AI reads every session  ← START HERE
├── project.md           ← project overview and goals
├── architecture.md      ← architecture and data flow
├── progress.md          ← development timeline
├── decisions.md         ← ADR-style decision log
├── tasks.md             ← current task status
├── config.yaml          ← ContextForge configuration
├── data/
│   ├── tasks/           ← individual task files (YAML)
│   └── decisions/       ← individual decision files (YAML)
├── rules/               ← AI behavior guardrails
│   ├── git.md
│   ├── tasks.md
│   ├── files.md
│   └── communication.md
└── mcp_server/          ← local MCP server for IDE integration

Commit .contextforge/ to git. Anyone who clones the repo and runs dart run contextforge init gets a fully context-aware AI assistant immediately.

---

The rules system

ContextForge ships with a set of AI behavior guardrails stored in .contextforge/rules/. These cover:

• Git: no commits or pushes without explicit permission
• Tasks: only work on the active task, no scope creep
• Files: no silent file changes outside the task scope
• Communication: surface blockers early, ask before assuming

Rules are plain markdown — edit them to match your team's workflow.

---

Shareable context

ContextForge context is just files. That means:

• Onboarding: a new developer clones the repo, runs dart run contextforge init, and their AI already knows the full architecture and decision history
• Handoffs: log your current task before signing off; the next session picks it up without explanation
• Code review: AI reviewers have the same context as the author

---

Roadmap

• x Project context management (tasks, features, decisions)
• x MCP server for VS Code, Cursor, Windsurf
• x AI behavior rules system
• x Repository analysis and tech stack detection
• Security analyzer (dart run contextforge analyze --security) — flag common vulnerabilities directly in the context file so AI reviewers catch them without extra prompting
• Performance issue detection for Flutter projects — surface widget rebuild and rendering issues during analyze
• Architecture enforcement — diff AI-generated code against your architecture spec and warn on drift
• Web dashboard — manage context, tasks, and decisions without the CLI

---

Contributing

Issues and PRs welcome. If you want to contribute, the open roadmap items above are the best starting point — pick one and open an issue to discuss your approach before building.

---

License

MIT — see LICENSE.