AI Project Memory Framework

Structured project memory and context management for AI coding agents.

APMF helps an AI agent understand the current state of a long-lived project without scanning the entire repository or replaying the full conversation history.

Project repository: github.com/MellojFront/APMF

Why APMF

• Keeps project identity, constraints, decisions, and tasks in a human-readable format.
• Compiles a small MEMORY.md snapshot for fast session startup.
• Exports focused context for one task instead of loading the whole project.
• Works with any coding agent that can read files.
• Keeps memory independent from a specific LLM or editor.
• Encourages Git versioning so project state can be reviewed and rolled back.

Install

Choose one of the following interfaces:

# Zero-install Node.js interface
npx @melloj/apmf init

# Global Node.js CLI
npm install --global @melloj/apmf

# Python CLI
python -m pip install apmf

Both packages provide the apmf and ai-memory commands. The npm package is scoped as @melloj/apmf because npm blocks the unscoped apmf name as too similar to existing packages.

Quick start

Interactive TUI Setup Wizard (Recommended)

Run the interactive setup wizard (similar to BMAD framework setup) to step through environment checks, project metadata, AI assistant selection (Antigravity, Cursor, Claude Code, Copilot), and automatic rule generation:

apmf wizard
# or
apmf init --interactive
# or zero-install
npx @melloj/apmf wizard

Direct initialization

apmf init
# (ai-memory init and ampf init also work as aliases)

APMF creates an isolated .ai-memory/ directory containing the framework state, documentation, schemas, scripts, and task storage. It also generates lightweight bootstrap files for AI agents:

• MEMORY.md — the current project snapshot;
• AGENTS.md — startup and collaboration instructions;
• .ai-memory/ — the full, structured memory store.

If the project is not a Git repository, APMF warns you and offers to run git init. Use --init-git for non-interactive initialization:

apmf init --init-git

Agent Setup & Integration

To generate or update rules and skills for specific AI assistants anytime:

# Generate rules for all supported agents (Antigravity, Cursor, Claude Code, Copilot, Codex)
apmf setup-agent all

# Generate rules for a specific agent
apmf setup-agent codex
apmf setup-agent cursor
apmf setup-agent antigravity
apmf setup-agent claude

Everyday commands

Both apmf and ai-memory (plus the common typo alias ampf) are registered executable commands. apmf is recommended:

# Refresh the project snapshot
apmf compile

# Validate memory units and graph relationships
apmf validate

# Run framework health check and self-diagnostics
apmf doctor

# Show context analytics, token consumption, and budget advice
apmf stats

# Run historical benchmark report (speed, health score 100/100, compression ratio)
apmf benchmark

# Generate printable PDF & HTML executive audit report
apmf report --open

# Generate interactive HTML visualization of memory graph
apmf visualize --open

# Install Git pre-commit hook (auto-validate & compile MEMORY.md on commit)
apmf install-hooks

# Launch Model Context Protocol (MCP) stdio server for LLM integration
apmf mcp

# Archive completed tasks to maintain clean context
apmf archive

# Create a structured task
apmf new-task "Add authentication"

# Export context for one task
apmf task task-001

The focused task export is useful when an AI agent needs the project boundaries and constraints for one piece of work, without receiving unrelated history.

Advanced Features & LLM Integration (v0.3.0)

⚓️ Git Pre-Commit Hooks (install-hooks)

Automatically run memory validation (ai-memory validate) and snapshot compilation (ai-memory compile) before every commit. If MEMORY.md changes during compile, it is staged automatically.

apmf install-hooks
apmf install-hooks --uninstall

🔌 Model Context Protocol Server (mcp)

APMF acts as a standard MCP Server (JSON-RPC 2.0) over stdio. Connect Claude Desktop, Cursor, or Antigravity directly to APMF tools & resources (apmf://snapshot, apmf://tasks).

apmf mcp

📊 Context Analytics & Token Budgeting (stats)

Analyze token consumption across memory units, active/completed tasks, and AI rule files. Receive recommendations to optimize memory context window.

apmf stats
apmf stats --json

🕸️ Interactive HTML Graph Visualizer (visualize)

Generate a rich, interactive HTML visualizer for exploring project entities, decisions, constraints, and task dependencies.

apmf visualize --open

📚 How to Read a Project & Update Memory (Comprehension Protocol)

APMF provides a structured workflow for both AI agents and developers to quickly understand a project and keep its state in sync:

1. Rapid Orientation (Zero-Waste Startup)

Instead of reading all files in a large repository:

1. Read MEMORY.md immediately to load Identity, Active Constraints, and Task Backlog.
2. Run apmf stats to inspect memory size, active tasks, and context window budget.
3. Run apmf visualize --open to visually inspect entity relationships, decisions, and dependencies in an interactive HTML graph.

2. Deep-Dive into Specific Work

When assigned a specific task or feature:

• Run apmf task task-XXX to export a minimal, targeted context package containing only relevant constraints and memory units for that task.

3. Updating & Syncing Project Memory

When discovering new technical decisions, modifying architecture, or completing tasks:

1. Record Knowledge: Create or update unit files in .ai-memory/units/*.json for new entities, decisions, or constraints.
2. Update Task Status: Mark finished tasks as status: completed in .ai-memory/tasks/.
3. Compile Snapshot: Run apmf compile to refresh MEMORY.md.
4. Validate Integrity: Run apmf validate to verify graph integrity and relationship links.

Project layout after initialization

your-project/
├── .ai-memory/
│   ├── docs/
│   ├── schema/
│   ├── scripts/
│   ├── tasks/
│   ├── units/
│   ├── AGENTS.md
│   └── MEMORY.md
├── AGENTS.md
└── MEMORY.md

The generated .ai-memory/ directory belongs to the project that you initialize. It may contain private project context and should be reviewed before sharing or publishing that project.

Design principles

1. Targeted context — load only the context required for the current task.
2. State over transcript — preserve the project state, not every conversational turn.
3. LLM independence — keep memory in portable files rather than provider-specific storage.
4. Human readability — make every important memory unit inspectable and recoverable.
5. Git hygiene — use version control for history, review, and rollback.

Development

Run the local test suite and inspect the distributable artifacts:

npm test
npm pack --dry-run
python -m pip install --upgrade build twine
python -m build

Publishing is intentionally a separate, explicit action:

npm publish
python -m twine upload dist/*

Review the generated files and confirm the release before running either publish command.

Automated releases

Public releases use GitHub Actions OIDC Trusted Publishing. No npm or PyPI write token is stored in the repository or GitHub Actions secrets.

Before the first release, configure both registries to trust:

• GitHub repository: MellojFront/APMF;
• workflow file: .github/workflows/release.yml;
• GitHub environment: release;
• npm package name: @melloj/apmf;
• PyPI package name: apmf.

Then publish a GitHub Release from a version tag such as v0.1.0. The workflow verifies the tag, builds the Python distributions, and publishes to npm and PyPI using short-lived OIDC credentials.

See the official setup guides for npm Trusted Publishing and PyPI Trusted Publishers.

Privacy and public releases

APMF can store project-specific decisions, tasks, paths, and other context in .ai-memory/. Do not publish an initialized project directory without reviewing that data.

The framework packages contain only the reusable implementation, tests, and public documentation. They do not include a user's .ai-memory/ directory, task history, or generated MEMORY.md.

License

MIT