Project Context Compiler

Project Context Compiler, or PCC, is a local project memory system for long-running coding and research work. It keeps the full raw history in the project, extracts evidence-backed memories, and compiles a focused Task Context Packet for the next agent or human task.

PCC is not a generic chatbot memory layer. It is project-scoped: raw events, decisions, lessons, file summaries, retrieval traces, audit logs, and generated .agent/ Markdown files stay tied to one repository.

Install

Use an editable install from the repository root:

python -m pip install -e ".[dev]"

For local development without installation, run commands with:

PYTHONPATH=src python -m pcc --help

Initialize

Create the PCC store inside a project:

pmem init --project ./demo-repo --name demo
pmem doctor --project ./demo-repo

This creates .agent/, .agent/pcc.sqlite, .agent/pcc.config.yaml, index directories, runtime output directories, and human-readable memory files.

Import History

Import conversation JSONL:

pmem ingest-chat \
  --project ./demo-repo \
  --file ./logs/session.jsonl \
  --source-agent codex

Bind a Codex project alias and collect matching local Codex sessions automatically:

pmem bind-codex --project ./demo-repo --alias memoryOS
pmem collect-codex --alias memoryOS
pmem collect-codex --alias memoryOS --watch --interval 30

collect-codex scans ~/.codex/sessions for rollout files whose working directory or environment context points inside the bound project, converts them to PCC conversation JSONL, and imports them idempotently.

Import git history or a saved diff:

pmem ingest-git --project ./demo-repo --since HEAD~5
pmem ingest-git --project ./demo-repo --diff ./changes.diff

Add a manual note:

pmem note --project ./demo-repo --type decision --text "Use SQLite for the MVP raw event store."

Maintain human-facing work objects:

pmem update-project --project ./demo-repo --description "Local memory for a long-running research prototype."
pmem create-issue --project ./demo-repo --title "Separate human-facing issues from system memories"

Generate Context

Compile a task packet for the next work item:

pmem compile-context \
  --project ./demo-repo \
  --task "Continue the RBAC integration without repeating the prior testing pitfall"

The default output is:

.agent/runtime/task_context_packet.md

Generate a role-specific delegation brief for a sub-agent:

Agent delegation is currently frozen. The existing brief and handoff commands remain available for compatibility, but PCC is not expanding roles, targets, or execution orchestration unless this track is explicitly unfrozen.

pmem compile-agent-brief \
  --project ./demo-repo \
  --role reviewer \
  --level standard \
  --task "Review the RBAC integration before merge"

This writes a copyable brief under .agent/runtime/agent_briefs/ with the grounded context packet plus role-specific focus, boundaries, and expected output. Built-in roles include reviewer, frontend-designer, test-planner, and researcher. Reviewer briefs can use --level quick, --level standard, --level deep, or --level system; researcher is external-only and does not compile project memory context.

Prepare a target-specific handoff or launch command:

pmem invoke-agent \
  --project ./demo-repo \
  --target copilot \
  --role reviewer \
  --level system \
  --task "Review whether this delegation feature fits the product architecture"

Supported targets:

• copilot: invokes GitHub Copilot CLI with the generated brief.
• windsurf: opens a project and handoff file for Windsurf Cascade/Command use.

Add --execute to actually launch the target command. Without it, PCC writes the brief and invocation plan under .agent/runtime/ so the main agent can inspect or run it deliberately.

Search and inspect memory directly:

pmem search --project ./demo-repo --query "RBAC decision" --json
pmem list-memories --project ./demo-repo
pmem inspect-memory --project ./demo-repo --id mem_...

Generate a high-level project Dream:

pmem dream --project ./demo-repo --mode local
pmem dream --project ./demo-repo --mode live --instructions "Focus on design tensions and next bets"

pmem dream is a diagnostic report view. The core Dream behavior lives inside live extraction consolidation: chunk extraction can emit dream_signals, and the consolidation pass uses those signals to learn higher-order durable memories instead of only deduplicating candidates.

Run the local GUI:

