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

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

Config written to: .vscode/mcp.json

Cursor

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

Config written to: .cursor/mcp.json

Windsurf

Run dart run contextforge init --ide windsurf in your project root
Fully quit and restart Windsurf
Open Windsurf Settings → Cascade → MCP Servers
Confirm contextforge appears and shows as connected
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.