### Install memtrace using Go

Source: https://github.com/memtrace-dev/memtrace/blob/main/README.md

Alternatively, install memtrace using the Go toolchain. This requires Go to be installed and configured.

```bash
go install github.com/memtrace-dev/memtrace/cmd/memtrace@latest
```

--------------------------------

### Example Memtrace MCP Server Configuration

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

These JSON examples show the structure of the MCP server configuration file for Memtrace, including how to specify the command, arguments, and environment variables.

```json
# Resulting .claude/mcp.json (Claude Code project scope):
# {
#   "mcpServers": {
#     "memtrace": {
#       "command": "memtrace",
#       "args": ["serve"]
#     }
#   }
# }
```

```json
# To pass an embeddings API key through the MCP client config:
# {
#   "mcpServers": {
#     "memtrace": {
#       "command": "memtrace",
#       "args": ["serve"],
#       "env": { "MEMTRACE_EMBED_KEY": "sk-..." }
#     }
#   }
# }
```

--------------------------------

### Install Memtrace via Homebrew or Go

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Choose either Homebrew or Go for installing the Memtrace CLI. Ensure your Go environment is set up if you opt for the Go installation.

```bash
# Homebrew
brew install memtrace-dev/tap/memtrace
```

```bash
# Go
go install github.com/memtrace-dev/memtrace/cmd/memtrace@latest
```

--------------------------------

### Setup Memtrace MCP Server for Agents

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Configure your AI agent to use Memtrace by running `memtrace setup`. This command is idempotent and supports various agents. You can target specific agents or set it up globally.

```bash
# Auto-detect from .claude/, .cursor/, .vscode/, opencode.json, .gemini/
memtrace setup
```

```bash
# Target a specific agent
memtrace setup claude-code   # writes to .claude/mcp.json
memtrace setup cursor        # writes to .cursor/mcp.json
memtrace setup vscode        # writes to .vscode/mcp.json
memtrace setup opencode      # writes to opencode.json
memtrace setup windsurf      # writes to ~/.codeium/windsurf/mcp_config.json
memtrace setup gemini        # writes to .gemini/settings.json
memtrace setup --global      # writes to ~/.claude/mcp.json (all projects)
```

--------------------------------

### OpenCode Agent Setup

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/setup.md

Configures the memtrace agent for OpenCode, writing to `opencode.json` in the project root. This setup uses a local type for the memtrace server.

```bash
memtrace setup opencode
```

```json
{
  "mcp": {
    "memtrace": {
      "type": "local",
      "command": ["memtrace", "serve"]
    }
  }
}
```

--------------------------------

### Install memtrace locally

Source: https://github.com/memtrace-dev/memtrace/blob/main/README.md

Builds the memtrace binary and copies it to your Go bin directory, making it accessible in your PATH.

```bash
make install
```

--------------------------------

### Install memtrace using Homebrew

Source: https://github.com/memtrace-dev/memtrace/blob/main/README.md

Use this command to install memtrace via Homebrew. Ensure Homebrew is installed on your system.

```bash
brew install memtrace-dev/tap/memtrace
```

--------------------------------

### Gemini CLI Agent Setup

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/setup.md

Configures the memtrace agent for Gemini CLI, writing to `.gemini/settings.json` in the project root. This setup defines the memtrace server configuration.

```bash
memtrace setup gemini
```

```json
{
  "mcpServers": {
    "memtrace": {
      "command": "memtrace",
      "args": ["serve"]
    }
  }
}
```

--------------------------------

### Windsurf Agent Setup

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/setup.md

Sets up the memtrace agent for Windsurf, writing to `~/.codeium/windsurf/mcp_config.json`. Windsurf only supports global configuration.

```bash
memtrace setup windsurf
```

```json
{
  "mcpServers": {
    "memtrace": {
      "command": "memtrace",
      "args": ["serve"]
    }
  }
}
```

--------------------------------

### VS Code (Copilot) Agent Setup

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/setup.md

Sets up the memtrace agent for VS Code (Copilot), writing to `.vscode/mcp.json`. This configuration specifies the server type and command.

```bash
memtrace setup vscode
```

```json
{
  "servers": {
    "memtrace": {
      "type": "stdio",
      "command": "memtrace",
      "args": ["serve"]
    }
  }
}
```

--------------------------------

### Cursor Agent Setup

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/setup.md

Configures the memtrace agent for Cursor, writing to `.cursor/mcp.json`. The format is the same as for Claude Code.

```bash
memtrace setup cursor
```

--------------------------------

### Get configuration value

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/cli.md

Retrieves a specific configuration value from memtrace.

```bash
memtrace config  get
```

--------------------------------

### Claude Code Project Scope Setup

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/setup.md

Sets up memory configuration for the Claude Code project scope, writing to `.claude/mcp.json`. Recommended for project-specific memory.

```bash
memtrace setup claude-code
```

```json
{
  "mcpServers": {
    "memtrace": {
      "command": "memtrace",
      "args": ["serve"]
    }
  }
}
```

--------------------------------

### Auto-detect Agent Setup

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/setup.md

Run this command to automatically detect and configure the MCP config entry for your agent. It is idempotent and merges into existing configs.

