Repository memory

ProjectCtx separates local repository inspection from durable cloud writes. Scanning is read-only; Code Memory writes require a reviewable preview.

Scan A Repository#

Run the scanner from a repository or workspace:

projectctx scan .

The scanner applies repository, file, depth, excerpt, and ignore budgets. It does not write ProjectCtx records and does not upload a background index.

Useful limits include:

projectctx scan . --max-repos 1
projectctx scan . --max-files 20 --max-depth 3
projectctx scan . --ignore node_modules --ignore dist
projectctx scan . --task-term authentication

The result is a structured, read-only overview that an AI client can use while preparing a concise repository brief.

Use The Local MCP Tools#

The optional local stdio server exposes:

Start the server only through an MCP client:

projectctx mcp

Do not keep a second copy running in a separate terminal.

Preview Durable Memory#

After reading the scan result and relevant source files, the AI client prepares a concise repository brief and calls preview_code_memory.

The preview validates:

• the target workspace and repository identity;
• proposed collections, records, and relationships;
• repository-relative source locators and excerpts;
• expected versions for updates; and
• duplicate or ambiguous records.

Nothing durable is written during preview.

Review And Apply#

Inspect the returned changes and warnings. If the proposal is correct, apply that exact previewId with apply_code_memory.

scan_workspace
  -> read selected source files
  -> prepare a concise repository brief
  -> preview_code_memory
  -> review proposed changes
  -> apply_code_memory

Apply cannot accept a replacement payload. If any content changes, create and review a new preview.

Authentication#

Hosted MCP clients normally authenticate through OAuth. CLI Code Memory operations can use a separately issued, workspace-scoped agent credential.

If your workspace administrator supplied one:

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

Never place a credential in repository files, documentation, screenshots, or debug output. See Security for storage and revocation guidance.