Agent Context Framework
Lightweight, file-based framework for bootstrapping, preserving, and handing off project context across AI agent sessions.
Ask AI about Agent Context Framework
Powered by Claude · Grounded in docs
I know everything about Agent Context Framework. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Agent Context Framework (ACF)
Lightweight, file-based framework for bootstrapping, preserving, and handing off project context across AI agent sessions.
Agent Context Framework helps teams keep continuity in AI-assisted software projects, especially across fresh sessions, context resets, and handoffs. Canonical project state lives in Markdown files under context/*, while MCP Memory serves as a supporting semantic recall layer.
For the Polish version, see PRZECZYTAJ_MNIE.md.
Why ACF
- keeps a canonical, file-based source of truth in
context/* - gives agents a repeatable startup and handoff workflow
- reduces repeated re-explanation after compaction or session resets
- keeps MCP as a supporting memory layer instead of the only project record
- stays lightweight in architecture while covering a broad project workflow
Scope Boundary
ACF should stay lightweight by default. For the detailed product boundary and future-tier guidance, see docs/acf_scope_boundary.md.
Agent Compatibility
ACF is agent-agnostic at the workflow level.
That means the core model works with:
- Codex
- ChatGPT
- Claude
- Cursor
- Aider
- Continue
- custom CLI or editor agents
The framework itself is based on:
- canonical context files in
context/* - repeatable startup and handoff rules
- MCP as an optional supporting memory layer
Some automation in this repository is Codex-aware, especially MCP registration scripts, but the workflow itself does not depend on Codex.
What You Get
context/next_context_sync.mdfor startup and active code-map referencescontext/project_map.mdfor lightweight repository orientation and module layoutcontext/procedures/for procedural memory and repo-specific ways of doing recurring workcontext/handoff_migration.mdfor technical state, decisions, and runbookscontext/context_change_history.mdfor history, tests, and commitscontext/master_plan.mdfor scope and delivery policytools/acf_setup.shas the unified interactive entrypointtools/init_project_context.shfor direct project initializationtools/bootstrap_existing_project.shfor draft context generation in existing repositoriestools/generate_project_map.jsfor draft project-map generationtools/sync_project_map.jsfor refreshing a generated project-map draft without overwriting manual editstools/verify_context_links.jsfor code-reference validationtools/verify_project_map.jsfor project-map path validationtools/run_next_verification.jsfor running the verification command fromnext_context_sync.mdtools/archive_context_history.jsfor archiving older change-history entriestools/acf_status.jsfor a quick framework status summary- MCP helper scripts for container setup, registration, and smoke checks
Requirements
bashnodeandnpmpython3podmanfor the container-based MCP workflowcodexif you want automatic MCP registration from the setup flow
After Download
If you just downloaded or cloned this repository, use this exact order:
- Move into the repository directory.
- Install dependencies:
npm install
- Start the unified setup:
npm run acf:setup
- When prompted, choose one mode:
newif you are starting a fresh project from this frameworkexistingif you are attaching the framework to a repository that already has code
- During setup, ACF can also:
- create and start Podman containers for MCP Memory
- register MCP Memory in Codex
- optionally register a repo-scoped filesystem MCP server
- After setup finishes, review:
context/next_context_sync.mdcontext/project_map.mdcontext/procedures/README.mdcontext/handoff_migration.mddocs/mcp_ai_memory_setup.md
- Verify the generated context references:
npm run verify:context
- Continue with:
- NEW_PROJECT_CHECKLIST.md for operational setup
- docs/system_flow.md to understand how file-based context and MCP Memory work together
Start Modes
New Project
Choose new when:
- you are creating a project from scratch
- you want the framework to initialize clean placeholders and MCP naming
- you want to fill in the context files as the project begins
What ACF does in this mode:
- initializes project placeholders
- generates
config/project.env - prepares context files for a new project
- can create and register MCP infrastructure
Existing Project
Choose existing when:
- the repository already contains real code
- you want to attach ACF to an existing codebase
- you want draft context files generated from a repository scan
What ACF does in this mode:
- initializes project-specific config
- scans the repository for manifests, likely stack, top-level directories, and likely entrypoints
- generates draft context files and marks them for human review
- can create and register MCP infrastructure
Important:
existingmode generates a starting draft- the user should review and correct the generated context files before treating them as canonical
Quick Start
If you already know the framework and just want the shortest path:
npm install
npm run acf:setup
npm run verify:context
Quick Install Via Agent
If you are already working with an AI coding agent, you can delegate the installation instead of doing the setup manually.
Use a prompt like this inside the target repository:
Install Agent Context Framework in this repository.
Steps:
1. Clone or copy ACF into this repo.
2. Run `npm install` in the ACF directory.
3. Run `npm run acf:setup`.
4. If this repository already contains code, choose `existing`.
5. After setup, run `npm run verify:context`.
6. Summarize what was created and what still needs manual review.
For a more explicit request:
Attach Agent Context Framework to this existing repository, use the `existing` setup mode, verify the generated context links, and then tell me which context files I should review first.
Shortest copy-paste version:
Install ACF here, choose `existing` if this repo already has code, run the setup, verify context links, and tell me what I should review next.
Non-Interactive Example
./tools/acf_setup.sh \
--mode new \
--project-name "New Project" \
--project-slug "new-project" \
--db-port 55735 \
--redis-port 56810 \
--with-filesystem
By default, the initializer:
- derives
project-slugfrom the parent repository folder name - builds
project-namefrom that slug - uses default ports
55735and56810
Typical Workflow
LLM Agent
|
v
context/next_context_sync.md
|
v
context/project_map.md
|
v
MCP semantic recall
|
v
verify with canonical context
|
v
work on codebase
|
v
update context + memory
In ACF, the recommended session flow is:
- The agent starts from
context/next_context_sync.md. - The agent reads
context/project_map.mdto orient on modules, entrypoints, and important files. - If the task matches a known repository workflow, the agent reads the relevant file in
context/procedures/. - The agent recalls relevant MCP Memory entries.
- The agent verifies MCP recall against canonical files in
context/*. - The agent works on the codebase.
- The work slice is closed with:
- a short code review
- an implementation commit
- updates to
context/* - one concise MCP write
Primary rule:
context/*wins over MCP.
Multi-Agent Use
ACF works well when multiple agents collaborate on the same project.
Typical examples:
- one agent works on backend changes
- another agent works on frontend changes
- another agent reviews or updates documentation
This works because:
context/*is shared canonical statecontext/next_context_sync.mdis the common startup point for every new sessioncontext/project_map.mdgives each session a lightweight repo map before deeper analysiscontext/procedures/captures repo-specific ways of carrying out recurring changes- MCP Memory is used for concise recall, not as the only source of truth
For multi-agent work to stay reliable:
- every closed work slice should update
context/* - every closed work slice should write one concise MCP record
- every new session should start from
context/next_context_sync.mdand then readcontext/project_map.md - when MCP and
context/*differ,context/*wins
In short:
- ACF supports multiple agents on one project
- the shared context files are what keep those agents aligned
MCP Setup
Use docs/mcp_ai_memory_setup.md for MCP registration and environment details.
Useful commands:
npm run acf:setup
npm run generate:project-map
npm run project-map:sync
npm run context:run-verification
npm run context:archive-history -- --keep-latest 100
npm run acf:status
npm run mcp:init
npm run verify:context
npm run verify:project-map
npm run mcp:register
npm run mcp:status
npm run mcp:smoke
Documentation Map
- NEW_PROJECT_CHECKLIST.md: human setup checklist
- docs/acf_scope_boundary.md: what belongs in core ACF vs future advanced modes
- docs/system_flow.md: architecture and memory flow
- docs/agent_workflow.md: day-to-day agent workflow
- docs/mcp_ai_memory_setup.md: MCP registration and runtime setup
- docs/mcp_memory_rules.md: source-of-truth and write/retrieval rules
Recommended Startup Prompt
Act as a senior engineer for project <name>.
Startup:
1. Read `context/next_context_sync.md`.
2. Read `context/project_map.md`.
3. Read a relevant file from `context/procedures/` if the task matches a known procedure.
4. Recall prior decisions from MCP `<server-name>` using project-specific keywords.
5. Verify recall against:
- `context/handoff_migration.md`
- `context/context_change_history.md`
Rules:
- `context/*` is the source of truth.
- If MCP and `context/*` differ, `context/*` wins.
- After each closed slice:
- short code review,
- commit,
- update `context/*`,
- 1 concise MCP record.
Contributing
Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.
Security
If you find a security issue, please follow SECURITY.md.
License
This project is available under the MIT License.