```bash
memtrace setup   # auto-detect from .claude/, .cursor/, .vscode/, opencode.json, .gemini/
```

--------------------------------

### Serve MCP server

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/cli.md

Starts the MCP server over stdio. This command is typically called by an agent and not run directly by the user. It can use the current directory or a specified directory.

```bash
memtrace serve            # uses current directory
```

```bash
memtrace serve --dir /path/to/project
```

--------------------------------

### Setup memtrace agent configuration

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/cli.md

Writes the MCP server entry into your agent's config file. It's idempotent and can auto-detect configurations or be specified for a particular agent.

```bash
memtrace setup              # auto-detect from .claude/, .cursor/, .vscode/, opencode.json, .gemini/
```

```bash
memtrace setup claude-code  # .claude/mcp.json
```

```bash
memtrace setup cursor       # .cursor/mcp.json
```

```bash
memtrace setup vscode       # .vscode/mcp.json
```

```bash
memtrace setup opencode     # opencode.json
```

```bash
memtrace setup windsurf     # ~/.codeium/windsurf/mcp_config.json
```

```bash
memtrace setup gemini       # .gemini/settings.json
```

```bash
memtrace setup --global     # ~/.claude/mcp.json (Claude Code user scope)
```

--------------------------------

### memory_prompt

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/mcp-tools.md

Captures the user's original request at the start of a session as an event memory.

```APIDOC
## memory_prompt

### Description
Capture the user's original request at the very start of a session, before any other memory operations. Stored as an `event` tagged `prompt` so future sessions can understand what was attempted and why.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **content** (string) - Required - The user's original request content.
- **file_paths** (array of strings) - Optional - File paths associated with the prompt.

### Request Example
```python
memory_prompt(
  content="Refactor auth middleware to support multi-tenant JWT validation",
  file_paths=["src/auth/middleware.go"]
)
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the prompt was saved.

#### Response Example
```json
{
  "message": "User prompt saved successfully."
}
```
```

--------------------------------

### Markdown Memory Format Example

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/import-export.md

An example of the Markdown format for memories, featuring type headings, metadata lists, and descriptive content. This format is human-readable and editable.

```markdown
## [decision] We use JWT with RS256 — stateless API, no session storage

- Tags: auth, security
- Confidence: 1.00
- Created: 2026-03-22T10:00:00Z
- Files: src/middleware/auth.go

We use JWT with RS256 for authentication. The API is completely stateless — no session
storage anywhere in the system. Access tokens expire after 1 hour, refresh tokens after 30 days.

---

## [convention] Error handling: always wrap with fmt.Errorf

- Tags: go, errors
- Confidence: 0.95
- Created: 2026-03-20T08:00:00Z

All errors must be wrapped with fmt.Errorf("context: %w", err) so they are inspectable
with errors.Is / errors.As at the call site.
```

--------------------------------

### Example of memtrace memory operations

Source: https://github.com/memtrace-dev/memtrace/blob/main/README.md

Illustrates how an agent interacts with memtrace to save and recall information across different sessions. Data is stored locally in a SQLite database.

```text
Session 1
  agent → memory_save("We use JWT RS256 — stateless API, no session storage.")
  agent → memory_save("Auth middleware lives in src/middleware/auth.go")

Session 2 (new chat, blank context)
  agent → memory_recall("auth")
  ← "We use JWT RS256 — stateless API, no session storage."
  ← "Auth middleware lives in src/middleware/auth.go"
```

--------------------------------

### Get memtrace status

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/cli.md

Displays the current configuration and database state of memtrace. Use the --json flag for machine-readable output.

```bash
memtrace status
```

```bash
memtrace status --json
```

--------------------------------

### Markdown Export Format for Memories

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

An example of the Markdown format used for exporting memories, which is human-editable before reimporting.

```markdown

```

--------------------------------

### Claude Code User Scope Setup

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/setup.md

Sets up memory configuration for the Claude Code user scope globally, writing to `~/.claude/mcp.json`. This configuration applies to all projects.

```bash
memtrace setup --global
```

--------------------------------

### Get statistics

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/cli.md

Retrieves statistics for memtrace, with options to specify the number of days and output in JSON format.

```bash
memtrace stats  [--days 7] [--json]
```

--------------------------------

### Pull Nomic Embeddings Model with Ollama

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/embeddings.md

Pull the necessary embedding model for Ollama. Memtrace will automatically detect it on the next start.

```bash
ollama pull nomic-embed-text
```

--------------------------------

### Run memtrace doctor health check

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/cli.md

Executes comprehensive health checks on the memtrace setup, reporting on database status, memory indexing, and configuration issues. Use this to diagnose potential problems.

```bash
memtrace doctor
```

```text
  [ok]   Database:        .memtrace/memtrace.db (24 KB, 42 memories)
  [ok]   Stale memories:  none
  [ok]   Embeddings:      ollama (nomic-embed-text)
  [ok]   Unembedded:      all memories indexed
 [warn]  MCP config:      memtrace not found — run 'memtrace setup'
  [ok]   CLAUDE.md:       memtrace instructions present
