Metadata-Version: 2.4
Name: apmf
Version: 0.2.0
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
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:

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

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

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