epost-local-memory-mcp

Local, file-based MCP memory server (stdio). No cloud.

Each machine stores memories as JSON files under MEMORY_DIR (set this when launching).

Requirements

• Node.js 18+

Tools

| Tool | Description | |------|-------------| | add_memory | Save text (+ optional tags / entity scopes) | | search_memories | Keyword search; usage includes memoryTokens and estTokensSaved | | get_context_pack | Deterministic capped pack (app+run). Flags: packOnly (omit items[]), includeConventions (merge run=conventions), returns packHash for drift checks | | get_memories | List with filters + pagination | | get_memory | Get by UUID | | update_memory | Overwrite text | | delete_memory | Delete one | | delete_all_memories | Bulk delete (confirm: true) | | list_entities | List user/agent/app/run scopes | | delete_entities | Delete a scope (confirm: true) |

Prompt cache vs MCP (important)

| | Cursor Cache Read | MCP get_context_pack / memories | |--|----------------------|----------------------------------------| | What | Automatic reuse of a stable prompt prefix inside one chat | Durable JSON facts on disk | | Survives new chat? | No | Yes | | MCP writes it? | No — Cursor/provider only | Yes |

Pattern: store facts with MCP → load the same get_context_pack early each turn (packOnly=true, same args) → Cursor can Cache-Read that stable blob. Prefer includeConventions=true on ticket runs so one call covers conventions + ticket. New chat → call get_context_pack again (MCP reloads; Cache Read starts fresh and small). Defer add_memory to handoff so packHash stays stable within a chat.

Preferred call (cache-friendly)

{
  "app": "my-app",
  "run": "feature-x",
  "includeConventions": true,
  "packOnly": true,
  "maxItems": 20,
  "maxChars": 4000
}

Response includes pack, packHash, includedConventions, usage — no bulky items[] when packOnly is true. Same packHash next turn → pack unchanged.

Example: useful “cache” with MCP

Feature work scoped as app=my-app, run=feature-x.

1) Store once (after research)

{
  "text": "Decision: use approach A for edge case B; entrypoint path/to/module → handler().",
  "app": "my-app",
  "run": "feature-x",
  "tags": ["decision"]
}

Call add_memory with that payload (and any other compact notes for the same app+run).

2) Every later turn in the same chat — load the pack first

{
  "app": "my-app",
  "run": "feature-x",
  "maxItems": 20,
  "maxChars": 4000
}

get_context_pack returns the same pack string every time (oldest-first, capped), e.g.:

# context-pack app=my-app run=feature-x
- [d0fcc477] tags=decision Decision: use approach A for edge case B; ...

• Turn 2+ in same chat: that identical prefix is cheap to reuse via Cursor Cache Read (fresh Input stays smaller because you did not re-grep the whole repo).
• Without MCP: each turn re-discovers the same facts → large fresh Input + growing transcript → Cache Read balloons on the whole chat history.

3) New chat after handoff

Cache Read resets (good). Call the same get_context_pack — MCP restores a small pack of facts instead of pasting the old long thread.

Long chat, no MCP:  transcript ↑ → Cache Read ↑ every turn
MCP + pack:         small stable pack → better Cache Read on pack; skip rediscovery
MCP + new chat:     pack reload → continuity without carrying the old transcript

Connect (Cursor)

Add to .cursor/mcp.json (project) or Cursor user MCP settings:

{
  "mcpServers": {
    "local-memory": {
      "command": "npx",
      "args": ["-y", "epost-local-memory-mcp"],
      "env": {
        "MEMORY_DIR": "C:/absolute/path/to/.cursor/memories"
      }
    }
  }
}

Or after a local clone/build:

{
  "mcpServers": {
    "local-memory": {
      "command": "node",
      "args": ["C:/path/to/epost-local-memory-mcp/dist/index.js"],
      "env": {
        "MEMORY_DIR": "C:/absolute/path/to/.cursor/memories"
      }
    }
  }
}

Always set MEMORY_DIR to an absolute path. The process cwd is not reliable under npx.

After changing this package locally, run npm run build and restart the MCP server in Cursor so get_context_pack appears.

Develop

npm install
npm run build
npm start

npm publish runs prepublishOnly → npm run build automatically. Published files are only dist/, README.md, and LICENSE (see package.json files).

Publish

npm login
npm publish

Consumers: npx -y epost-local-memory-mcp.

Why this helps

| | Bad way | Better way (MCP) | |--|---------|------------------| | Turn 1 | Re-read many large files | Research once, then add_memory | | Later turns same chat | History + re-reads → huge Cache Read | Same get_context_pack → stable small prefix | | New chat | Paste old thread or start over | get_context_pack again → small continuity |

Rule of thumb: MCP stores the fact; get_context_pack reloads it; Cursor caches the pack inside a chat. New chat = call pack again — don’t carry the old transcript.

License

MIT — see LICENSE.