```

--------------------------------

### Get relevant memories with memory_context

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/mcp-tools.md

Call memory_context with a list of file paths to retrieve memories relevant to those files. It prioritizes file-matched memories over semantically related ones.

```go
memory_context(
  file_paths: ["src/auth/middleware.go", "src/auth/handler.go"],
  limit:      10
)
```

--------------------------------

### Initialize Memtrace in a Project

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Use `memtrace init` to set up Memtrace in your current project. It creates the necessary database and configuration files, and optionally imports existing memories.

```bash
# Standard init — auto-imports from Claude Code memories, .cursorrules, and git history
memtrace init
```

```bash
# Override the project name
memtrace init --name "my-api"
```

```bash
# Skip auto-import of existing memories
memtrace init --no-import
```

--------------------------------

### Build memtrace binary

Source: https://github.com/memtrace-dev/memtrace/blob/main/README.md

Use this make command to build the memtrace binary. The executable will be placed in the 'bin/' directory.

```bash
make build
```

--------------------------------

### Initialize memtrace in a project

Source: https://github.com/memtrace-dev/memtrace/blob/main/README.md

Run this command within your project directory to initialize memtrace. This sets up the necessary configuration for memory persistence.

```bash
cd your-project
memtrace init
```

--------------------------------

### Create a cross-platform memtrace build snapshot

Source: https://github.com/memtrace-dev/memtrace/blob/main/README.md

Generates a build snapshot of the memtrace binary for various platforms using goreleaser, without publishing the release.

```bash
make snapshot
```

--------------------------------

### Initialize memtrace

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/cli.md

Initializes memtrace in the current project. Creates necessary files and directories, adds to gitignore, and appends instructions to CLAUDE.md. Can override the project name or skip auto-import.

```bash
memtrace init
```

```bash
memtrace init --name "my-api"   # override the project name
```

```bash
memtrace init --no-import       # skip auto-import
```

--------------------------------

### CLAUDE.md Instructions for Memtrace Tools

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/setup.md

Instructions to append to `CLAUDE.md` or a project's system prompt to direct Claude to use memtrace tools for all memory operations instead of built-in memory.

```markdown
This project has the memtrace MCP server connected. Use memory_save, memory_recall,
memory_get, memory_forget, memory_update, memory_context, and memory_prompt for all
memory operations — do not use built-in memory tools.
```

--------------------------------

### Capture user prompt with memory_prompt

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/mcp-tools.md

Use memory_prompt to record the user's initial request at the beginning of a session. This is stored as an event tagged 'prompt' for future reference.

```go
memory_prompt(
  content:    "Refactor auth middleware to support multi-tenant JWT validation",
  file_paths: ["src/auth/middleware.go"]   // optional
)
```

--------------------------------

### Round-trip Memory Export and Import

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/import-export.md

Demonstrates a typical round-trip workflow: exporting memories from one project and importing them into another. It includes a preview step using `--dry-run` before the final import.

```bash
# Export from project A
cd project-a
memtrace export --format markdown --output ../shared-conventions.md

