project_memory
What you learned stays — even when the chat resets.
Zephex project_memory stores and recalls project-specific learned facts (decisions, gotchas, goals, conventions) across agent sessions via local stdio MCP. It is not a repo scanner — use get_project_context for stack and structure. Requires npx zephex stdio; hosted HTTP returns local_stdio_required.
When to use
- User says remember this, don't forget, or recall what we learned about X.
- Starting a new session on a repo you worked on before — recall area-specific facts first.
- After a non-obvious discovery: encryption scheme, legacy path, team convention, deploy quirk.
- Auditing what the agent has stored — list titles before editing or deleting stale entries.
When not to use
- You need stack, scripts, or entry points — use get_project_context.
- You need to find a symbol or string — use find_code or read_code.
- You are on hosted HTTP MCP only and have not installed stdio — memory will not work.
- You want automatic capture of every chat turn — memory requires explicit remember calls.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| action | enum | Yes | remember | recall | list | forget |
| path | string | No | Absolute project root. Stdio auto-injects cwd when omitted. |
| title | string | remember | Max 80 chars. |
| content | string | remember | Max 500 chars. Paraphrase, not file dumps. |
| type | enum | remember | decision | gotcha | goal | preference | area_fact | convention |
| area | string | No | Subsystem label. Max 64 chars. |
| tags | string[] | No | Max 10 lowercase tags. |
| written_by | enum | No | user | agent (default agent) |
| query | string | recall | FTS5 keywords. |
| id | uuid | forget | Memory id from remember or list. |
| limit | number | No | recall/list cap. Default 5, max 10. |
| scope | enum | No | project (default) | personal | all |
Limits: v1 is MCP-only (no zephex memory CLI). Stdio required for read/write. No cloud sync. No automatic session bootstrap inject. remember does not force personal scope while inside a project.
Try it — copy a prompt
Paste into Cursor, Claude Code, Windsurf, VS Code, or any editor with a hosted MCP connection.
Before you call it
- Zephex stdio transport: npx zephex in .cursor/mcp.json, .mcp.json, or equivalent.
- ZEPHEX_API_KEY in env (same key as hosted MCP).
- Project opened at a real root (.git, package.json, or similar) for project-scoped memory.
Token and request cost
recall returns at most 5 matches (~500 tokens total). list returns titles only. remember stores compact snippets (max 500 chars body, 80 chars title) — not file dumps. Each MCP call counts as one request on your plan.
Example
MCP tools/call
{ "jsonrpc": "2.0", "id": 11, "method": "tools/call", "params": { "name": "project_memory", "arguments": { "action": "remember", "title": "Gallery encryption", "content": "AES-256-GCM in src/lib/crypto.ts encryptBuffer(). Do not modify legacy-v1 path.", "type": "gotcha", "area": "encrypted-gallery", "written_by": "agent" } }}Search response
Response shape
{ "action": "remember", "id": "550e8400-e29b-41d4-a716-446655440000", "status": "stored"}Step 2 — get full entry
{ "name": "project_memory", "arguments": { "action": "recall", "query": "encrypted gallery crypto legacy" }}Get response
{ "action": "recall", "scope": "project", "project_root": "/Users/dev/my-app", "matches": [{ "id": "550e8400-e29b-41d4-a716-446655440000", "title": "Gallery encryption", "content": "AES-256-GCM in src/lib/crypto.ts encryptBuffer()…", "type": "gotcha", "area": "encrypted-gallery", "written_by": "agent", "age_days": 3 }], "match_count": 1, "tokens_estimate": 142}Which Zephex tool when
| Task | Use this tool | Not this tool |
|---|---|---|
| Stack, scripts, monorepo layout | get_project_context | project_memory |
| Remember a decision across sessions | project_memory remember | keep_thinking |
| Find where a function is defined | find_code | project_memory |
| Recall area facts before editing | project_memory recall | read_code (whole files) |
What it can do in your codebase
- Project isolation — one SQLite DB per sha256(project root); no global bleed
- Four actions — remember, recall, list, forget in a single MCP tool
- Six memory types — decision, gotcha, goal, preference, area_fact, convention
- FTS5 search — fast keyword recall without embedding RAM cost
- Explicit writes — no auto-capture noise; agent or user intends each memory
- On-demand recall — no session-start token dump; call when you need context
- Secret rejection — blocks API keys, PEM private keys, instruction-shaped poisoning
- Markdown mirror — `.zephex/memory.md` in project root for human audit
- Cross-editor — same memory in Cursor, Claude Code, Windsurf, Zed via stdio
Common response fields
Why teams use it
Survives session resets
Facts persist in ~/.zephex/memory/ on your machine — new chats, new agents, same project root.
Pairs with code tools
Recall before find_code/read_code on unfamiliar areas; remember after discoveries the scan tools cannot infer.
Human-auditable
list shows titles; .zephex/memory.md mirrors project memories. No opaque embedding store.
Stdio-first security
Memory never leaves your disk in v1. Hosted MCP cannot read ~/.zephex — returns a clear error instead.
What it looks at vs skips
- Explicit remember calls from agent or user
- FTS5 index on title, content, area, tags
- Project root via .git / package.json / pyproject.toml / go.mod / Cargo.toml
- Automatic chat logging — every memory is intentional
- Repo structure detection — get_project_context
- Cloud sync in v1 — local SQLite only
- File dumps — max 500 char paraphrased snippets
Fields agents should read first
| Field | Meaning |
|---|---|
| type | decision | gotcha | goal | preference | area_fact | convention |
| area | Subsystem label (e.g. auth, billing) for scoped recall |
| written_by | user or agent — who authored the memory |
| scope | project (default) | personal | all (cross-project with warnings) |
| tokens_estimate | Approximate recall response size for token budgeting |
| status | stored | rejected | deleted | not_found |
Task modes
| task | What you get |
|---|---|
| remember | Save a compact fact. Requires title, content, type. Max 200 per project. |
| recall | FTS5 keyword search. Max 5 hits, ~500 token budget. |
| list | Titles and metadata only — audit without loading bodies. |
| forget | Delete by uuid. Updates .zephex/memory.md in project scope. |
Actions
How it fits your workflow
- get_project_context — orient on a new repo
- project_memory recall — before editing an unfamiliar subsystem
- find_code / read_code — implement with code context
- project_memory remember — after a non-obvious discovery
Troubleshooting
- local_stdio_required → switch editor config to npx zephex stdio; see /docs/http-vs-stdio and /docs/project-memory.
- rejected secret_detected → never store API keys or tokens; paraphrase the lesson without secrets.
- cap_reached (200 memories) → list oldest entries and forget stale ids before remembering more.
- Empty recall on virgin project → no DB yet; remember first or confirm cwd is the correct project root.
- Cross-project bleed → use default scope project; only scope:all adds warnings on foreign hits.
How to verify it works
- Confirm npx zephex stdio in MCP config (not HTTP-only).
- Call remember with title, content, and type — expect status stored and a uuid id.
- Open a new session; call recall with keywords — expect the same fact in matches[].
- Open .zephex/memory.md in the project root — titles should mirror stored memories.
Common questions
Billing and plan limits: FAQ, usage limits.
What is the difference between project_memory and get_project_context?
get_project_context scans manifests and config to detect stack, scripts, and layout. project_memory stores learned facts you or the agent explicitly save — decisions, gotchas, goals — across sessions.
Why does hosted MCP return local_stdio_required?
Memory lives at ~/.zephex/memory/ on your machine. Hosted zephex.dev/mcp cannot access your filesystem. Install stdio via npx zephex for memory; use hosted MCP for the other ten tools.
How many memories can I store?
200 per project database. Titles max 80 characters; content max 500 characters. recall returns up to 5 matches (~500 tokens). Use forget to remove stale entries when near the cap.
Where is memory stored on disk?
~/.zephex/memory/projects/{sha256(projectRoot)}.db per project, plus personal/memories.db when no project root is detected. A .zephex/memory.md file in your repo mirrors project-scoped titles.
Can memories leak between projects?
No with default scope project — each root gets its own database. scope:all searches registered projects and adds a warning on each foreign match.
What content is rejected on remember?
API keys (AWS, Stripe, OpenAI, GitHub, Slack), PEM private keys, and instruction-shaped poisoning patterns. The tool returns status rejected with a reason — never silent drop.
Does project_memory replace keep_thinking?
No. keep_thinking tracks structured reasoning within a session. project_memory persists durable facts across sessions — complementary tools.
How do I use project_memory with Cursor?
Add npx zephex stdio to .cursor/mcp.json. Say: recall what we learned about auth, or remember: JWT refresh tokens live in httpOnly cookies, type gotcha, area auth.
On a new repo: get_project_context for stack and layout, then project_memory recall for learned facts.
Billing: Each tool call counts as one request on your Zephex plan (Free includes 555 requests/month). See usage limits for tier details. Usage limits.
Data: Secrets are rejected on write. Memory is local-only — not transmitted to Zephex servers. Gitignore .zephex/memory.md by default; export for team sharing is opt-in. Data use.
get_project_context scans the repo for stack facts; project_memory stores what you learned while working (see also get_project_context.
For AI agents (JSON)
{"tool":"project_memory","when":"remember/recall cross-session facts","need":"stdio npx zephex; action + fields per action"}