Skip to content

TUTORIAL.md

Latest commit

 

History

History
225 lines (156 loc) · 7.06 KB

TUTORIAL.md

File metadata and controls

225 lines (156 loc) · 7.06 KB
Raw

projectmem — Tutorial

Watch the 60-second promo: youtu.be/YCqfJ8-XVqY A full screen-recorded walkthrough is coming soon — this written version covers the same flow step-by-step so you can follow along on your own project.

This is the 15-minute tour. By the end you'll have set up projectmem on a real project, watched the AI agent log a bug → record a failed attempt → record the fix, and seen the pre-commit warning catch you the next time you almost repeat the same mistake.

What you'll need

  • Python ≥ 3.10
  • A git repository you can experiment in (or a fresh git init somewhere)
  • An MCP-capable AI client — any of: Claude Desktop, Cursor, Antigravity (legacy IDE), Codex. The flow is identical across all four.

Step 1 — Install

pip install projectmem

Two console commands ship: pjm (the CLI) and pjm-mcp (the MCP server that your AI client talks to).

Step 2 — Initialize in your project

cd path/to/your/project
pjm init

You should see, in order:

  1. .projectmem/ directory created with events.jsonl, summary.md, PROJECT_MAP.md, AI_INSTRUCTIONS.md.
  2. CLAUDE.md created at the repo root — the rules-file bridge that instructs AI clients to call projectmem's MCP tools before reading source.
  3. PROJECT_MAP.md pre-populated from your pyproject.toml / package.json / Cargo.toml / go.mod — no manual stack tour needed (new in 0.1.3).
  4. Git hooks installed — pre-commit for failure warnings, post-commit and post-merge for auto-capture.
  5. A printed MCP client config block with your absolute paths already filled in (new in 0.1.3) — copy it.

Step 3 — Wire up your AI client

Paste the printed config block into your client's MCP config file:

Client Config file
Claude Desktop ~/Library/Application Support/Claude/claude_desktop_config.json
Cursor ~/.cursor/mcp.json (per-project) or via Settings → MCP
Antigravity (legacy) ~/.gemini/antigravity/mcp_config.json
Codex ~/.codex/config.toml (TOML, not JSON)

Then fully quit and restart the client (cold start — closing the window isn't enough; MCP servers initialize only on launch).

Verify the connection: open your client's tools panel. You should see 14 projectmem tools. Hover search_events — its query and limit parameters should show descriptions. If they don't, you're not on 0.1.3.

Step 4 — First chat: Setup Mode

Open a new chat in your AI client. Paste:

I just added projectmem to this project. Please get the project summary, and since the memory is still empty, read the source files and set it up: capture what this project is, its stack, and any architectural decisions worth recording. Then regenerate the summary.

The agent will:

  1. Call get_summary → see the placeholder content.
  2. Read your source files.
  3. Call add_decision and add_note to record what it learns.
  4. Call get_summary again to confirm the new state.

You're now in Setup Mode → done. Memory is populated.

Step 5 — Hit a bug, watch the lifecycle

Pick any real bug in your project. In your AI chat:

Bug: <describe the symptom>. Log this as an issue in projectmem, then investigate the cause.

Expect: log_issue followed by the agent reading the relevant files.

Try a fix that you think might be wrong:

Try <approach A> first. If it doesn't work, we'll try something else.

When it doesn't fix the bug:

That didn't work. Record it as a failed attempt in projectmem, then revert it.

Expect: record_attempt with outcome="failed". This is the seed that makes the pre-commit warning fire later.

Now apply the real fix:

The real fix is <approach B>. Apply it, confirm the bug is gone, and record the fix.

Expect: record_fix — the issue closes, memory is sealed.

Run pjm show in your terminal — you'll see the full audit trail: issue → failed attempt → fix.

Step 6 — The killer feature: pre-commit warning

A week from now, in a totally different chat, the AI agent forgets and suggests approach A again (the failed one). You apply it without thinking, stage it, and:

git commit -m "fix: try approach A"

projectmem's pre-commit hook intercepts and prints:

projectmem: Pre-Commit Check
  <file>
    WARN  1 failed attempt on this file
    Last failure: tried approach A — didn't fix the bug

You pivot before committing the same dead end. That's the judgment layer. Memory + warning at the moment of action.

If the warning doesn't fire, run pjm hooks install — pjm init auto-installs hooks but only when .git/hooks/ exists at the moment of init.

Step 7 — New chat: Maintenance Mode

Open a brand-new chat in your AI client (fresh context). Paste:

Get me up to speed on this project — what is it, what's been worked on recently, and are there any known gotchas I should avoid?

The agent will call get_summary / get_context and answer from memory — no re-reading of source files. That's the token savings in action: a fresh session inherits everything the previous one learned.

Step 8 — See your value

pjm score        # A–F grade + hours saved + tokens saved + USD saved
pjm visualize    # interactive D3 dashboard in your browser

The score is your concrete answer to "is this thing actually saving me time?"

What just happened

In about 15 minutes you exercised every part of projectmem:

Feature Where you saw it
Setup Mode (Step 4) Agent populated summary.md and PROJECT_MAP.md
Issue → attempt → fix lifecycle (Step 5) log_issue, record_attempt, record_fix
Pre-commit warning (Step 6) git commit printed the warning
Maintenance Mode (Step 7) Fresh chat answered from memory, no file scan
Token savings (Step 7 + 8) pjm score reports the saved-token estimate
Secret redaction Any API key you accidentally pasted is auto-scrubbed before disk

Common gotchas

  • Pre-commit warning doesn't fire → .git/hooks/pre-commit doesn't exist. Run pjm hooks install. Under conda/venv, 0.1.3 bakes the absolute pjm path into the hook — confirm with head .git/hooks/pre-commit.
  • Agent re-reads files instead of using memory → your client may not surface the MCP instructions= field strongly. projectmem also writes a CLAUDE.md rules file at the repo root for exactly this — open that file and confirm the bridge block is intact.
  • Multiple machines / team members → .projectmem/ is meant to be committed to git. Each clone inherits the memory. Don't .gitignore it.

Where to go next

  • Cross-project memory: lessons learned in one repo can surface in others with the same stack (~/.projectmem/global/). Try pjm global show to see what's accumulated across your machine.
  • Issues + feature requests: github.com/riponcm/projectmem/issues.

Last updated for projectmem 0.1.3.