Skip to main content
Glama

PCTX compiles the durable knowledge of a project — facts, decisions, constraints, procedures, confirmed failures and handoffs — into a small, portable context file and task-scoped packs. Any assistant can pick up the work without re-reading the whole repository or replaying a chat transcript.

It is local-first, has zero runtime dependencies, and records why a claim is believed: state, origin, evidence, freshness and sensitivity.

PCTX dashboard

Why another context tool?

Most "memory" for coding agents is either a giant Markdown file that goes stale, or a chat log that cannot be audited. PCTX keeps a small, typed record store and compiles what is relevant:

  • Evidence, not vibes. Every record carries a state (verified, user_asserted, inferred, stale, superseded), origin and evidence. Volatile facts expire; replacements keep history.

  • Fits any assistant. Plain Markdown and JSON, a stdio MCP server, and adapters for AGENTS.md, CLAUDE.md, GEMINI.md, Copilot, Cursor and Windsurf.

  • Built for several agents at once. Goals and checklists with difficulty and risk, cooperative task/file reservations with TTL, checkpoints and handoffs.

  • Local and boring on purpose. No accounts, no network calls, no telemetry, no embeddings required, and secret-like content is refused before it is stored.

Related MCP server: Agent Harness Kit

Quick start

Requires Python 3.10+ and SQLite with FTS5 (standard in CPython builds).

# Install from this repository (pipx keeps it isolated)
pipx install git+https://github.com/tuangel134/pctx.git

# Inside the project you want to give memory to
cd ~/projects/my-app
pctx init
pctx scan
pctx export
pctx doctor

You now have:

Path

Purpose

PROJECT_CONTEXT.md

Portable, human/LLM-readable context export

architecture.md

Compact Mermaid map of components and imports

TASKS.md

Crash-recovery marker for the active task

.project-context/

Canonical JSON records and machine-local state

Ask for only what a task needs, within a token budget:

pctx context --task "add password reset without breaking the API" --budget 8000
pctx brief --budget 800 --role W4

Record something durable:

pctx decision \
  --id decision.storage \
  --statement "Sessions are stored in PostgreSQL" \
  --rationale "The existing migrations and tests already depend on it"

pctx record --type constraint --id constraint.no-secrets \
  --statement "Never store secrets or .env values in project memory" \
  --state user_asserted --export

How it works

project files ──► static scan ──► typed records ──► compiled context
                                      │                  │
                          decisions, evidence,      PROJECT_CONTEXT.md
                          TTL, replacements,        task packs, briefs
                          checklists, leases        MCP tools/resources
  1. Scan inspects manifests, Git state, structure and hashes. It never executes project code.

  2. Records are small JSON documents with stable IDs. Newer states replace older ones without deleting history; --ttl expires volatile claims.

  3. Compile produces a portable export, a role brief, or a task-scoped pack that fits a token budget.

  4. Verify can run an explicitly recorded check command and store the observed outcome — never automatically, and only on request.

Task context and worker brief

Record states

State

Meaning

verified

Backed by current evidence (file hash, Git revision, check result)

user_asserted

Declared by a person or an explicit decision

inferred

Written by an AI or imported from a worker report; needs review

stale

Evidence changed or expired; must be reviewed before trusting it

superseded

Replaced by a newer record; kept for history

unknown

Not enough information

MCP setup

PCTX speaks MCP over stdio. Generate a client configuration:

pctx --root /path/to/project integrate --client vscode --write
pctx --root /path/to/project integrate --client cursor --write
pctx --root /path/to/project integrate --client claude-code --write

Or add it manually:

{
  "mcpServers": {
    "pctx": {
      "command": "pctx",
      "args": ["--root", "/path/to/project", "mcp", "serve", "--allow-write"]
    }
  }
}
  • Default mcp serve is read-only. Add --allow-write so the agent can record decisions, checkpoints and handoffs; add --watch to refresh derived memory while the client keeps the server open.

  • The server exposes context, search, plan, coordination and history tools plus context/architecture/task resources.

  • Client behavior is not guaranteed: pctx diagnose checks the protocol handshake, not whether a model chooses to use it.

Working with multiple agents

PCTX does not call or hire models. It gives cooperating sessions a shared, auditable protocol:

# Create a goal and tasks with explicit difficulty and risk
pctx plan create --id plan.login --kind goal --title "Ship login" \
  --difficulty intermediate --difficulty-reason "Touches API, UI and sessions" --risk high
