| name | processwire-memory |
| description | Stores and retrieves ProcessWire API patterns, gotchas, and conventions via memvid hybrid search. Use when starting PW tasks, hitting PW errors, or when user asks to remember/recall ProcessWire knowledge. Persistent cross-project memory at ~/.memvid/processwire.mv2 |
memvid -- ProcessWire Cross-Project Memory
Installation
npm install -g memvid-cli
If the memory file doesn't exist yet:
mkdir -p ~/.memvid && memvid create ~/.memvid/processwire.mv2
When to Store vs Retrieve
STORE proactively when you discover:
- Non-obvious PW API pattern, gotcha, or workaround
- Debugging insight involving ProcessWire internals
- PW convention or architectural decision worth preserving
- Correction to previously stored PW knowledge
- User requests storing a PW pattern
RETRIEVE when:
- Starting any ProcessWire task
- Encountering a PW error or familiar pattern
- User asks "do we know..." or "have we seen..." about PW
- Before PW architectural decisions
DO NOT store:
- Project-specific config (belongs in project CLAUDE.md)
- Transient debugging state (one-off errors)
- Non-PW knowledge (general PHP, CSS, JS patterns)
URI Convention
mv2://processwire/topic/subtopic
| Topic | Example URIs |
|---|
| api/pages | mv2://processwire/api/pages -- $pages API, PageArray, find/get |
| api/fields | mv2://processwire/api/fields -- field types, options, config |
| api/templates | mv2://processwire/api/templates -- template API, families |
| api/hooks | mv2://processwire/api/hooks -- hook system, priorities, events |
| api/modules | mv2://processwire/api/modules -- module API, autoload, config |
| selectors | mv2://processwire/selectors -- selector syntax, operators |
| templating | mv2://processwire/templating -- template files, rendering, regions |
| multilingual | mv2://processwire/multilingual -- LanguageSupport, translations |
| permissions | mv2://processwire/permissions -- access control, roles, pages |
| debugging | mv2://processwire/debugging -- common errors, diagnostics |
| patterns | mv2://processwire/patterns -- architectural patterns, conventions |
| migrations | mv2://processwire/migrations -- field/template setup, deployment |
Use --scope on retrieval to filter by URI prefix.
Quick Reference
All commands use $MV for ~/.memvid/processwire.mv2 below. In actual commands, use the full path.
| Operation | Command |
|---|
| Store a learning | echo "content" | memvid put $MV --embedding --uri mv2://processwire/topic --title "Short title" --tag source=project-name |
| Store from file | memvid put $MV --embedding --input file.md --uri mv2://processwire/topic --title "Title" |
| Bulk ingest (JSON) | cat batch.json | memvid put-many $MV --dedup (note: put-many does NOT support --embedding; use individual put --embedding per file for vector search, or pre-compute embeddings and include in batch JSON) |
| Correct a mistake | memvid correct $MV "The correct statement" --topics "processwire,topic" |
| Search | memvid find $MV --query "search terms" |
| View memory cards | memvid memories $MV |
| Statistics | memvid stats $MV |
Search
Use memvid find for all queries — it runs true hybrid search (BM25 + vector).
Do not use ask: broken — ignores --mode hybrid/sem, falls back to pure Tantivy lexical with poor semantic recall.
Storing Content
Always pass --embedding on every put call — required for hybrid search to work.
Anatomy of a good memory entry
echo 'ProcessWire $pages->find() returns a PageArray even for zero results.
Use $pages->count() for existence checks instead of empty() on the result,
because PageArray is never falsy. Discovered debugging blank template output
where empty($results) was always false.' | \
memvid put ~/.memvid/processwire.mv2 \
--embedding \
--uri mv2://processwire/api/pages \
--title "PageArray is never falsy - use count() for existence" \
--tag source=walz-relaunch \
--tag type=gotcha
Key qualities:
- What: the fact or pattern (PageArray never falsy)
- Why it matters: consequence of getting it wrong (blank output)
- Context: how it was discovered (debugging blank template)
- URI: scoped for retrieval (
mv2://processwire/api/pages)
- Tags: enable filtering (
source, type)
Useful tag conventions
| Tag | Values |
|---|
type | gotcha, pattern, convention, fix, architecture, api |
source | project name where learned |
confidence | high, medium, low |
Storing corrections
When you discover previous PW knowledge was wrong:
memvid correct ~/.memvid/processwire.mv2 \
"ProcessWire hook priority 100 runs AFTER default (0), not before. Higher number = later execution." \
--topics "processwire,hooks,priority"
Corrections get a retrieval boost so they surface above the wrong information.
Retrieving Content
At session start in a PW project
memvid find ~/.memvid/processwire.mv2 --query "processwire" --top-k 5
Scoped to a topic
memvid find ~/.memvid/processwire.mv2 --query "hooks" --scope mv2://processwire/api/hooks/
When hitting a specific error
memvid find ~/.memvid/processwire.mv2 --query "SQLSTATE[HY000] template not found"
Conceptual queries
Use keyword terms, not natural language — find is BM25-driven:
memvid find ~/.memvid/processwire.mv2 --query "multilingual page field language value"
Common Mistakes
| Mistake | Fix |
|---|
| Storing without URI | Always pass --uri — unscoped content is hard to retrieve |
Overly broad URI (mv2://processwire/) | Be specific: mv2://processwire/api/pages |
| Storing project-specific config | Belongs in project CLAUDE.md |
| Not searching before starting work | Retrieve at start of every PW task |
Using ask | Broken — use find instead |
| Storing non-PW knowledge | PW-only memory. General PHP/CSS/JS doesn't belong |
Storing without --embedding | Always pass --embedding on put (see put-many caveat in Quick Reference) |