# Import into project B
cd ../project-b
memtrace import ../shared-conventions.md --dry-run   # preview first
memtrace import ../shared-conventions.md
```

--------------------------------

### Preview Import without Saving

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/import-export.md

Use the `--dry-run` flag to preview the import process without actually saving the changes. This is helpful for verifying the import content.

```bash
memtrace import memories.md --dry-run
```

--------------------------------

### Create and release a new memtrace version

Source: https://github.com/memtrace-dev/memtrace/blob/main/README.md

Tags the current version and pushes it to trigger the GitHub release workflow. Replace '1.2.3' with the desired version number.

```bash
make release VERSION=1.2.3
```

--------------------------------

### Configure memtrace settings

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/cli.md

Manages persistent configuration for memtrace, including embed keys, URLs, and models. Settings are stored in a JSON file, but environment variables take precedence.

```bash
memtrace config get
```

```bash
memtrace config set embed.key sk-...
```

```bash
memtrace config set embed.model text-embedding-3-small
```

```bash
memtrace config unset embed.key
```

--------------------------------

### Preview Linking Memory to Code

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/concepts.md

Perform a dry run of the `memtrace link` command without saving any changes. This allows you to preview which symbols would be linked.

```bash
memtrace link --dry-run src/auth/*.go
```

--------------------------------

### Configure Custom Local Embeddings Server

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/embeddings.md

Configure memtrace to use a custom local server that is compatible with the OpenAI API. No API key is required for local servers.

```bash
memtrace config set embed.url http://localhost:8080/v1
```

```bash
memtrace config set embed.model my-model
```

--------------------------------

### List Memories from CLI with memtrace list

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Lists memories with optional filters for type and status. Supports limiting the number of results and outputting in JSON format.

```bash
memtrace list
```

```bash
memtrace list --type convention
```

```bash
memtrace list --status stale      # review memories flagged by memtrace scan
```

```bash
memtrace list --limit 50 --json
```

--------------------------------

### Import Memories from URL

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/import-export.md

Import memories directly from an HTTP or HTTPS URL. This is convenient for fetching data from remote sources.

```bash
memtrace import https://example.com/memories.json
```

--------------------------------

### MCP Tool: memory_prompt

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Captures the user's initial request for a session as a memory. This is tagged as 'prompt' and helps in retaining context for future sessions.

```APIDOC
## memory_prompt

### Description
Captures the user's original request at the very start of a session as an `event` tagged `prompt`. Future sessions can then understand what was previously attempted and why.

### Parameters
#### Request Body
- **content** (string) - Required - The content of the user's prompt.
- **file_paths** (array of strings) - Optional - A list of file paths associated with the prompt.
```

--------------------------------

### CLI: memtrace link

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Parses source files to create memories for top-level symbols (functions, types, etc.). Supports multiple languages including Go, TypeScript, JavaScript, Python, and Rust. Can perform a dry-run to preview changes without saving.

```APIDOC
## memtrace link

### Description
Parses source files and creates one memory per top-level symbol (functions, types, structs, interfaces, classes, enums, traits). Supports Go (AST), TypeScript, JavaScript, Python, and Rust.

### Usage
```bash
memtrace link <file_path> [--dry-run] [--type <type>]
```

### Parameters
#### Positional Arguments
- **file_path** (string) - Required - The path to the source file(s) to link.

#### Options
- **--dry-run** - Optional - Preview the linking process without saving any memories.
- **--type** (string) - Optional - Specify the memory type to assign to the linked symbols.
```

--------------------------------

### Set configuration value

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/cli.md

Sets a configuration value for memtrace.

```bash
memtrace config  set <key> <value>
```

--------------------------------

### Configure MCP Client to Pass Embeddings API Key

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/embeddings.md

Add environment variables to your MCP configuration to make the embeddings API key available when `memtrace serve` is running.

```json
{
  "mcpServers": {
    "memtrace": {
      "command": "memtrace",
      "args": ["serve"],
      "env": {
        "MEMTRACE_EMBED_KEY": "sk-..."
      }
    }
  }
}
```

--------------------------------

### View memtrace status and statistics

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Displays current configuration, database state, and memory activity over a rolling time window. Can output in JSON format for programmatic use.

```bash
memtrace status
memtrace status --json

memtrace stats              # default 7-day window
memtrace stats --days 30 --json
```

--------------------------------

### CLI: memtrace list

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Lists existing memories with optional filters for type and status. Can also limit the number of results and output in JSON format.

```APIDOC
## memtrace list

### Description
Lists memories with optional filters for type and status.

### Usage
```bash
memtrace list [--type <type>] [--status <status>] [--limit <number>] [--json]
```

### Parameters
#### Options
- **--type** (string) - Optional - Filters the list to memories of a specific type.
- **--status** (string) - Optional - Filters the list by memory status (e.g., 'stale').
- **--limit** (integer) - Optional - The maximum number of memories to list.
- **--json** - Optional - Outputs the list in JSON format.
```

--------------------------------

### Link source files to memories

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/cli.md

Parses source files and creates memories for top-level symbols. Supports multiple languages and links memories to source files for automatic context retrieval. Includes a dry-run option.

```bash
memtrace link src/auth/middleware.go
```

```bash
memtrace link --dry-run src/auth/*.go
```

--------------------------------

### Save memory with private content

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/mcp-tools.md

When saving sensitive information, wrap it in `<private>...</private>` tags. This content will be stripped before storage.

```go
memory_save(
  content: "Auth uses JWT RS256. <private>Signing key: sk-prod-abc123</private> Tokens expire after 1h.",
  type: "convention"
)
// stored as: "Auth uses JWT RS256.  Tokens expire after 1h."
```

--------------------------------

### Import Memories from File

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/import-export.md

Import memories from a file. The tool automatically detects the format based on the file extension (e.g., .md for Markdown, .json for JSON).

```bash
memtrace import memories.md
```

```bash
memtrace import memories.json
```

--------------------------------

### Configure semantic search embeddings

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Sets up hybrid BM25 and vector semantic search. Supports auto-detection of local Ollama, OpenAI API, or custom compatible endpoints. Use `memtrace reindex` to backfill embeddings for existing memories.

```bash
# Zero-config: Ollama (auto-detected if running)
ollama pull nomic-embed-text
memtrace status
# Embeddings: ollama (nomic-embed-text)
```

```bash
# OpenAI API key via config
memtrace config set embed.key sk-...
memtrace config set embed.model text-embedding-3-small   # default
```

```bash
# OpenAI API key via environment variable
export MEMTRACE_EMBED_KEY=sk-...
```

```bash
# Custom local OpenAI-compatible endpoint (no key needed)
memtrace config set embed.url http://localhost:8080/v1
memtrace config set embed.model my-model
```

```bash
# Backfill embeddings for memories saved before embedder was configured
memtrace reindex
```

```bash
# Disable semantic search (BM25 only)
memtrace config set embed.provider disabled
# or: MEMTRACE_EMBED_PROVIDER=disabled
```

--------------------------------

### Force Import Format

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/import-export.md

Explicitly specify the import format using the `--format` flag when the file extension might be ambiguous or incorrect.

```bash
memtrace import backup.txt --format json
```

--------------------------------

### Link Symbols from Source Files with memtrace link

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Parses source files (Go, TypeScript, JavaScript, Python, Rust) to create memories for top-level symbols. Supports linking all symbols, previewing changes, and specifying memory types.

```bash
# Link all symbols from a file
memtrace link src/auth/middleware.go
```

```bash
# Preview without saving
memtrace link --dry-run src/auth/*.go
```

```bash
# Link with a specific memory type
memtrace link --type fact src/api/handlers.go
```

--------------------------------

### Open interactive memory browser

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Launches a full-screen terminal UI for interactively browsing, searching, editing, and deleting memories. Provides key bindings for common actions.

```bash
memtrace browse
# Key bindings:
#   /      — filter/search
#   enter  — view full memory
#   e      — edit in $EDITOR
#   d      — delete (with confirmation)
#   esc    — back
#   q      — quit
```

--------------------------------

### Configure OpenAI API Key and Model

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/embeddings.md

Set the OpenAI API key and optionally the model name in memtrace configuration. This key is used by both the CLI and MCP server.

```bash
memtrace config set embed.key sk-...
```

```bash
memtrace config set embed.model text-embedding-3-small   # optional, this is the default
```

--------------------------------

### Configure agent to use memtrace

Source: https://github.com/memtrace-dev/memtrace/blob/main/README.md

Execute this command to automatically detect and configure your AI agent to use memtrace. Supports various agents like Claude Code, Cursor, and VS Code.

```bash
memtrace setup
```

--------------------------------

### Export and Import Memories with memtrace export/import

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Exports memories to JSON or Markdown and imports them back, supporting various formats, filters, and URLs. Includes a dry-run option for previewing imports.

```bash
# Export
memtrace export --output memories.json
```

```bash
memtrace export --format markdown --output memories.md
```

```bash
memtrace export --type decision --output decisions.json
```

```bash
memtrace export --status stale --output stale.json
```

```bash
# Import (format auto-detected by extension)
memtrace import memories.md
```

```bash
memtrace import memories.json
```

```bash
memtrace import memories.md --dry-run          # preview without saving
```

```bash
memtrace import memories.json --type decision  # import only decisions
```

```bash
memtrace import https://example.com/memories.json  # import from URL
```

```bash
# Round-trip: share conventions between projects
cd project-a && memtrace export --format markdown --output ../shared.md
cd ../project-b && memtrace import ../shared.md --dry-run && memtrace import ../shared.md
```

--------------------------------

### Link Memory to Code

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/concepts.md

Parse source files to create memories for top-level symbols like functions and types. Supports multiple languages including Go, TypeScript, JavaScript, Python, and Rust.

```bash
memtrace link src/auth/middleware.go

# Linking src/auth/middleware.go (3 symbols):
#   saved  01KMFOO...  function `ValidateJWT`
#   saved  01KMBAR...  struct `AuthConfig`
#   saved  01KMBAZ...  interface `Validator`
# 3 symbols linked.
```

--------------------------------

### Verify Ollama Embeddings Configuration

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/embeddings.md

Check the memtrace status to confirm that Ollama is being used for embeddings.

```bash
memtrace status
```

--------------------------------

### Run memtrace tests

Source: https://github.com/memtrace-dev/memtrace/blob/main/README.md

Executes all defined tests for the memtrace project to ensure functionality and stability.

```bash
make test
```

--------------------------------

### Set OpenAI API Key via Environment Variable

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/embeddings.md

Alternatively, set the OpenAI API key using an environment variable. This method is useful for CI/CD or temporary configurations.

```bash
export MEMTRACE_EMBED_KEY=sk-...
```

--------------------------------

### Update memory confidence and manage topic keys

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Allows manual override of a memory's confidence score via the CLI. Demonstrates the `topic_key` pattern for preventing duplicate memories when content evolves, ensuring updates modify existing entries rather than creating new ones.

```bash
# Manual confidence override via CLI
memtrace update 01KMDX71NT --confidence 0.5
```

```python
# topic_key deduplication pattern:
memory_save(content: "We use Postgres 16", type: "decision", topic_key: "decision/database")
# → later, upgrading:
memory_save(content: "We use Postgres 17 — upgraded March 2026", type: "decision", topic_key: "decision/database")
# → updates the existing memory, no duplicate created

# Good topic_key naming: hierarchical and stable
```

--------------------------------

### Update an existing memory with memory_update

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/mcp-tools.md

Modify an existing memory using memory_update by providing its ID and the fields to change. Other fields remain preserved.

```go
memory_update(
  id:         "01KMDX71NT...",
  content:    "Updated decision text",
  type:       "decision",
  tags:       ["auth", "api"],
  file_paths: ["src/auth/middleware.go"],
  confidence: 0.8
)
```

--------------------------------

### Backfill Existing Memories with Embeddings

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/embeddings.md

Run the `reindex` command to generate and store vectors for memories that were created before an embedder was configured.

```bash
memtrace reindex
```

--------------------------------

### CLI: memtrace export / memtrace import

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Exports memories to JSON or Markdown format and imports them back into the system. Supports filtering exports by type or status, importing from URLs, and previewing imports with a dry-run option.

```APIDOC
## memtrace export / memtrace import

### Description
Exports memories to JSON or Markdown and imports them back, including from URLs. Supports filtered export and dry-run preview.

### Usage: Export
```bash
memtrace export [--output <file>] [--format <json|markdown>] [--type <type>] [--status <status>]
```

### Usage: Import
```bash
memtrace import <file_path_or_url> [--dry-run] [--type <type>]
```

### Export Options
- **--output** (string) - Optional - The file path to save the exported memories. Defaults to stdout.
- **--format** (string) - Optional - The format for export ('json' or 'markdown'). Defaults to JSON.
- **--type** (string) - Optional - Filters export to memories of a specific type.
- **--status** (string) - Optional - Filters export to memories with a specific status (e.g., 'stale').

### Import Options
- **--dry-run** - Optional - Preview the import process without saving any memories.
- **--type** (string) - Optional - Specify the memory type to assign during import. Format is auto-detected by file extension.
```

--------------------------------

### Manage memtrace configuration

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Reads and writes persistent configuration for the embeddings provider. Environment variables always take precedence over config file values. Configuration is stored in a platform-specific JSON file.

```bash
memtrace config get
memtrace config set embed.key sk-...
memtrace config set embed.model text-embedding-3-small
memtrace config set embed.url http://localhost:8080/v1
memtrace config unset embed.key

# Config is stored at:
# macOS:   ~/Library/Application Support/memtrace/config.json
# Linux:   ~/.config/memtrace/config.json
# Windows: %AppData%\memtrace\config.json
# (Environment variables always take precedence over config file values)
```

--------------------------------

### CLI: memtrace save

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Saves a new memory from the command line, analogous to the `memory_save` MCP tool. Allows specifying content, type, tags, associated files, and confidence score.

```APIDOC
## memtrace save

### Description
Saves a memory from the command line.

### Usage
```bash
memtrace save "<memory content>" [--type <type>] [--tags <tag1,tag2,...>] [--files <file1,file2,...>] [--confidence <score>]
```

### Parameters
#### Positional Arguments
- **content** (string) - Required - The text content of the memory to save.

#### Options
- **--type** (string) - Optional - The type of the memory (e.g., 'decision', 'fact').
- **--tags** (string) - Optional - Comma-separated list of tags for the memory.
- **--files** (string) - Optional - Comma-separated list of file paths associated with the memory.
- **--confidence** (float) - Optional - The confidence score for the memory (0.0–1.0).
```

--------------------------------

### Export Memories to JSON

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/import-export.md

Use this command to export memories to a JSON file, which is the default format. This is useful for programmatic access and storage.

```bash
memtrace export --output memories.json
```

--------------------------------

### List memories

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/cli.md

Lists memories with optional filters for type, status, and limit. Can output in JSON format.

```bash
memtrace list
```

```bash
memtrace list --type convention
```

```bash
memtrace list --status stale
```

```bash
memtrace list --limit 50 --json
```

--------------------------------

### View memtrace statistics

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/cli.md

Shows memory activity over a rolling window. Use --days to specify the duration and --json for structured output.

```bash
memtrace stats
```

```bash
memtrace stats --days 30 --json
```

--------------------------------

### CLI: memtrace search

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Searches memories from the command line using a hybrid search pipeline. Supports basic keyword search and filtering by memory type, with options for limiting results and outputting in JSON format.

```APIDOC
## memtrace search

### Description
Searches memories from the command line using the same hybrid BM25 + semantic pipeline.

### Usage
```bash
memtrace search "<query>" [--type <type>] [--limit <number>] [--json]
```

### Parameters
#### Positional Arguments
- **query** (string) - Required - The search query string.

#### Options
- **--type** (string) - Optional - Filters search results to a specific memory type.
- **--limit** (integer) - Optional - The maximum number of search results to return.
- **--json** - Optional - Outputs the search results in JSON format.
```

--------------------------------

### memory_context

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/mcp-tools.md

Retrieves memories relevant to specified files, combining direct file-path matching with semantic recall.

```APIDOC
## memory_context

### Description
Get all memories relevant to the files you are about to read or edit. Combines direct file-path matching with semantic recall — call this at the start of any task.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- **file_paths** (array of strings) - Required - An array of file paths to find relevant memories for.
- **limit** (integer) - Optional - Maximum number of results to return. Default: 10.

### Request Example
```python
memory_context(
  file_paths=["src/auth/middleware.go", "src/auth/handler.go"],
  limit=10
)
```

### Response
#### Success Response (200)
- **memories** (array of objects) - A list of relevant memory summaries.
  - **id** (string) - The unique identifier of the memory.
  - **type** (string) - The type of the memory.
  - **timestamp** (string) - When the memory was created or last updated.
  - **summary** (string) - A brief summary of the memory content.
  - **relevance** (string) - Indicates how the memory is relevant (`[file match]` or `[related]`).

#### Response Example
```json
{
  "memories": [
    {
      "id": "01KMDX71NT...",
      "type": "convention",
      "timestamp": "2d ago",
      "summary": "Use JWT RS256 for stateless auth.",
      "relevance": "[file match]"
    },
    {
      "id": "01KMDX72AB...",
      "type": "decision",
      "timestamp": "1w ago",
      "summary": "Implement multi-tenant support.",
      "relevance": "[related]"
    }
  ]
}
```
```

--------------------------------

### Save Memory from CLI with memtrace save

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Saves a memory from the command line, analogous to the `memory_save` MCP tool. Allows specifying content, type, tags, associated files, and confidence level.

```bash
memtrace save "We use Postgres 16 with pgvector for embeddings" \
  --type decision \
  --tags database,postgres \
  --files src/db/client.go \
  --confidence 0.95
```

--------------------------------

### Save a memory

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/cli.md

Saves a memory from the command line with specified content, type, tags, and associated files.

```bash
memtrace save "We use Postgres 16 with pgvector for embeddings" \
  --type decision \
  --tags database,postgres \
  --files src/db/client.go
```

--------------------------------

### Save a memory with memory_save

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/mcp-tools.md

Use memory_save to store information that should persist across sessions. Specify content, type, tags, and optionally file paths and a topic key for updates.

```go
memory_save(
  content:    "We use JWT RS256 — stateless API, no session storage",
  type:       "decision",             // decision | convention | fact | event
  tags:       ["auth", "security"],
  file_paths: ["src/middleware/auth.go"],
  topic_key:  "decision/auth"         // optional — re-saving with the same key updates instead of creating a duplicate
)
```

--------------------------------

### Import Filtered Memories

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/import-export.md

Import specific types of memories from a file by using the `--type` flag. This allows for selective loading of data.

```bash
memtrace import memories.json --type decision
```

--------------------------------

### List Event Memories

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/concepts.md

Retrieve a list of memories that are of type `event`. These are automatically generated summaries of session activities.

```bash
memtrace list --type event
```

--------------------------------

### MCP Tool: memory_get

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Retrieves the full content of a memory by its unique identifier. This is useful for obtaining complete details after identifying a memory through other means.

```APIDOC
## memory_get(id: "01KMDX71NT...")

### Description
Retrieves the full content of a memory by ID. Use after `memory_recall` or `memory_context` to read complete details.

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the memory to retrieve.
```

--------------------------------

### Recall Memories with `memory_recall`

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Search memories using natural language queries with `memory_recall`. You can filter by type and limit the number of results. Use `memory_get` with the returned ID for full content.

```python
memory_recall(
  query: "authentication approach",
  limit: 10,           # optional, default 10, max 50
  type:  "decision"    # optional filter: decision | convention | fact | event
)
# Example output:
# Found 3 memories:
#
# [01KMDX71NT...] decision · 3d ago · confidence: 0.9
# We use JWT RS256 — stateless API, no session storage
# tags: auth, security
#
# [01KMDX72AB...] convention · 1h ago · confidence: 1.0
# Error handling: always wrap with fmt.Errorf("...: %w", err)
# tags: go, errors
#
# Call memory_get with an ID to read the full content.
```

--------------------------------

### Save Memory with Topic Key

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/concepts.md

Assign a stable, hierarchical `topic_key` to a memory to prevent duplicates and facilitate updates. This is useful for tracking evolving concepts.

```python
memory_save(
  content:   "We use Postgres 16 with pgvector",
  type:      "decision",
  topic_key: "decision/database"
)

// Later, when you upgrade:
memory_save(
  content:   "We use Postgres 17 with pgvector — upgraded March 2026",
  type:      "decision",
  topic_key: "decision/database"   // updates the existing memory instead of creating a new one
)
```

--------------------------------

### Run memtrace doctor health check

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Executes comprehensive health checks on database integrity, stale memories, embeddings configuration, MCP wiring, and CLAUDE.md instructions. Use this to diagnose potential issues.

```bash
memtrace doctor
#   [ok]   Database:        .memtrace/memtrace.db (24 KB, 42 memories)
#   [ok]   Stale memories:  none
#   [ok]   Embeddings:      ollama (nomic-embed-text)
#   [ok]   Unembedded:      all memories indexed
#  [warn]  MCP config:      memtrace not found — run 'memtrace setup'
#   [ok]   CLAUDE.md:       memtrace instructions present
```

--------------------------------

### memory_get

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/mcp-tools.md

Retrieves the full content of a memory using its unique ID.

```APIDOC
## memory_get

### Description
Retrieve the full content of a memory by ID. Use this after `memory_recall` or `memory_context`.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- **id** (string) - Required - The unique identifier of the memory to retrieve.

### Request Example
```python
memory_get(id="01KMDX71NT...")
```

### Response
#### Success Response (200)
- **content** (string) - The full content of the memory.
- **type** (string) - The type of the memory.
- **tags** (array of strings) - Tags associated with the memory.
- **file_paths** (array of strings) - File paths associated with the memory.
- **topic_key** (string) - The topic key of the memory, if set.

#### Response Example
```json
{
  "content": "Auth uses JWT RS256. Tokens expire after 1h.",
  "type": "convention",
  "tags": ["auth", "security"],
  "file_paths": ["src/middleware/auth.go"],
  "topic_key": "decision/auth"
}
```
```

--------------------------------

### MCP Tool: memory_context

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Retrieves memories relevant to a given set of file paths. It prioritizes memories directly matched to the file paths and then includes semantically related memories.

```APIDOC
## memory_context

### Description
Returns all memories relevant to a set of files — file-path-matched memories first (labeled `[file match]`), then semantically related ones (`[related]`). Call this at the start of any task before reading or editing files.

### Parameters
#### Query Parameters
- **file_paths** (array of strings) - Required - A list of file paths to find relevant memories for.
- **limit** (integer) - Optional - The maximum number of memories to return.
```

--------------------------------

### Retrieve memory content with memory_get

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/mcp-tools.md

Call memory_get with a memory ID to retrieve its full content. This is typically used after memory_recall or memory_context.

```go
memory_get(id: "01KMDX71NT...")
```

--------------------------------

### Delete memory by ID or query

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/mcp-tools.md

Use memory_forget to delete a memory. You can specify the memory by its ID or by providing a query string to delete the top matching memory.

```go
memory_forget(id: "01KMDX71NT...")        // delete by ID
```

```go
memory_forget(query: "old jwt approach")  // delete top match
```

--------------------------------

### Export Memories to Markdown

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/import-export.md

Export memories to a Markdown file for human readability and manual editing. This format is useful for documentation and review.

```bash
memtrace export --format markdown --output memories.md
```

--------------------------------

### CLI: memtrace scan

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Scans all memories that reference source files and marks them as 'stale' if the corresponding files have been modified or deleted since the memory was last updated. Provides a summary of changes.

```APIDOC
## memtrace scan

### Description
Checks all memories that reference source files and marks them stale when files have been modified or deleted since the memory was last updated.

### Usage
```bash
memtrace scan
```

### Output Example
```
  stale  01ABCDEF1234  "Auth uses RS256 JWT..." — file modified: src/auth/middleware.go
  stale  01EFGH567890  "Schema migration v3..." — file deleted: db/migrations/003.sql

2 memories marked stale (11 unchanged).
```
```

--------------------------------

### Save a Memory with `memory_save`

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Use `memory_save` to store information across sessions. Specify the type, tags, and optionally a `topic_key` to update existing memories. Sensitive content can be enclosed in `<private>` tags.

```python
memory_save(
  content=    "We use JWT RS256 — stateless API, no session storage. <private>Signing key: sk-prod-abc123</private> Tokens expire after 1h.",
  type=       "decision",             # decision | convention | fact | event  (default: fact)
  tags=       ["auth", "security"],
  file_paths= ["src/middleware/auth.go"],
  topic_key=  "decision/auth"         # re-saving with the same key updates instead of duplicating
)
# stored content: "We use JWT RS256 — stateless API, no session storage.  Tokens expire after 1h."

# Updating the same decision later — no duplicate created:
memory_save(
  content=   "We switched to Paseto v4 — stateless, no session storage. Tokens expire after 2h.",
  type=      "decision",
  topic_key= "decision/auth"
)
```

--------------------------------

### Search memories

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/cli.md

Searches memories using a natural language query, with options to filter by type and limit results. Can output in JSON format.

```bash
memtrace search "auth approach"
```

```bash
memtrace search "database" --type decision --limit 5
```

```bash
memtrace search "error handling" --json
```

--------------------------------

### memory_save

Source: https://context7.com/memtrace-dev/memtrace/llms.txt

Saves a memory across sessions. Supports four types: `decision`, `convention`, `fact`, `event`. Sensitive text can be wrapped in `<private>` tags to be stripped before storage. Use `topic_key` to update an existing memory instead of creating a duplicate.

```APIDOC
## memory_save

### Description
Saves a memory across sessions. Supports four types: `decision`, `convention`, `fact`, `event`. Wrap sensitive text in `<private>...</private>` to strip it before storage. Use `topic_key` to update an existing memory instead of creating a duplicate.

### Parameters
- **content** (string) - Required - The content of the memory.
- **type** (string) - Optional - The type of memory (`decision`, `convention`, `fact`, `event`). Defaults to `fact`.
- **tags** (array of strings) - Optional - Tags associated with the memory.
- **file_paths** (array of strings) - Optional - Paths to files related to the memory.
- **topic_key** (string) - Optional - A key to identify and update existing memories.

### Request Example
```apidoc
memory_save(
  content="We use JWT RS256 — stateless API, no session storage. <private>Signing key: sk-prod-abc123</private> Tokens expire after 1h.",
  type="decision",
  tags=["auth", "security"],
  file_paths=["src/middleware/auth.go"],
  topic_key="decision/auth"
)
```

### Response
(Implicitly returns a success status or identifier for the saved memory)

### Example Usage
```apidoc
// Stored content after privacy redaction:
// "We use JWT RS256 — stateless API, no session storage.  Tokens expire after 1h."

// Updating the same decision later — no duplicate created:
memory_save(
  content="We switched to Paseto v4 — stateless, no session storage. Tokens expire after 2h.",
  type="decision",
  topic_key="decision/auth"
)
```
```

--------------------------------

### Update Memory Confidence

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/concepts.md

Manually set the confidence score for a specific memory using its ID. Confidence ranges from 0.0 to 1.0.

```bash
memtrace update 01KMDX71NT --confidence 0.5
```

```python
memory_update(id: "01KMDX71NT...", confidence: 0.5)
```

--------------------------------

### Search memories with memory_recall

Source: https://github.com/memtrace-dev/memtrace/blob/main/docs/mcp-tools.md

Use memory_recall to search memories using natural language queries. You can filter by type and set a limit for the number of results.

```go
memory_recall(
  query: "authentication approach",
  limit: 10,            // optional, default 10, max 50
  type:  "decision"     // optional filter
)
```