pmem serve-gui --project ./demo-repo --host 127.0.0.1 --port 8765

MCP

PCC exposes a stdio MCP server:

pmem serve-mcp

It supports:

• get_project_context
• get_agent_brief
• invoke_agent
• recall_project_history
• search_project_memory
• ingest_conversation
• record_correction

Use tools/list to inspect the input and output schema for each tool. Stdio transport means one server process serves one MCP client connection; multiple agents can use the same project by launching separate pmem serve-mcp processes. Project storage uses SQLite WAL mode, busy timeout handling, and a project write lock for MCP tools that modify the database or .agent/ files. Tool calls are audited with status, error code, and count summaries; request arguments and message content are not copied into MCP audit payloads.

Runtime Adapter

The Python PCC core owns local memory, retrieval, evidence, and acceptance. Model runtime adapters live under packages/runtime-ts/ so PI and other agent bases do not leak into the storage core.

Current runtime bridge:

node packages/runtime-ts/bin/pcc-runtime.mjs complete < request.json

Supported provider directions:

• openai-compatible for HTTP chat/embedding APIs;
• pi-ai for PI/Codex OAuth completion via the TS/Node bridge;
• embeddings should stay on openai-compatible until PI embedding support is confirmed.

For PI live runs, set PCC_LIVE_LLM_PROVIDER=pi-ai and keep embeddings on PCC_LIVE_EMBEDDING_PROVIDER=openai-compatible.

.agent/ Files

Generated Markdown files include:

.agent/project.md
.agent/issues.md
.agent/current_state.md
.agent/architecture.md
.agent/conventions.md
.agent/lessons.md
.agent/open_questions.md
.agent/decisions/
.agent/research/
.agent/session_digests/

PCC writes generated sections inside <!-- PCC:AUTO_START --> and <!-- PCC:AUTO_END --> markers. Manual text outside the auto section is preserved. If the generated section is edited, sync-agent-files records a conflict instead of overwriting user content.

Security

PCC redacts common credentials during ingestion, marks sensitive raw events, and writes audit records for sensitive detection, correction, redaction, index repair, backups, file sync, and MCP tool calls.

Important defaults:

• project data is local to .agent/;
• cross-project search is disabled for the MVP;
• raw event deletion requires an explicit user command;
• .agent/pcc.sqlite, .agent/audit/, .agent/index/, .agent/runtime/, and .agent/*.secret.yaml should stay out of git.

Use these commands for operations and recovery:

pmem metrics --project ./demo-repo --json
pmem doctor --project ./demo-repo --repair-index
pmem backup --project ./demo-repo --output ./pcc-backup.zip
pmem redact-event --project ./demo-repo --event-id evt_... --reason "user requested removal"

Specs and Acceptance

The implementation is driven by the specs under docs/ and the executable acceptance assets under acceptance/ and tests/e2e/scenarios/.

Run the complete local product gate with:

python acceptance/checks/run_full_acceptance.py --include-real-project

Set PCC_LIVE_ENV to a local provider env file when live provider variables are not already exported. The runner redacts provider secrets before printing or writing reports.

Live memory extraction processes all ingested events in chunks. Tune PCC_LIVE_EXTRACTION_CHUNK_SIZE, PCC_LIVE_EXTRACTION_EVENT_CHAR_LIMIT, and PCC_LIVE_EXTRACTION_MAX_MEMORIES_PER_CHUNK when a real project has very long history or tight model-context limits.

Set PCC_LIVE_EXTRACTION_CONSOLIDATE=1 to run the Dream-aware consolidation path: each chunk may emit direct memories plus dream_signals, then memory_consolidation turns the accepted candidates and signals into higher-order project memories.

Core references:

• docs/00-index.md
• docs/12-cli-spec.md
• docs/14-security-privacy-spec.md
• docs/16-implementation-plan.md
• docs/acceptance/00-acceptance-overview.md

Third-Party Open Source

PCC uses a small direct dependency surface. Runtime and development dependency attribution is maintained in THIRD_PARTY_NOTICES.md.