Installation
Project Memory — what you learned stays
Store decisions, gotchas, and goals across agent sessions. Local SQLite on your machine — not a cloud memory SaaS, not a repo scanner.
Tool reference: project_memory MCP guide · HTTP vs stdio · get_project_context · NPX setup
One sentence
project_memoryis one of Zephex's ten MCP tools — four actions that persist learned facts per project: decisions you made, gotchas you hit, goals you set, conventions the team follows.
Tagline
What you learned stays. What the repo is — that's get_project_context.
Context tools scan files. Memory tools store what scanning cannot infer: tribal knowledge discovered while coding.
Terminal CLI (primary way for humans)
mcpcli remember "auth uses Supabase JWT in cookies"mcpcli recall authmcpcli memory listmcpcli memory forget <uuid> # Slash palette in interactive shell# /remember /recall /memoryNot package upgrades — that is mcpcli check-package next --task upgrade (legacy alias: loop-guard). See slash commands.
What it is not
- Not a replacement for
get_project_context(stack, scripts, layout) - Not automatic chat logging — every memory is an explicit
remembercall - Not a session-start token dump — recall is on-demand when you need it
- Not a full chat export — hosted cloud memory needs a dashboard-linked API key; local stdio still writes
~/.zephex/memory/when usingnpx zephexin editors
Two complementary tools
| get_project_context | project_memory | |
|---|---|---|
| Data source | Auto-scan manifests, config, git | Explicit remember calls |
| Updates when | On scan / cache refresh | Agent or user intends to save |
| Best for | New repo orientation | Returning to a repo across sessions |
| Transport | Local stdio + hosted HTTP | Local stdio only (v1) |
| Storage | Ephemeral scan results | ~/.zephex/memory/ SQLite |
Typical flow: get_project_context on day one → work and discover quirks → project_memory remember → new session next week → project_memory recall before touching that area again.
remember · recall · list · forget
One MCP tool. The action parameter selects the operation.
remember — save a fact
Requires title (max 80 chars), content (max 500 chars), and type. Optional area, tags, written_by. Paraphrase lessons — do not dump whole files.
{ "name": "project_memory", "arguments": { "action": "remember", "title": "Stripe webhook idempotency", "content": "Webhook handler dedupes by event.id in Redis 24h TTL. Do not use DB unique on raw payload.", "type": "decision", "area": "billing", "tags": ["stripe", "webhooks"], "written_by": "agent" }}recall — FTS5 keyword search
Requires query. Returns up to 5 matches with ~500 token budget. Updates last_recalled_at on hits. Call before editing unfamiliar subsystems.
{ "name": "project_memory", "arguments": { "action": "recall", "query": "stripe webhook idempotency billing" }}list — audit without bodies
Returns titles, types, areas, and ids — useful when near the 200-memory cap or cleaning stale entries.
forget — delete by id
Pass the uuid from remember or list. Rewrites .zephex/memory.md in project scope.
Memory types
decision— architectural or product choicegotcha— non-obvious trap or legacy constraintgoal— active objective across sessionspreference— team or user style preferencearea_fact— fact about a subsystemconvention— naming, error shape, or process rule
Where memory lives
All data stays on your machine under ~/.zephex/memory/ — the same home directory family as Test Pulse sessions and credentials.
~/.zephex/memory/├── index.json # registry: sha256 → { root, name, updated_at }├── personal/│ └── memories.db # when no project root detected└── projects/ └── {sha256(absRoot)}.db # one SQLite DB per projectProject isolation
Each absolute project root maps to sha256(root). Cursor's global-memory bleed problem is the cautionary tale — Zephex never mixes memories across projects unless you explicitly pass scope: "all" on recall (foreign hits get a warning field).
SQLite + FTS5
bun:sqlitewith WAL mode — concurrent-safe, sub-ms search at scale- FTS5 virtual table on title, content, area, tags — keyword recall, no embedding RAM hog
- 14-field
memoriestable +metakey/value per database - Hard cap: 200 memories per project
Markdown mirror
After remember or forget in project scope, Zephex rewrites <projectRoot>/.zephex/memory.md with titles and metadata. Gitignore it by default; use it to audit what agents stored without opening SQLite.
Why hosted MCP cannot use memory
zephex.dev/mcp is served via Vercel and forwards to Railway — it cannot read ~/.zephex on your laptop. Calling project_memory over HTTP returns a structured error instead of failing silently:
{ "error": "local_stdio_required", "message": "project_memory requires local stdio transport (npx zephex)...", "hint": "Use get_project_context, find_code, read_code on hosted MCP...", "docs": "https://zephex.dev/docs/tools/project-memory"}Fix: add stdio transport for memory while keeping HTTP for other tools, or use stdio for everything. See HTTP vs stdio.
Stdio config (Cursor / Claude Code)
{ "mcpServers": { "zephex": { "command": "npx", "args": ["-y", "zephex"], "env": { "ZEPHEX_API_KEY": "mcp_sk_your_key_here" } } }}No Node? curl -fsSL https://zephex.dev/cli/install.sh | bash. Already have Node 22.5+? npx -y zephex@latest (terminal) or npx -y zephex@latest setup --cursor (editor). Install & upgrade. Same CLI: mcpcli, zepx, zphx, mcpz, zepcli, zephx, or zephex (after npm i -g zephex).
What gets rejected on remember
Memory poisoning and secret leaks are blocked at write time:
- AWS keys (
AKIA…), Stripe live keys, OpenAIsk-… - GitHub
ghp_, Slackxoxb-tokens - PEM private keys
- Instruction-shaped content (
always ignore…,never skip…)
Rejected writes return status: "rejected" with a reason — never silent drop. Store the lesson, not the secret.
Privacy
Memory files never upload to Zephex servers in v1. Your API key still authenticates MCP calls, but memory content stays local. Each project_memory call counts as one request on your plan like any other tool.
How agents should use memory
New repo (first session)
get_project_context— stack, entry points, scripts- Work normally with
find_code/read_code project_memory rememberafter non-obvious discoveries
Returning repo (new session)
project_memory recallwith area keywords before editing- Apply returned facts — do not re-scan the whole repo for known gotchas
rememberupdates;forgetstale entries
Cross-editor continuity
Same npx zephex stdio install in Cursor Monday and Claude Code Thursday — same ~/.zephex/memory/ database for the same project root. That is the wedge vs editor-native memory silos.
Pairing with verification tools
check_test scopes files → agent implements → project_memory remembers the fix pattern if it was non-obvious. Memory captures the lesson so the next session does not re-learn it.
Caps and budgets
| Limit | Value |
|---|---|
| Memories per project | 200 (reject remember with cap_reached) |
| Title length | 80 characters |
| Content length | 500 characters |
| recall default hits | 5 (max 10 via limit) |
| recall token budget | ~500 tokens total response |
| Tags per memory | 10 |
| Scope default | project (current DB only) |
project · personal · all
project(default) — current project database only. Safe default; no cross-project leakage.personal—personal/memories.dbwhen cwd has no git/package markers. Global preferences like "prefer bun over npm."all(recall only) — searches every registered project plus personal. Each foreign match includes awarningso agents know the source project.
Project root detection walks up from cwd for .git, package.json, pyproject.toml, go.mod, or Cargo.toml.
Common issues
local_stdio_required- Switch MCP config from HTTP URL to
npx zephexstdio. Memory cannot run on hosted transport. rejected/secret_detected- Rephrase without API keys or tokens. Store the pattern, not the credential.
cap_reached- Run
list,forgetstale ids, thenrememberagain. - Empty recall on first visit
- No memories stored yet — expected.
recalldoes not create empty database files on virgin projects. - Wrong project memories
- Confirm cwd /
pathpoints at the correct root. Each root has its own hash.
v1 vs future
Shipped in v1:
- Single MCP tool, four actions
- Local SQLite FTS5 + WAL
- Project isolation, secret rejection, markdown export
- Hosted graceful error
Not in v1 (possible follow-ups):
zephex memoryCLI subcommands- SessionStart hook with ≤400 token inject
- Cloud sync / team shared memory
confidence,expires_at,supersedes_idin MCP schema