apmf 0.2.0

AI Project Memory Framework (APMF) — Universal AI Project Memory & Context Framework

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

ai-memory init

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:

ai-memory 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

# Refresh the project snapshot
ai-memory compile


# Validate memory units and graph relationships
ai-memory validate

# Create a structured task
ai-memory new-task "Add authentication"

# Export context for one task
ai-memory 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.

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