Security

ProjectCtx separates local file access, hosted memory, and credentials. This page describes the boundaries enforced by the agent package.

Local File Access#

The agent reads local files only when projectctx scan or the scan_workspace MCP tool is invoked. Scanning is read-only and limited by explicit file, repository, depth, and ignore budgets.

The package does not install a background file watcher, continuous indexer, or sync daemon. Local repository contents are not uploaded automatically.

Conversation Harvest Boundary#

Local lifecycle hooks can automatically stage durable conversation outcomes. The shared runner copies only the capture snapshot needed for that invocation, stores private state under ~/.projectctx/harvest/, and deletes temporary snapshots after processing. Complete transcripts are never stored in ProjectCtx.

Transcript text is treated as untrusted data. The scribe receives only exact snapshot read access and ProjectCtx MCP tools; shell, editing, search, browser, agent, and unrelated MCP tools are denied. Secrets and transcript bodies are excluded from sanitized logs.

Promotion into durable records and relationships happens through a separate preview that requires explicit approval.

Reviewed Cloud Writes#

Code Memory uses a two-step write path:

1. preview_code_memory validates a proposed repository brief and returns a reviewable preview.
2. apply_code_memory applies that exact preview by previewId.

apply_code_memory cannot accept a replacement payload. If the proposal needs changes, create and review a new preview.

Generic record updates require the current version, and record or relationship changes append an event in the same database transaction.

Authentication#

Hosted MCP clients use OAuth with short-lived, workspace-bound access tokens. CLI Code Memory operations can use a separately issued scoped agent token:

projectctx login --token "<scoped-agent-token>"

For temporary automation:

export PROJECTCTX_TOKEN="<scoped-agent-token>"
export PROJECTCTX_API_URL="https://projectctx.com"

ProjectCtx stores only SHA-256 hashes of agent bearer tokens on the server. Locally, the CLI prefers the operating system credential store. The optional file fallback requires explicit consent and writes ~/.projectctx/config.json with mode 0600.

Clear local CLI credentials with:

projectctx logout

Never commit or share credentials. Do not place tokens in documentation, chat, screenshots, shell history, issue trackers, or debug logs. Revoke and replace a credential immediately if it is exposed.

MCP Trust Boundary#

ProjectCtx MCP tools are capability-scoped and workspace-bound. MCP never exposes:

• database or arbitrary SQL access;
• credential creation or administration;
• global user administration;
• workspace ownership transfer; or
• arbitrary local filesystem access.

REST and MCP call the same application service, so authorization and version conflict behavior remain consistent across both transports.

Source Metadata#

Prefer repository-relative paths in source metadata. Do not send absolute local paths to cloud memory unless the path itself is intentionally part of the record. Repository sources use a path:Lstart-Lend or heading-anchor locator and should include a concise excerpt for provenance.

Safe Diagnostics#

projectctx doctor reports credential presence and source without printing the credential value. Its output is designed to be shareable when requesting support. Review any debug output before posting it publicly.