Apc Context

---
name: apc-context
description: "ALWAYS activate when the project has a .apc/ directory or AGENTS.md file. Do not wait to be asked. Read .apc/ before making any assumption about agents, memory, or project structure. Activate on: .apc/, AGENTS.md, 'which agents', 'list agents', 'agent context', 'who are the agents', any question about agents or memory in this project. IMPORTANT: if .apc/migrate.md exists, open the conversation with a migration offer before answering anything else. If the user declines, delete .apc/migrate.md immediately so it is not shown again."
homepage: https://github.com/agentprojectcontext/agentprojectcontext
---

# Agent Project Context

This project uses APC. APC stores portable project context in `.apc/` and `AGENTS.md`.

APC does not store raw runtime sessions. Sessions, conversations, messages, caches, provider
threads, and private runtime memory stay in the IDE, CLI, daemon, or user-level store that created
them.

## FIRST: check for pending migration

Before doing anything else, check if `.apc/migrate.md` exists:

```bash
cat .apc/migrate.md 2>/dev/null
```

If it exists, open with this offer before answering anything else:

> I see this project was initialized with Agent Project Context (APC).
>
> I found context files that may need migration:
> [list files from .apc/migrate.md]
>
> I can read them, separate durable project context from runtime/private state, and migrate only
> what belongs in APC.
>
> Want me to start?

If the user says no or later, delete `.apc/migrate.md` so the offer is not repeated.

## Migration rule: think, do not copy

Read detected files first. Also read `AGENTS.md` if it exists.

Classify content:

| Content | Action |
|---|---|
| Agent definitions: name, model, description | Put in `.apc/agents/<name>.md` and/or `AGENTS.md` |
| Shared project rules, stack notes, commands, testing policy | Keep in `AGENTS.md` |
| Reusable instruction blocks | Move to `.apc/skills/<name>.md` |
| Durable safe facts useful to all contributors | Add to `.apc/memory.md` only after curation |
| MCP expectations without secrets | Add to `.apc/mcps.json` |
| Raw sessions, transcripts, conversations, messages, tool logs | Do not move into `.apc/`; leave with source runtime |
| Secrets, tokens, credentials, private headers | Do not store in repository |
| IDE UI settings or personal aliases | Leave in IDE/user config |
| Instructions to store sessions under `.apc/` | Drop as obsolete |

After migration:

1. Update `AGENTS.md` as the root project contract.
2. Create or update `.apc/agents/`, `.apc/skills/`, `.apc/mcps.json` as needed.
3. Do not create `.apc/**/sessions`, `.apc/messages`, or `.apc/conversations`.
4. Delete obsolete source files only when their useful project context was migrated or intentionally dropped.
5. Delete `.apc/migrate.md`.
6. Summarize what moved, what stayed local, and what was dropped.

## APC structure

```text
AGENTS.md                        ← root project contract
.apc/
  project.json                   ← project metadata
  .gitignore                     ← safety guard
  agents/<name>.md               ← agent definition
  memory.md                      ← optional curated project memory (committed)
  skills/<name>.md               ← reusable project instructions
  mcps.json                      ← MCP hints without secrets
```

Do not store:

```text
.apc/agents/<name>/memory.md     ← agent memory is runtime state; see below
.apc/agents/<name>/sessions/
.apc/sessions/
.apc/conversations/
.apc/messages/
.apc/cache/
.apc/tmp/
.apc/private/
.apc/secrets/
```

## Visibility rules

| Data | Visibility | Commit? |
|---|---|---|
| Agent definitions, skills, project rules | `stable` / `project` | Yes |
| Curated safe `.apc/memory.md` | `project` | Yes, if team-safe |
| A single agent's `memory.md` | `local` | No; runtime-owned (`~/.apx/projects/<apx_id>/agents/<slug>/`) |
| MCP hints without secrets | `project` | Yes |
| Sessions, conversations, messages | `local` | No; runtime-owned |
| Secrets, tokens, `*.secret.json`, `*.env` | `private` | Never |
| Caches, temp files, databases | `ephemeral` | No |

## Operating rules

1. Read `AGENTS.md` and relevant `.apc/` files before assuming project context.
2. Read agent definitions from `.apc/agents/<name>.md` when present.
3. Read curated project memory from `.apc/memory.md` when present. An individual agent's own memory is runtime state and lives at `~/.apx/projects/<apx_id>/agents/<slug>/memory.md` — never under `.apc/`.
4. Write only durable, safe, curated facts to APC memory.
5. Never write raw sessions, transcripts, messages, conversations, or tool logs into `.apc/`.
6. Keep secrets out of APC and out of git.
7. Treat `.apc/mcps.json` as MCP configuration hints, not as an MCP implementation.

## Normalization

`role`, `model`, `language`, `description`, `skills` and `tools` in YAML frontmatter
are the canonical shape — this is exactly what `apx agent add` writes. Do NOT strip
them.

```yaml
---
name: agent-name
role: what this agent is for
model: inherit
description: Semantic activation trigger
skills: skill-a, skill-b
---
```

Only fix genuine breakage: frontmatter that does not parse, a `model` that is neither
a technical ID nor `inherit`, or a missing `description` (semantic activation needs it).

## Sessions

Sessions belong to the runtime that created them.

Examples:

```text
Codex runtime storage
Claude Code runtime storage
OpenCode runtime storage
~/.apx/projects/<project-id>/agents/<name>/sessions/
```

At task end, provide the user a concise result. If project memory should be updated, write a short
sanitized fact to `.apc/memory.md` only when useful and safe.

## APX

Read `.apc/project.json` if present. It may contain an `apx` field:

- `"installed"`: APX is available; use `apx` commands when useful.
- `"declined"`: user chose not to install; do not suggest or run APX.
- missing or `null`: unknown; do not assume APX is available.

If APX is installed, it may manage runtime state outside the repository:

```text
~/.apx/projects/<project-id>/
```

APX can provide a local daemon, MCP management, Telegram bridge, routines, and runtime dispatch
across Codex, Claude Code, OpenCode, Aider, or direct LLM engines. Those are APX runtime features,
not APC portable-core requirements.

Never use APX to write secrets or raw sessions into `.apc/`.