# MCP Memento

> Local-first MCP server that gives AI agents durable repo memory and fast semantic code context.

- **Type:** MCP server
- **Install:** `agentstack add mcp-caiowilson-mcp-memento`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [caiowilson](https://agentstack.voostack.com/s/caiowilson)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [caiowilson](https://github.com/caiowilson)
- **Source:** https://github.com/caiowilson/MCP-memento

## Install

```sh
agentstack add mcp-caiowilson-mcp-memento
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# memento-mcp

[](https://github.com/caiowilson/MCP-memento/releases)
[](https://github.com/caiowilson/MCP-memento/releases/tag/server%2Flatest)
[](https://github.com/caiowilson/MCP-memento/releases)
[](https://go.dev/)
[](./LICENSE)

[](https://ko-fi.com/caiowilson)

A local-first MCP server that gives AI agents durable, high-signal memory for your repository: indexed code context, semantic relationships, fast search, and explicit notes that persist across sessions.

fun easy tl;dr version of the change logs: [`Nomit Memento`](https://nomit.dev/caiowilson/MCP-memento)

## Languages

- English: `README.md`
- Brazilian Portuguese: [`README.pt-BR.md`](./README.pt-BR.md)

## Documentation

- Project docs: [`docs/README.md`](./docs/README.md)
- Generic MCP clients: [`docs/clients.md`](./docs/clients.md)
- VS Code usage: [`docs/vscode.md`](./docs/vscode.md)
- VS Code extension: [`vscode-extension/README.md`](./vscode-extension/README.md)
- ADR guide: [`docs/adr/README.md`](./docs/adr/README.md)
- ADR index and decisions: [`docs/adr/ADRs.md`](./docs/adr/ADRs.md)

## What It Does

- Exposes MCP tools for repo operations: `repo_list_files`, `repo_read_file`, `repo_search`, `repo_related_files`, `repo_context`, `repo_switch_workspace`
- Maintains an on-disk code index per repository for fast, bounded context retrieval
- Stores explicit repo-scoped notes: `memory_upsert`, `memory_search`, `memory_clear`
- Supports a companion VS Code extension that installs and configures the server

## How It Works

1. The server starts over stdio JSON-RPC and registers MCP tools.
2. It builds and updates a local chunk index under `~/.memento-mcp/`.
3. Change detection is incremental:
   - Default (`auto`): filesystem watcher first, fallback to `git status` polling for git repos if watcher fails
   - Configurable via `MEMENTO_CHANGE_DETECTOR` (`auto` / `fs` / `git`)
4. Context tools combine:
   - Indexed chunks and scoring
   - Language-aware relationships (Go, TS/JS, PHP)
   - Hard byte and line limits for LLM context safety
5. Explicit notes are stored separately as durable, repo-scoped memory.

## Project Structure

- `cmd/server/` - entrypoint
- `internal/mcp/` - MCP server and tool handlers
- `internal/indexing/` - chunking, manifest, search, incremental indexing
- `internal/app/` - app lifecycle wiring
- `vscode-extension/` - companion extension (installer and MCP config UX)
- `docs/` - usage docs and ADRs

## Contributing

### Prerequisites

- Go `1.25.5`
- Node.js (only if working on `vscode-extension/`)

### Local Development

```bash
git clone https://github.com/caiowilson/MCP-memento.git
cd MCP-memento
make build
./bin/memento-mcp
```

### Generic Client Onboarding

```bash
./bin/memento-mcp print-config
./bin/memento-mcp print-guidance
```

### Run Tests

```bash
go test ./...
```

### VS Code Extension Development

```bash
cd vscode-extension
npm install
npm run build
```

### Contribution Flow

1. Create a branch from `main`.
2. Make focused changes with tests and docs updates.
3. Run `go test ./...` (and extension build/tests when applicable).
4. Open a PR with:
   - Problem statement
   - Approach
   - Validation steps
   - Any tool or behavior changes

## Roadmap Themes

- Better context quality and ranking
- Broader semantic language support
- Extension UX and install reliability
- Release automation and operational tooling

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [caiowilson](https://github.com/caiowilson)
- **Source:** [caiowilson/MCP-memento](https://github.com/caiowilson/MCP-memento)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-caiowilson-mcp-memento
- Seller: https://agentstack.voostack.com/s/caiowilson
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.