pctx plan create --id plan.login-api --parent plan.login --kind task \
  --title "Implement login endpoint" --difficulty medium \
  --difficulty-reason "One route plus tests" --risk medium

# Reserve the task and the exact paths before editing
pctx coordinate claim --session-id ia-login-01 --task-id plan.login-api \
  --path src/auth --path tests/auth --ttl 900

pctx coordinate list --status active --budget 1500
pctx coordinate renew --id <lease-id> --ttl 900
pctx coordinate release --id <lease-id> --summary "Endpoint done; tests pending"

Reservations are cooperative leases, not OS file locks: editors stay usable, but every session must respect the protocol. Expired leases stop occupying the area; a late worker cannot silently overwrite its successor.

Goals and checklists

Retrieval

Search is local SQLite FTS5 over records and documents, with budgets and expandable evidence:

pctx lookup "authentication flow" --budget 2000
pctx expand <record-or-fragment-id> --budget 1200
pctx neighbors <record-id> --budget 1000

Semantic search is optional and fully local: PCTX never downloads models or calls an API. Install the extra and point it at an ONNX embedding bundle:

pipx inject pctx numpy onnxruntime tokenizers   # or: pip install -e ".[semantic]"
pctx index --model /path/to/onnx-bundle
pctx lookup "how does login work?" --mode hybrid --model /path/to/onnx-bundle

JSON records remain the source of truth; indexes are disposable and queries are never persisted.

Installation

# Isolated install from Git
pipx install git+https://github.com/tuangel134/pctx.git

# Or as a library/editable checkout
git clone https://github.com/tuangel134/pctx.git
cd pctx
python3 -m pip install -e ".[dev]"

Linux desktop entry (application menu + ~/.local/bin/pctx):

python3 install.py

Other platforms work through pip/pipx, but are not continuously validated yet. The dashboard is a local web UI opened by pctx gui (currently in Spanish).

CLI at a glance

Command

What it does

pctx init / scan

Create memory and refresh verified facts

pctx export

Compile PROJECT_CONTEXT.md

pctx context --task

Build a task-scoped context pack

pctx brief

Short objective/next step/constraints/blockers brief

pctx record / decision

Add durable knowledge

pctx handoff

Save, verify or resume a session handoff

pctx task

Start, checkpoint or finish resumable work

pctx plan

Goals, checklists, difficulty, risk and reviews

pctx coordinate

Cooperative leases for tasks and paths

pctx verify

Preview or explicitly run a recorded check

pctx lookup / expand / neighbors

Budgeted retrieval over records

pctx mcp serve

MCP server over stdio

pctx integrate

Write MCP config for a client

pctx adapters sync

Update AGENTS.md, CLAUDE.md, etc.

pctx doctor

Health, drift and security checks

pctx gui

Local dashboard on 127.0.0.1

pctx backup / history

Private backups and record revisions

Full command help: pctx <command> --help.

Security and privacy

  • Everything runs locally. The dashboard binds to 127.0.0.1 and requires a per-session token; there is no cloud component.

  • Transcripts, internal reasoning and routine tool output are not stored. .project-context/.private/ and .cache/ are excluded from version control.

  • Secret-like content (private keys, provider tokens, password assignments) is rejected before it can be written to a canonical record.

  • Signed/verified source is not executed by scan; stored check commands run only on an explicit pctx verify --run or request.

  • Repository content is treated as data, not as instructions with authority.

Status and limits

PCTX is 0.7.1 (beta). It is honest about what it cannot do:

  • The scanner is static and best-effort; it does not infer full program semantics or guarantee complete coverage.

  • Leases coordinate cooperative agents; they do not block editors at the OS level.

  • verified means evidence was current and a recorded review covered the criteria — not that an independent audit happened.

  • The GUI is Spanish-only today; the CLI, generated context and MCP tools are in English.

  • Python 3.10+ on Linux is the tested path. Windows and macOS need validation.

Documentation

Contributing

Bug reports, reproducible examples and focused pull requests are welcome. See CONTRIBUTING.md. Run the suite before sending changes:

python3 -m pip install -e ".[dev]"
python3 -m pytest -q

License

MIT — see LICENSE. PCTX is not affiliated with Anthropic, OpenAI, Google or any editor vendor.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding providers to run structured multi-agent workflows with tracked tasks, specifications, handoffs, and health-gated completion. It exposes MCP tools for task claiming, action logging, repairs, document validation, and lifecycle evidence.
      29 npm
      MIT