pi-memctx

Local-first memory context for Pi coding agents.

What it does • Install • Setup • Context • Tools • Commands • Docs • Development

Automatic memory context injection for Pi coding agent.

Your agent forgets everything between sessions. Every new conversation starts from zero — re-discovering project structure, re-reading conventions, re-asking about deploy procedures. pi-memctx fixes this.

The problem

Without persistent memory, coding agents waste time and tokens on every session:

You: "How do I deploy to production?"

Agent: Let me explore the project...
  $ find . -name "*.yml" | grep deploy      # scanning...
  $ cat .github/workflows/ci.yaml           # reading...
  $ ls kubernetes/                           # more scanning...
  $ cat README.md                            # still looking...
  
  → 30+ seconds, 8 tool calls, misses key details

The fix

pi-memctx loads project context before the agent starts thinking:

You: "How do I deploy to production?"

Agent: Based on your deploy runbook:
  1. Push to main triggers GitHub Actions
  2. CI builds → Docker → ECR → Helm values update
  3. ArgoCD auto-syncs to staging
  4. Production requires manual approval in ArgoCD
  
  → 5 seconds, 0 tool calls, all key details correct

Measured impact

Run bash benchmark/setup.sh && bash benchmark/run.sh to measure on your own project.

Typical results across 5 common tasks:

What this means for your team

Less tokens = lower API cost. Better answers = less rework. Faster responses = less waiting.

Install

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

Quick start

1. Generate a pack from your project

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

# Inside pi:
/pack-generate

This scans your repos for README.md, CLAUDE.md, go.mod, package.json and builds a memory pack automatically.

2. Let the agent learn organically

As you work, the agent discovers and saves knowledge:

You: "remember that we use pgx instead of database/sql"

Agent: Saved decision: pgx-over-database-sql
       → packs/my-project/50-decisions/pgx-over-database-sql.md

The pack grows over time with real operational knowledge.

3. Knowledge persists across sessions

Next session, the agent already knows:

You: "set up a new database connection"

Agent: Based on your conventions, I'll use pgx with connection pooling
       (per your decision in pgx-over-database-sql)...

How it works

pi starts → detect pack for cwd → load context
                                      │
user sends prompt ────────────────────┤
                                      │
  1. Search pack for relevant memories (qmd semantic or grep)
  2. Build prioritized context (manifest → context → search → actions → decisions → runbooks)
  3. Inject into system prompt (16K char budget)
                                      │
agent responds ───────────────────────┤
                                      │
  4. Agent can save learnings (memctx_save)
  5. Session handoff captured on compaction

Context priority

Not everything fits. Sections are included by priority — lower-priority content is trimmed first:

Pack structure

Packs are just Markdown files with frontmatter. Edit them in any editor or Obsidian.

~/.pi/agent/memory-vault/packs/my-project/
  00-system/
    pi-agent/
      memory-manifest.md     # Pack entrypoint
      resource-map.md        # Repos, services, environments
    indexes/
      context-index.md       # Links to context packs
      decision-index.md      # Links to decisions
      runbook-index.md       # Links to runbooks
  20-context/
    backend.md               # Stack, architecture, conventions
    frontend.md              # Framework, components, build commands
  50-decisions/
    001-hexagonal-arch.md    # Why we chose this architecture
    002-use-pgx.md           # Why pgx over database/sql
  70-runbooks/
    deploy.md                # Step-by-step deploy procedure
    terraform.md             # Infrastructure operations

Tools

memctx_search

Search across pack files:

use memctx_search to find information about deploy

Modes: keyword (fast), semantic (2s), deep (10s).

Install qmd for semantic search: npm install -g @tobilu/qmd

Without qmd, search uses keyword grep (still works, just less smart).

memctx_save

Persist learnings to the active pack:

save this as a decision: we use integer cents for all monetary values

Types: observation, decision, action, runbook, context.

Safety: automatically blocks secrets, tokens, API keys, private keys.

Commands

Multiple packs

With multiple packs, pi-memctx auto-detects the best one based on your working directory:

cd ~/code/my-api       # → loads "my-api" pack
cd ~/code/my-infra     # → loads "infra" pack
cd ~/code              # → loads org-level pack

Switch mid-session with /pack.

Pack locations

Packs are resolved in order:

Benchmark

Measure the impact on your own project:

# Setup fictional test scenario
bash benchmark/setup.sh

# Run 5 tasks with and without pi-memctx
bash benchmark/run.sh

Documentation

• Getting started
• Architecture
• Safety
• Search
• Persistence
• Development
• Publishing

Development

npm ci
npm run typecheck
npm test
npm run test:e2e
npm run ci

Please read CONTRIBUTING.md and SECURITY.md before opening a pull request.

License

MIT