pi-memctx

Local-first memory context for Pi coding agents.

Quickstart • Why • Benchmark • How it works • Packs • Commands • Development

Stop paying your coding agent to rediscover what your project already knows.

pi-memctx gives Pi a local, durable, Markdown-native memory layer. It searches your project memory before each prompt, injects only the context that matters, and lets the agent work normally when memory is not enough.

No database server. No hosted memory vendor. No new workflow for your users. Just launch Pi and ask the question.

Quickstart

1. Install

pi install npm:pi-memctx

Or install from GitHub:

pi install git:github.com/weauratech/pi-memctx

You can also verify the local installation:

npx pi-memctx doctor

2. Start Pi with the extension

cd /path/to/your/workspace
pi -e pi-memctx

3. Generate your first memory pack

Inside Pi:

/memctx-pack-generate

pi-memctx scans the workspace and creates a structured Markdown memory pack with context, decisions, runbooks, and indexes.

4. Ask normally

How do I deploy this service to production?

The user experience stays the same: prompt, wait, get the answer. The Memory Gateway works behind the scenes.

Why it feels like magic

A normal coding agent starts every session cold:

User: How do I deploy the gateway service to production?
Agent: I'll inspect the repo...
       [tool] list files
       [tool] read workflows
       [tool] inspect Helm charts
       [tool] search docs
       ...

pi-memctx turns that into:

User: How do I deploy the gateway service to production?
Agent: Merge to main, GitHub Actions builds Docker and pushes to ECR,
       Helm values are updated, ArgoCD syncs to Kubernetes, staging is
       automatic, and production is manual via ArgoCD approval/sync.

The difference is not a better prompt. It is memory arriving before the model starts reasoning.

Benchmark

Latest local benchmark from the synthetic NovaPay fixture, 5 tasks, 1 repeat:

QMD_PATH=/tmp/pi-memctx-qmd/node_modules/.bin/qmd \
BENCH_REPEATS=1 \
BENCH_PROFILES="baseline gateway" \
BENCH_TIMEOUT=120 \
bash benchmark/run.sh /tmp/pi-memctx-benchmark-gateway-final

Compared with baseline:

Benchmarks are intentionally local and reproducible. Run them on your own projects:

bash benchmark/setup.sh /tmp/pi-memctx-benchmark
QMD_PATH=$(pwd)/node_modules/.bin/qmd \
BENCH_PROFILES="baseline gateway" \
bash benchmark/run.sh /tmp/pi-memctx-benchmark

How it works

pi-memctx is a Memory Gateway between the user and the main LLM.

User prompt
   │
   ▼
Memory Gateway
   ├─ detects the active pack
   ├─ retrieves relevant Markdown memories with qmd or grep fallback
   ├─ ranks candidates with cheap semantic coverage
   ├─ builds a compact local memory summary
   └─ injects only useful context
   │
   ▼
Pi agent answers normally
   ├─ uses memory when sufficient
   ├─ inspects the repo when memory is partial or stale
   └─ can save durable discoveries back to Markdown

The gateway does not replace the main LLM. It does the boring part first: finding the right project memory, compressing it, and preventing redundant tool exploration when the answer is already known.

Profile

pi-memctx now has one recommended runtime profile: gateway.

Inspect or re-apply the profile inside Pi:

/memctx-profile status
/memctx-profile gateway

Old profile names such as gateway-lite, gateway-full, qmd-economy, low, balanced, auto, and full are compatibility-mapped to gateway.

Memory packs

A pack is a directory of Markdown files with frontmatter. You can edit it with any editor, commit it, review it, or open it in Obsidian.

packs/my-project/
  00-system/
    pi-agent/
      memory-manifest.md
      resource-map.md
    indexes/
      context-index.md
      decision-index.md
      runbook-index.md
  20-context/
    api.md
    web.md
    infra.md
  50-decisions/
    001-hexagonal-architecture.md
    002-use-pgx.md
  70-runbooks/
    deploy.md
    terraform.md

Recommended note types:

Commands

Deprecated aliases such as /pack and /pack-generate are still registered for compatibility.

Tools

memctx_search

Search the active memory pack:

Use memctx_search to find the deploy runbook.

Parameters:

When the Memory Gateway already injected sufficient memory, the agent is instructed not to call memctx_search again. That keeps answers fast and prevents duplicate context retrieval.

memctx_save

Save durable knowledge into the active pack:

Remember that production deploys require ArgoCD manual approval.

The tool supports:

• observation
• decision
• action
• runbook
• context

Secret-looking content is blocked.

qmd integration

pi-memctx uses @tobilu/qmd when available for fast memory retrieval. To keep pi install npm:pi-memctx clean and warning-free, qmd is not installed automatically. If qmd is not available, pi-memctx falls back to grep-based search.

Resolution order:

1. QMD_PATH or MEMCTX_QMD_BIN
2. an already-installed local .bin or bundled/vendor path
3. qmd on PATH
4. grep fallback

Optional qmd install example:

npm install -g @tobilu/qmd

Check your setup:

npx pi-memctx doctor

Safety model

pi-memctx is local-first and intentionally boring about sensitive data.

It will not save:

• API keys
• tokens
• passwords
• private keys
• customer data
• payment card data
• sensitive payloads

Memory is Markdown on disk. You can inspect every byte.

Configuration

Most users should start with the defaults. Advanced users can configure behavior with environment variables or /memctx-profile.

Common environment variables:

Development

Requirements:

• Node.js 20+
• Bun for tests
• Pi coding agent

Install dependencies:

npm install

Run checks:

npm run typecheck
npm test
npm run test:e2e

Run all CI checks:

npm run ci

Run benchmark:

bash benchmark/setup.sh /tmp/pi-memctx-benchmark
QMD_PATH=/tmp/pi-memctx-qmd/node_modules/.bin/qmd \
BENCH_REPEATS=1 \
BENCH_PROFILES="baseline gateway" \
BENCH_TIMEOUT=120 \
bash benchmark/run.sh /tmp/pi-memctx-benchmark

Contributing

Issues and pull requests are welcome.

Good contributions include:

• better language-agnostic retrieval heuristics
• safer memory extraction
• clearer benchmark fixtures
• docs and examples
• profile tuning with reproducible numbers

Please do not commit private company memory packs, customer data, secrets, or benchmark fixtures derived from private repositories.

License

MIT