![\"Card](\"https://em-content.zobj.net/source/apple/391/card-file-box_1f5c3-fe0f.png\")
\n\n \n
\n Stop making Pi rediscover your repo every session.\n
\n\n\n ![\"Stars\"](\"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2Fweauratech%2Fpi-memctx&query=%24.stargazers_count&label=stars&color=yellow&style=flat&logo=github\"){kind=icon}
![\"npm](\"https://img.shields.io/npm/dt/pi-memctx?style=flat&logo=npm&label=total%20downloads\")
![\"Last](\"https://img.shields.io/github/last-commit/weauratech/pi-memctx?style=flat\")
![\"License\"](\"https://img.shields.io/github/license/weauratech/pi-memctx?style=flat\")
![\"Latest](\"https://img.shields.io/badge/release-v0.13.1-blue?style=flat\"){kind=icon}
\n Quickstart •\n Why •\n Learning •\n Benchmark •\n How it works •\n Workspace memory •\n Commands •\n Development\n
\n\n---\n\n> **Stop making your coding agent rediscover your repo.**\n\n`pi-memctx` gives [Pi](https://github.com/mariozechner/pi-coding-agent) a local, durable, Markdown-native memory layer. It searches project memory before each prompt, injects only compact/relevant context, lets Pi inspect the repo normally when memory is not enough, and learns durable discoveries after turns.\n\nNo database server. No hosted memory vendor. No hidden black box. Just Markdown memory packs you can read, edit, grep, version, and sync.\n\n## Quickstart\n\n### 1. Install\n\n```bash\npi install npm:pi-memctx\n```\n\nAlready installed? Update with:\n\n```bash\npi update npm:pi-memctx\n```\n\nOr install from GitHub:\n\n```bash\npi install git:github.com/weauratech/pi-memctx\n```\n\nYou can also verify the local installation:\n\n```bash\nnpx pi-memctx doctor\n```\n\n### 2. Start Pi with the extension\n\n```bash\ncd /path/to/your/workspace\npi -e pi-memctx\n```\n\n### 3. Generate your first memory pack\n\nInside Pi:\n\n```txt\n/memctx-init\n```\n\n`pi-memctx` scans the workspace and creates local Markdown workspace memory with context, decisions, runbooks, and indexes. Internally this is stored as a pack, but most users do not need to manage packs directly.\n\n### 4. Ask normally\n\n```txt\nHow do I deploy this service to production?\n```\n\nThe user experience stays the same: prompt, wait, get the answer. The Memory Gateway works behind the scenes.\n\n## Why it feels like magic\n\nA normal coding agent starts every session cold:\n\n```txt\nUser: How do I deploy the gateway service to production?\nAgent: I'll inspect the repo...\n [tool] list files\n [tool] read workflows\n [tool] inspect Helm charts\n [tool] search docs\n ...\n```\n\n`pi-memctx` turns that into:\n\n```txt\nUser: How do I deploy the gateway service to production?\nAgent: Merge to main, GitHub Actions builds Docker and pushes to ECR,\n Helm values are updated, ArgoCD syncs to Kubernetes, staging is\n automatic, and production is manual via ArgoCD approval/sync.\n```\n\nThe difference is not a better prompt. It is **memory arriving before the model starts reasoning**.\n\n## Automatic learning\n\nAfter a rich planning, debugging, or repository-discovery turn, `pi-memctx` can persist multiple linked Markdown notes instead of one shallow summary:\n\n```txt\nmemctx: learned 5 memories:\n - context: [[packs/my-pack/20-context/payment-api|Payment API]] (updated)\n - observation: [[packs/my-pack/60-observations/deploy-patterns|Deploy patterns]] (created)\n - runbook: [[packs/my-pack/70-runbooks/deploy-payment-api|Deploy Payment API]] (created)\n - action: [[packs/my-pack/40-actions/2026-05-02-prepared-rollout|Prepared rollout]] (created)\n - session: [[packs/my-pack/80-sessions/rich-persistence-payment-api|Rich planning snapshot]] (created)\n```\n\nLearned notes are cross-linked with `[[wikilinks]]`, so future searches can recover the whole discovery: context, observations, runbooks, actions, decisions, and rich session snapshots.\n\n## Local and inspectable by design\n\n- Memories are Markdown files on your machine.\n- No hosted memory service or external vector database is required.\n- You can inspect, edit, delete, commit, or sync packs yourself.\n- Secret-looking values are blocked/redacted before persistence.\n- When memory is insufficient or stale, Pi falls back to normal repo inspection.\n\n## Benchmark\n\n### Real-world stress benchmark\n\nA local stress benchmark was run against five anonymized real workspace-memory packs (`Pack 1` … `Pack 5`), with 5 repeats per task and two profiles: plain Pi with **no extensions** (`baseline`) and Pi with `pi-memctx` (`gateway`). The benchmark is read-only: no commits, deploys, applies, publishes, or cloud mutations.\n\n| Profile | Runs | Avg latency | Provider tokens/task | Visible tokens/task | Tool calls/task | Quality | Timeouts |\n|---|---:|---:|---:|---:|---:|---:|---:|\n| baseline | 25 | 196.6s | 34,385 | 2,503 | 27.2 | 206/255 | 1 |\n| gateway | 25 | 65.0s | 6,614 | 1,776 | 1.36 | 231/255 | 0 |\n\nCompared with baseline:\n\n| Metric | Gateway vs baseline |\n|---|---:|\n| Latency | **66.9% faster** |\n| Provider tokens | **80.8% fewer** |\n| Tool calls | **95.0% fewer** |\n| Quality | **+25 facts** |\n| Timeouts | **1 → 0** |\n\nPer-pack quality in the same anonymized run:\n\n| Case | Baseline | Gateway |\n|---|---:|---:|\n| Pack 1 — deployment/GitOps runbook recall | 56/60 | **60/60** |\n| Pack 2 — Lambda/release workflow recall | **48/50** | 45/50 |\n| Pack 3 — package publishing configuration | **44/45** | 38/45 |\n| Pack 4 — long frontend-workflow continuation | 30/50 | **38/50** |\n| Pack 5 — observability troubleshooting runbook | 28/50 | **50/50** |\n\nThe biggest change is not just quality; it is avoiding expensive rediscovery. The gateway keeps average tool use near one call per prompt while still allowing bounded fallback when memory is partial.\n\n### Reproducible synthetic benchmark\n\nThe repository also includes a synthetic benchmark fixture you can run locally:\n\n```bash\nbash benchmark/setup.sh /tmp/pi-memctx-benchmark\nBENCH_REPEATS=2 \\\nBENCH_PROFILES=\"baseline gateway\" \\\nbash benchmark/run.sh /tmp/pi-memctx-benchmark\n```\n\nRecent synthetic release-check run (`BENCH_REPEATS=5`, 25 tasks/profile, public fixture only):\n\n| Profile | Runs | Avg latency | Provider tokens/task | Visible tokens/task | Tool calls/task | Failed tools/task | Quality |\n|---|---:|---:|---:|---:|---:|---:|---:|\n| baseline | 25 | 22.0s | 2,450 | 571 | 6.2 | 0.4 | 63/110 |\n| gateway | 25 | 10.5s | 2,615 | 329 | 0.3 | 0.0 | 76/110 |\n\nGateway result on the public fixture:\n\n- **52.2% faster** average latency.\n- **95.2% fewer tool calls**.\n- **42.4% fewer visible tokens** in assistant-facing prompt/output text.\n- **+13 scored facts** across the same prompts.\n- Provider token totals may move differently from visible tokens because model/provider cache accounting is included.\n\nBenchmarks are intentionally local and reproducible. Results depend on the model/provider, machine, cache behavior, and contents of your memory packs.\n\n## How it works\n\n`pi-memctx` is a Memory Gateway between the user and the main LLM.\n\n```txt\nUser prompt\n │\n ▼\nMemory Gateway\n ├─ detects the active pack, including workspace maps and prompt mentions\n ├─ supports Markdown packs that are real directories or symlinked directories\n ├─ retrieves relevant Markdown memories with qmd or grep fallback\n ├─ scopes qmd collections by pack path to avoid cross-vault index reuse\n ├─ ranks candidates with cheap semantic coverage\n ├─ builds a compact local memory summary\n └─ injects only useful context\n │\n ▼\nPi agent answers normally\n ├─ uses memory when sufficient\n ├─ inspects the repo when memory is partial or stale\n └─ after the turn, pi-memctx learns durable context back to Markdown\n ├─ context\n ├─ observations\n ├─ runbooks\n ├─ decisions\n ├─ actions\n └─ rich session snapshots\n```\n\nThe 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.\n\nWhen multiple packs are available, explicit pack names in the prompt take priority over weaker aliases from other packs. This keeps multi-workspace setups predictable without hardcoded company, domain, language, or technology rules.\n\n## Profile\n\n`pi-memctx` now has one recommended runtime profile: `gateway`.\n\n| Profile | Best for | Behavior |\n|---|---|---|\n| `gateway` | Fast daily use | Conservative local judge, compact context, qmd/grep retrieval, zero redundant memory searches when memory is sufficient. |\n\nThe profile is applied by default. Use `/memctx-status --advanced` if you need to inspect the active runtime settings. Old profile names such as `gateway-lite`, `gateway-full`, `qmd-economy`, `low`, `balanced`, `auto`, and `full` are compatibility-mapped to `gateway` in configuration files.\n\n## Workspace memory\n\nEach workspace gets local Markdown memory. Internally, workspace memory is stored as a pack directory with frontmatter. You can edit it with any editor, commit it, review it, or open it in Obsidian.\n\n```txt\npacks/my-project/\n 00-system/\n pi-agent/\n memory-manifest.md\n resource-map.md\n indexes/\n context-index.md\n decision-index.md\n runbook-index.md\n 20-context/\n api.md\n web.md\n infra.md\n 40-actions/\n 2026-05-02-prepared-rollout.md\n 50-decisions/\n 001-hexagonal-architecture.md\n 002-use-pgx.md\n 60-observations/\n deploy-patterns.md\n 70-runbooks/\n deploy.md\n terraform.md\n 80-sessions/\n rich-persistence-payment-api.md\n```\n\nRecommended note types:\n\n| Type | Directory | Use it for |\n|---|---|---|\n| `context` | `20-context/` | Stack, services, repositories, conventions, environments. |\n| `decision` | `50-decisions/` | Architecture and technical decisions with rationale. |\n| `observation` | `60-observations/` | Durable facts, requirements, caveats, structural discoveries. |\n| `runbook` | `70-runbooks/` | Repeatable operational procedures. |\n| `action` | `40-actions/` | Completed work, migrations, deploys, incident notes. |\n| `session` | `80-sessions/` | Sanitized rich planning/discovery snapshots for future retrieval. |\n\n## Commands\n\nMost users only need the daily commands:\n\n| Command | Purpose |\n|---|---|\n| `/memctx` | Show compact help and current memory status. |\n| `/memctx-init` | Create/update memory for this workspace. If a model is selected, deep LLM enrichment starts in the background by default; use `--no-deep` to skip it. |\n| `/memctx-status` | Show workspace memory status; add `--advanced` for internal paths/config. |\n| `/memctx-review` | Review queued memory candidates; approve, reject, clear, or inspect the queue path. |\n| `/memctx-refresh` | Refresh workspace memory inventory/enrichment in the background. |\n| `/memctx-doctor` | Diagnose qmd, workspace memory, and configuration. |\n\nOlder pack/config commands were removed from the public command surface to keep the extension simple. Advanced behavior is still configurable through environment variables and the local config file.\n\n### Reviewing queued memory candidates\n\nWhen automatic learning is unsure whether a candidate should be persisted, pi-memctx queues it for review instead of silently saving it. Review the active workspace queue with:\n\n```txt\n/memctx-review\n```\n\nUseful forms:\n\n```txt\n/memctx-review --list\n/memctx-review approve 1\n/memctx-review reject 1\n/memctx-review clear\n/memctx-review path\n```\n\nBy default, review commands operate only on the active workspace memory pack. Advanced users can inspect the raw queue at `~/.cache/pi-memctx/save-queue.json`.\n\n## Tools\n\n### `memctx_search`\n\nSearch the active memory pack:\n\n```txt\nUse memctx_search to find the deploy runbook.\n```\n\nParameters:\n\n| Parameter | Values | Default |\n|---|---|---|\n| `query` | string | required |\n| `mode` | `keyword`, `semantic`, `deep` | `keyword` |\n| `limit` | number | `5` |\n\nWhen 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.\n\n## Gateway diagnostics\n\nFor memory-quality investigations, enable opt-in debug snapshots:\n\n```bash\nMEMCTX_GATEWAY_DEBUG=1 pi -e pi-memctx\n```\n\nSnapshots are written under:\n\n```txt\n$TMPDIR/pi-memctx-gateway-debug/\n```\n\nThey include sanitized/truncated prompt terms, active pack, candidate paths, selected facts, coverage, fallback budget, and top scored candidate lines. Debug is off by default, best-effort only, and intended for local diagnosis; do not commit debug snapshots because they may contain project-specific paths or note titles.\n\n### `memctx_save`\n\nSave durable knowledge into the active pack:\n\n```txt\nRemember that production deploys require ArgoCD manual approval.\n```\n\nThe tool supports:\n\n- `observation`\n- `decision`\n- `action`\n- `runbook`\n- `context`\n- `session`\n\nSecret-looking content is blocked.\n\n## Status overlay\n\n`pi-memctx` keeps a small status overlay in Pi:\n\n```txt\n🧠 my-pack · memory ready · 3 memory hits · qmd · learn auto\n```\n\nThis tells you which pack is active, whether memory was useful, which search backend is being used, and whether automatic learning is enabled.\n\n## Best use cases\n\n`pi-memctx` is especially useful when:\n\n- you work on large repos or monorepos;\n- Pi keeps rediscovering architecture and deploy flows;\n- your team has many services with repeated conventions;\n- you want local memory without a hosted vector database;\n- you want agent memory you can read, edit, grep, and version;\n- you want planning/discovery sessions to become durable project notes.\n\n## Why not just RAG?\n\nMost RAG setups retrieve documents at query time. `pi-memctx` is different:\n\n- it is local-first and file-based;\n- it stores durable memories as Markdown;\n- it learns after turns, not only before prompts;\n- it links related memories together;\n- it can fall back to repo inspection when memory is stale;\n- it does not require a hosted vector database.\n\n## qmd integration\n\n`pi-memctx` uses [`@tobilu/qmd`](https://www.npmjs.com/package/@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.\n\nResolution order:\n\n1. `QMD_PATH` or `MEMCTX_QMD_BIN`\n2. an already-installed local `.bin` or bundled/vendor path\n3. `qmd` on `PATH`\n4. grep fallback\n\nOptional qmd install example:\n\n```bash\nnpm install -g @tobilu/qmd\n```\n\nCheck your setup:\n\n```bash\nnpx pi-memctx doctor\n```\n\n## Safety model\n\n`pi-memctx` is local-first and intentionally boring about sensitive data.\n\nIt will not save:\n\n- API keys\n- tokens\n- passwords\n- private keys\n- customer data\n- payment card data\n- sensitive payloads\n\nMemory is Markdown on disk. You can inspect every byte.\n\n## Configuration\n\nMost users should start with the defaults. Advanced users can configure behavior with environment variables or the local config file at `~/.config/pi-memctx/config.json`.\n\nCommon environment variables:\n\n| Variable | Purpose |\n|---|---|\n| `MEMCTX_CONTEXT_TOKEN_BUDGET` | Approximate injected context budget. |\n| `MEMCTX_CONTEXT_MAX_ITEMS` | Maximum memory items to include. |\n| `MEMCTX_RETRIEVAL` | Retrieval policy: `fast`, `balanced`, `deep`, `strict`, `auto`. |\n| `MEMCTX_GATEWAY_JUDGE` | Gateway judge mode: `off`, `conservative`, `auto`, `main-llm`. |\n| `MEMCTX_AUTOSAVE` | Autosave mode: `off`, `suggest`, `confirm`, `auto`. |\n| `QMD_PATH` / `MEMCTX_QMD_BIN` | Explicit qmd binary path. |\n\n## Development\n\nRequirements:\n\n- Node.js 20+\n- Bun for tests\n- Pi coding agent\n\nInstall dependencies:\n\n```bash\nnpm install\n```\n\nRun checks:\n\n```bash\nnpm run typecheck\nnpm test\nnpm run test:e2e\n```\n\nRun all CI checks:\n\n```bash\nnpm run ci\n```\n\nRun benchmark:\n\n```bash\nbash benchmark/setup.sh /tmp/pi-memctx-benchmark\nQMD_PATH=/tmp/pi-memctx-qmd/node_modules/.bin/qmd \\\nBENCH_REPEATS=1 \\\nBENCH_PROFILES=\"baseline gateway\" \\\nBENCH_TIMEOUT=120 \\\nbash benchmark/run.sh /tmp/pi-memctx-benchmark\n```\n\n## Contributing\n\nIssues and pull requests are welcome.\n\nGood contributions include:\n\n- better language-agnostic retrieval heuristics\n- safer memory extraction\n- clearer benchmark fixtures\n- docs and examples\n- profile tuning with reproducible numbers\n\nPlease do not commit private company memory packs, customer data, secrets, or benchmark fixtures derived from private repositories.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}