npm package: @folterung/project-memory
Description: Local-first Project Memory: scoped indexing, embeddings, Cursor integration
Latest version: 0.2.3

# 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](docs/skill.md).

### 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](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](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):

```bash
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:
  ```bash
  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:
  ```bash
  mem init
  mem scaffold
  ```

## Requirements

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

## Documentation

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

All docs live under [docs/](docs/). The **Cursor skill** ([packages/skill](packages/skill)) tells the agent when and how to use Project Memory; see [docs/skill.md](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.