@folterung/project-memory

Project Memory

Local-first project understanding for Cursor: scoped indexing, embeddings, and Cursor integration.

Quick start

Option A — Run tasks (easiest)
Open this repo in Cursor/VS Code, then Terminal → Run Task (or Cmd+Shift+B for default build task) and pick:

• Project Memory: Init — create .mem/ (config, state dir, docker-compose copy) and .memignore
• Project Memory: Scaffold — Phase 1: start Qdrant, build index, start memory server (default build task)

Then register the MCP server in Cursor (or Claude Desktop) and use the agent with the Project Memory skill.

Using with Cursor MCP

Register the Project Memory MCP server in Cursor, Claude Desktop, or any MCP client. The agent can then call search_project_memory, explain_symbol, refresh_project_memory_index, and store_project_memory (store a summary or finding so future search can use it — incremental context from the agent). Ask the agent to refresh the index when the codebase changes so the vector DB stays up to date.

• Ensure the memory server is running (mem scaffold in the project).
• Add the MCP server: In Cursor, add the server via MCP settings (e.g. .cursor/mcp.json in the project) with a stdio config pointing at project-memory-mcp. An example config is in docs/mcp-config.example.json—copy to .cursor/mcp.json if needed. Set MEM_SERVER_URL in env if the server is not on the default port (default http://127.0.0.1:31415). If the project has node_modules/@folterung/project-memory, run the MCP from that package; otherwise use project-memory-mcp on your PATH (e.g. after npm install -g @folterung/project-memory). See docs/commands.md and Cursor’s MCP docs for the config format.
• Logs: Tool calls and responses are written to /tmp/project-memory-mcp.log on macOS/Linux, or %TEMP%\project-memory-mcp.log on Windows. Override with PROJECT_MEMORY_MCP_LOG_FILE. Every line is prefixed with [project: <name>] (workspace dir name or PID) so multiple projects sharing the same file are distinguishable. Use tail -f /tmp/project-memory-mcp.log to watch.

Option B — npm scripts
From the repo root (run mem:init once for first-time setup):

npm install && npm run build
npm run mem:init
npm run mem:scaffold

Option C — CLI directly

• From this repo: run from the repo root; run init first if you haven’t (e.g. via Option A or B), then scaffold:

  node packages/cli/bin/mem.js init
  node packages/cli/bin/mem.js scaffold
  

• From another repo: after npm install -g @folterung/project-memory, run in that repo:

  mem init
  mem scaffold
  

Requirements

• Node.js 18+
• Docker and Docker Compose (for Qdrant)

Documentation

Topic	Doc
Architecture (diagram, pipeline, components)	docs/architecture.md
Commands (tasks, scripts, CLI)	docs/commands.md
Configuration (config.yml, .memignore, defaults)	docs/configuration.md
Packages (CLI, server, MCP, skill)	docs/packages.md
Cursor skill (use Project Memory in the agent)	docs/skill.md
Testing (run tests, coverage)	docs/testing.md
Development (build, run services)	docs/development.md
Publishing (npm, use in other projects)	docs/publishing.md

All docs live under docs/. The Cursor skill (packages/skill) tells the agent when and how to use Project Memory; see docs/skill.md to install it. When using the published npm package in another project, copy the skill from node_modules/@folterung/project-memory/packages/skill to .cursor/skills/project-memory/ (or ~/.cursor/skills/project-memory/) so the agent gets the full usage rules.