Metadata-Version: 2.4
Name: apmf
Version: 0.3.1
Summary: AI Project Memory Framework (APMF) — Universal AI Project Memory & Context Framework
Home-page: https://github.com/MellojFront/APMF
Author: AI Architect
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-python
Dynamic: summary

# 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](https://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:

```bash
# 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:

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

### Direct initialization

```bash
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:

```bash
apmf init --init-git
```

### Agent Setup & Integration

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

```bash
# 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:

```bash
# 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.
```bash
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`).
```bash
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.
```bash
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.
```bash
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

```text
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:

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

Publishing is intentionally a separate, explicit action:

```bash
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](https://docs.npmjs.com/trusted-publishers/) and [PyPI Trusted Publishers](https://docs.pypi.org/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
