### Install Mnemex CLI using UV Tool

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/installation.md

Installs the Mnemex project and its 7 CLI commands directly from its GitHub repository using UV's tool install feature. This is the recommended method for a straightforward setup.

```bash
uv tool install git+https://github.com/simplemindedbot/mnemex.git
```

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

### Verify Mnemex Installation and CLI Tools

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/quickstart.md

Checks if the Mnemex command-line interface (CLI) tools are installed and accessible. Ensures the Mnemex version and help commands for search and maintenance tools are functional.

```bash
# Check MCP server
mnemex --version

# Check CLI tools
mnemex-search --help
mnemex-maintenance --help
```

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

### Development Setup with uv or pip

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Sets up the Mnemex project for development using an editable installation. This allows for direct code modification and testing. It requires cloning the repository and installing dependencies using either uv or pip, followed by environment configuration.

```bash
# Clone the repository
git clone https://github.com/simplemindedbot/mnemex.git
cd mnemex

# Install with uv (recommended)
uv pip install -e ".[dev]"

# Or with pip
pip install -e ".[dev]"

# Copy environment template
cp .env.example .env

# Edit .env with your settings
vim .env
```

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

### Verify Mnemex Installation and Entry Points

Source: https://github.com/simplemindedbot/mnemex/blob/main/pypi.txt

Commands to install the published Mnemex package in a new virtual environment and verify that its command-line entry points are accessible and functioning.

```bash
python -m venv fresh-venv
source fresh-venv/bin/activate
pip install mnemex==0.4.1
mnemex --help
mnemex-search --help
mnemex-maintenance --help
```

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

### Configure Claude Desktop for Mnemex Development

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/installation.md

Provides a JSON configuration snippet for Claude Desktop to run the Mnemex MCP server during development. It specifies the command to use, arguments, and environment variables for proper setup.

```json
{
  "mcpServers": {
    "mnemex": {
      "command": "uv",
      "args": ["--directory", "/path/to/mnemex", "run", "mnemex"],
      "env": {"PYTHONPATH": "/path/to/mnemex/src"}
    }
  }
}
```

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

### Perform Mnemex Search Operations

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/quickstart.md

Demonstrates various ways to search memories using the Mnemex CLI. Supports basic keyword searches, filtering by tags, and limiting the number of results returned.

```bash
# Basic search
mnemex-search "Python"

# Filter by tags
mnemex-search "Python" --tags coding,projects

# Limit results
mnemex-search "Python" --limit 10
```

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

### Development Install Mnemex with UV

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/installation.md

Clones the Mnemex repository and installs it in editable mode with development dependencies using UV. This method is suitable for contributors who plan to modify the project's code.

```bash
git clone https://github.com/simplemindedbot/mnemex.git
cd mnemex
uv pip install -e ".[dev]"
```

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

### Migrating from Editable Install to UV Tool Install

Source: https://github.com/simplemindedbot/mnemex/blob/main/README.md

Steps to uninstall an editable Mnemex installation and switch to the recommended UV tool install. This simplifies the setup and management of Mnemex.

```bash
# 1. Uninstall editable version
uv pip uninstall mnemex

# 2. Install as UV tool
uv tool install git+https://github.com/simplemindedbot/mnemex.git

# 3. Update Claude Desktop config to just:
#    {"command": "mnemex"}
```

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

### Mnemex Memory Consolidation with Thresholds

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/quickstart.md

Advanced commands for memory consolidation, allowing users to specify cohesion thresholds for identifying and applying clusters. `--preview` shows potential consolidations, while `--apply` executes them.

```bash
# Find similar memory clusters
mnemex-consolidate --preview --cohesion-threshold 0.75

# Apply consolidation
mnemex-consolidate --apply --cohesion-threshold 0.80
```

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

### Consolidate Similar Mnemex Memories

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/quickstart.md

Commands to manage memory consolidation. `--preview` shows potential clusters without applying changes, while `--apply` executes the consolidation process to merge similar memories.

```bash
# Find clusters
mnemex-consolidate --preview

# Apply consolidation
mnemex-consolidate --apply
```

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

### Install Mnemex CLI Tool (uv)

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Installs the Mnemex command-line interface and its dependencies as isolated tools using the uv package manager. This method is recommended for end-users. Configuration is managed via `~/.config/mnemex/.env`.

```bash
# Install from GitHub
uv tool install git+https://github.com/simplemindedbot/mnemex.git

# Or from local directory
uv tool install .
```

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

### Quick Installation and Verification for Mnemex

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

This script demonstrates how to quickly install Mnemex from its Git repository and verify the installation. It also includes commands to run basic server statistics and perform a search operation, useful for quick testing on different platforms.

```bash
# Install and verify
uv tool install git+https://github.com/simplemindedbot/mnemex.git
mnemex --version

# Run basic tests
cd $(mktemp -d)
mnemex-maintenance stats
mnemex-search "test" --verbose
```

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

### Bash: Mnemex User Migration Guide

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/future_roadmap.md

Bash commands and instructions for existing Mnemex users to migrate from an editable installation to the new tool-based installation using `uv`. It includes steps for uninstallation, installation, and updating configurations.

```bash
# 1. Uninstall editable version
uv pip uninstall mnemex

# 2. Install as tool
uv tool install git+https://github.com/simplemindedbot/mnemex.git

# 3. Update Claude config to just: {"command": "mnemex"}
#    Remove the --directory, run, and PYTHONPATH settings
```

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

### Mnemex Maintenance and Garbage Collection CLI

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/quickstart.md

Utilizes Mnemex maintenance commands for various operations. Includes viewing statistics, compacting storage by removing deleted entries, generating a full report, and performing garbage collection to delete low-scoring memories.

```bash
# View statistics
mnemex-maintenance stats

# Compact storage (remove deleted entries)
mnemex-maintenance compact

# Full report
mnemex-maintenance report

# Preview what will be deleted
mnemex-gc --dry-run

# Delete low-scoring memories
mnemex-gc
```

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

### Build and Validate Mnemex Locally

Source: https://github.com/simplemindedbot/mnemex/blob/main/pypi.txt

Commands to install necessary build tools and then build and validate the Mnemex package locally before publishing. This ensures the distribution files are created correctly.

```bash
python -m pip install --upgrade build twine
python -m build
twine check dist/*
```

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

### Verify Mnemex Installation Commands

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/installation.md

Commands to verify that the Mnemex installation was successful and that its core CLI commands are accessible in the system's PATH. This helps confirm that the installation process completed without errors.

```bash
mnemex --version
mnemex-search --help
mnemex-maintenance --help
```

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

### Mnemex Configuration File Example

Source: https://github.com/simplemindedbot/mnemex/blob/main/README.md

Example configuration settings for Mnemex, including storage paths, decay model parameters, and thresholds. These are typically set in a .env file.

```bash
# Storage
MNEMEX_STORAGE_PATH=~/.config/mnemex/jsonl

# Decay model (power_law | exponential | two_component)
MNEMEX_DECAY_MODEL=power_law

# Power-law parameters (default model)
MNEMEX_PL_ALPHA=1.1
MNEMEX_PL_HALFLIFE_DAYS=3.0

# Exponential (if selected)
# MNEMEX_DECAY_LAMBDA=2.673e-6  # 3-day half-life

# Two-component (if selected)
# MNEMEX_TC_LAMBDA_FAST=1.603e-5  # ~12h
# MNEMEX_TC_LAMBDA_SLOW=1.147e-6  # ~7d
# MNEMEX_TC_WEIGHT_FAST=0.7

# Common parameters
MNEMEX_DECAY_LAMBDA=2.673e-6
MNEMEX_DECAY_BETA=0.6

# Thresholds
MNEMEX_FORGET_THRESHOLD=0.05
MNEMEX_PROMOTE_THRESHOLD=0.65

# Long-term memory (optional)
LTM_VAULT_PATH=~/Documents/Obsidian/Vault
```

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

### Mnemex Knowledge Graph Interaction (Python)

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/quickstart.md

Python code snippets for interacting with Mnemex's knowledge graph. Demonstrates creating explicit relations between memories and querying the graph to retrieve related information.

```python
# Create explicit relations
create_relation(
    from_id="mem_project_xyz",
    to_id="mem_decision_sqlalchemy",
    relation_type="has_decision"
)

# Query the graph
read_graph()  # Get entire graph
open_memories(["mem_project_xyz"])  # Get memory with relations
```

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

### View Stored Mnemex Memories and Statistics

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/quickstart.md

Provides commands to search all stored memories by keyword, view storage statistics, and display the raw JSONL content of memories. Useful for inspecting and debugging stored data.

```bash
# Search all memories
mnemex-search "TypeScript"

# View storage statistics
mnemex-maintenance stats

# See raw JSONL storage
cat ~/.config/mnemex/jsonl/memories.jsonl
```

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

### Mnemex Maintenance CLI Commands

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Demonstrates how to use the Mnemex maintenance command-line interface (CLI) for checking storage statistics and compacting JSONL files. It includes an example of specifying a custom storage path.

```bash
# Show JSONL storage stats (active counts, file sizes, compaction hints)
mnemex-maintenance stats

# Compact JSONL (rewrite files without tombstones/duplicates)
mnemex-maintenance compact

# With explicit path
mnemex-maintenance --storage-path ~/.config/mnemex/jsonl stats
```

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

### MCP Configuration for Mnemex (Claude Desktop - macOS)

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Configures Mnemex as an MCP server for Claude Desktop on macOS. This JSON snippet specifies the command to run Mnemex, with different configurations for UV tool installs and development setups.

```json
{
  "mcpServers": {
    "mnemex": {
      "command": "mnemex"
    }
  }
}
```

```json
{
  "mcpServers": {
    "mnemex": {
      "command": "uv",
      "args": ["--directory", "/path/to/mnemex", "run", "mnemex"],
      "env": {"PYTHONPATH": "/path/to/mnemex/src"}
    }
  }
}
```

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

### Install Mnemex CLI Tool

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/index.md

Installs the Mnemex command-line interface tool using the 'uv tool install' command. This is the recommended method for installation and ensures the latest version is fetched directly from the GitHub repository.

```bash
# Recommended: UV tool install
uv tool install git+https://github.com/simplemindedbot/mnemex.git
```

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

### Mnemex .env Configuration Example

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/configuration.md

Example of a Mnemex environment variables file (~/.config/mnemex/.env) to configure storage, decay models, thresholds, LTM, and Git backups.

```bash
# ============================================
# Storage Configuration
# ============================================

# Where short-term memories are stored (JSONL format)
MNEMEX_STORAGE_PATH=~/.config/mnemex/jsonl

# ============================================
# Decay Model Configuration
# ============================================

# Decay model: power_law | exponential | two_component
MNEMEX_DECAY_MODEL=power_law

# Power-law model parameters
MNEMEX_PL_ALPHA=1.1                # Power exponent (higher = faster decay)
MNEMEX_PL_HALFLIFE_DAYS=3.0       # Half-life in days

# Exponential model parameters (if MNEMEX_DECAY_MODEL=exponential)
# MNEMEX_DECAY_LAMBDA=2.673e-6     # Decay constant

# Two-component model parameters (if MNEMEX_DECAY_MODEL=two_component)
# MNEMEX_TC_LAMBDA_FAST=1.603e-5   # Fast decay constant
# MNEMEX_TC_LAMBDA_SLOW=1.147e-6   # Slow decay constant
# MNEMEX_TC_WEIGHT_FAST=0.7        # Weight for fast component

# Use count exponent (affects reinforcement)
MNEMEX_DECAY_BETA=0.6

# ============================================
# Thresholds
# ============================================

# Forget threshold: delete memories with score < this
MNEMEX_FORGET_THRESHOLD=0.05

# Promote threshold: move to LTM if score >= this
MNEMEX_PROMOTE_THRESHOLD=0.65

# ============================================
# Long-Term Memory (LTM)
# ============================================

# Obsidian vault path (for permanent storage)
LTM_VAULT_PATH=~/Documents/Obsidian/Vault

# LTM index path (for fast search)
LTM_INDEX_PATH=~/.config/mnemex/ltm_index.jsonl

# ============================================
# Git Backups
# ============================================

# Auto-commit changes to git
GIT_AUTO_COMMIT=true

# Commit interval in seconds (3600 = 1 hour)
GIT_COMMIT_INTERVAL=3600

# ============================================
# Embeddings (Optional)
# ============================================

# Enable semantic search with embeddings
MNEMEX_ENABLE_EMBEDDINGS=false

# Embedding model (if enabled)
MNEMEX_EMBED_MODEL=all-MiniLM-L6-v2

```

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

### Manual PyPI Upload using Twine

Source: https://github.com/simplemindedbot/mnemex/blob/main/pypi.txt

Instructions for manually uploading the built distribution files to PyPI using the twine command-line tool. Requires setting environment variables for authentication.

```bash
export TWINE_USERNAME="__token__"
export TWINE_PASSWORD="pypi-<your-token>"
twine upload dist/*
```

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

### Install and Verify Mnemex

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

Installs project dependencies using 'uv sync' and verifies the installation by running a Python script that imports the 'mnemex' package.

```bash
uv sync --all-extras

uv run python -c "import mnemex; print('Mnemex installed successfully!')"
```

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

### Troubleshooting Mnemex Dependencies

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Bash command to list installed Python packages and filter for those related to 'mcp', useful for checking Mnemex dependencies.

```bash
pip list | grep mcp
```

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

### Mnemex Installation with UV Tool

Source: https://github.com/simplemindedbot/mnemex/blob/main/README.md

Installs the Mnemex project and its CLI commands as isolated tools using the UV tool installer. This is the recommended method for installing Mnemex.

```bash
# Install from GitHub (recommended)
uv tool install git+https://github.com/simplemindedbot/mnemex.git

# Or install from local directory (for development)
uv tool install .
```

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

### Mnemex Promotion Workflow with Basic Memory

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Illustrates the JSON configuration for promoting memories with Mnemex. It shows how to enable auto-detection and perform a dry run before actual promotion, and how to list new notes in the vault.

```json
# 1. Auto-detect promotion candidates
{
  "auto_detect": true,
  "dry_run": true
}

# 3. Promote
{
  "auto_detect": true,
  "dry_run": false
}
```

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

### Configure Mnemex Environment

Source: https://github.com/simplemindedbot/mnemex/blob/main/CONTRIBUTING.md

Copies the example environment file and provides instructions for editing it, including macOS-specific path configurations.

```bash
# Copy example config
cp .env.example .env

# Edit with your preferred editor
nano .env
# or
open -e .env  # TextEdit

# macOS-specific config (~/.config/mnemex/.env or project .env):
# Standard macOS paths
MNEMEX_STORAGE_PATH=~/.config/mnemex/jsonl

# Optional: LTM vault path
LTM_VAULT_PATH=~/Documents/Obsidian/Vault
```

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

### Configure Mnemex Environment Variables

Source: https://github.com/simplemindedbot/mnemex/blob/main/CONTRIBUTING.md

Copies the example environment file and provides instructions for editing it. It also shows example configurations for Windows and Linux, including storage paths and optional LTM vault paths.

```powershell
# Copy example config
copy .env.example .env

# Edit .env with your preferred text editor
notepad .env

# Windows-specific config (~/.config/mnemex/.env or project .env):
# Use Windows paths with forward slashes or escaped backslashes
MNEMEX_STORAGE_PATH=C:/Users/YourUsername/.config/mnemex/jsonl
# Or with escaped backslashes
# MNEMEX_STORAGE_PATH=C:\Users\YourUsername\.config\mnemex\jsonl

# Optional: LTM vault path
LTM_VAULT_PATH=C:/Users/YourUsername/Documents/Obsidian/Vault
```

```bash
# Copy example config
cp .env.example .env

# Edit with your preferred editor
nano .env
# or
vim .env
# or
code .env  # VS Code

# Linux-specific config (~/.config/mnemex/.env or project .env):
# Standard XDG paths
MNEMEX_STORAGE_PATH=~/.config/mnemex/jsonl

# Optional: LTM vault path
LTM_VAULT_PATH=~/Documents/Obsidian/Vault

# Decay parameters
MNEMEX_DECAY_MODEL=power_law
MNEMEX_PL_ALPHA=1.1
MNEMEX_PL_HALFLIFE_DAYS=3.0
MNEMEX_DECAY_BETA=0.6

# Thresholds
MNEMEX_FORGET_THRESHOLD=0.05
MNEMEX_PROMOTE_THRESHOLD=0.65
```

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

### MCP Configuration for Mnemex (VSCode)

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Sets up Mnemex as an MCP server within VSCode using the MCP extension. It provides JSON configurations for both UV tool installations and development workflows, specifying the command and associated arguments or environment variables.

```json
{
  "mcp.servers": {
    "mnemex": {
      "command": "mnemex"
    }
  }
}
```

```json
{
  "mcp.servers": {
    "mnemex": {
      "command": "uv",
      "args": ["--directory", "${workspaceFolder}", "run", "mnemex"],
      "env": {"PYTHONPATH": "${workspaceFolder}/src"}
    }
  }
}
```

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

### Install Embeddings Support for Mnemex

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Pip command to install the 'sentence-transformers' library, which is required for Mnemex to use embeddings.

```bash
pip install sentence-transformers
```

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

### MCP Configuration for Mnemex (Claude Desktop - Windows)

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Configures Mnemex as an MCP server for Claude Desktop on Windows. This JSON snippet provides the necessary configuration for both UV tool installs and development environments, including command, arguments, and environment variables.

```json
{
  "mcpServers": {
    "mnemex": {
      "command": "mnemex"
    }
  }
}
```

```json
{
  "mcpServers": {
    "mnemex": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\mnemex", "run", "mnemex"],
      "env": {"PYTHONPATH": "C:\\path\\to\\mnemex\\src"}
    }
  }
}
```

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

### Install Git and Verify Version (Windows PowerShell)

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

This snippet demonstrates how to verify the Git installation on Windows using PowerShell. It assumes Git has been downloaded and installed from git-scm.com.

```powershell
# Verify installation
git --version
```

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

### Tag and Push for CI/CD Deployment

Source: https://github.com/simplemindedbot/mnemex/blob/main/pypi.txt

Commands to create a Git tag and push it to the repository, which triggers the CI/CD workflow to publish the package to PyPI. Assumes a tag pattern like 'v0.*'.

```bash
git tag v0.4.1
git push origin v0.4.1
```

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

### Install Mnemex CLI Tool

Source: https://github.com/simplemindedbot/mnemex/blob/main/ELI5.md

Installs Mnemex and its associated CLI commands using the 'uv tool install' command. This command fetches the project from a Git repository and sets up the tool and its dependencies.

```bash
# Install Mnemex as a UV tool
uv tool install git+https://github.com/simplemindedbot/mnemex.git
```

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

### Pre-commit Hook Installation and Usage

Source: https://github.com/simplemindedbot/mnemex/blob/main/CONTRIBUTING.md

Instructions for installing and using pre-commit hooks to ensure code quality before committing. This includes global installation, enabling hooks in the repository, running all hooks, and executing individual hooks like Ruff and Mypy.

```bash
pipx install pre-commit  # or: pip install pre-commit

pre-commit install

pre-commit run --all-files

# Run ruff only
pre-commit run ruff --all-files

# Run mypy on src via pre-commit
pre-commit run mypy --all-files
```

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

### Minimal Claude Desktop Configuration

Source: https://github.com/simplemindedbot/mnemex/blob/main/examples/README.md

Provides the minimal JSON configuration required for Claude Desktop to run Mnemex after installation via `uv tool install`. This configuration should be placed at `~/Library/Application Support/Claude/claude_desktop_config.json`.

```json
{
  "command": "mnemex"
}
```

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

### Configure Mnemex Custom Decay Parameters

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/quickstart.md

Shows how to adjust memory decay rates by editing the Mnemex environment file (`~/.config/mnemex/.env`). Parameters like `MNEMEX_PL_HALFLIFE_DAYS` control how long memories persist.

```bash
# Slower decay (memories last longer)
MNEMEX_PL_HALFLIFE_DAYS=7.0

# Faster decay (more aggressive forgetting)
MNEMEX_PL_HALFLIFE_DAYS=1.0
```

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

### Install Homebrew on macOS

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

Provides the command to install Homebrew, the package manager for macOS, if it is not already installed.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

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

### Configure Mnemex Environment Variables

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

Copies the example environment file and provides instructions on how to edit it for local configuration. It highlights Windows-specific path formats and common Linux/macOS paths.

```powershell
# Copy example config
copy .env.example .env

# Edit .env with your preferred text editor
notepad .env

# Windows-specific config (`~/.config/mnemex/.env` or project `.env`):
# Use Windows paths with forward slashes or escaped backslashes
MNEMEX_STORAGE_PATH=C:/Users/YourUsername/.config/mnemex/jsonl
# Or with escaped backslashes
# MNEMEX_STORAGE_PATH=C:\\Users\\YourUsername\\.config\\mnemex\\jsonl

# Optional: LTM vault path
LTM_VAULT_PATH=C:/Users/YourUsername/Documents/Obsidian/Vault
```

```bash
# Copy example config
cp .env.example .env

# Edit with your preferred editor
nano .env
# or
vim .env
# or
code .env  # VS Code

# Linux-specific config (`~/.config/mnemex/.env` or project `.env`):
# Standard XDG paths
MNEMEX_STORAGE_PATH=~/.config/mnemex/jsonl

# Optional: LTM vault path
LTM_VAULT_PATH=~/Documents/Obsidian/Vault

# Decay parameters
MNEMEX_DECAY_MODEL=power_law
MNEMEX_PL_ALPHA=1.1
MNEMEX_PL_HALFLIFE_DAYS=3.0
MNEMEX_DECAY_BETA=0.6

# Thresholds
MNEMEX_FORGET_THRESHOLD=0.05
MNEMEX_PROMOTE_THRESHOLD=0.65
```

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

### Install Python and Git on macOS

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

Installs Python (version 3.10) and Git on macOS using Homebrew, and verifies their installations.

```bash
brew install python@3.10 git

# Verify installation
python3 --version
git --version
```

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

### Install Python and Git on Linux

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

Provides commands for installing Python (specifically 3.10), pip, and Git on Ubuntu/Debian, Fedora/RHEL, and Arch Linux distributions.

```bash
# Ubuntu/Debian:
sudo apt update
sudo apt install python3.10 python3.10-venv python3-pip git

# Verify installation
python3 --version

# Fedora/RHEL:
sudo dnf install python3.10 python3-pip git

# Verify installation
python3 --version

# Arch Linux:
sudo pacman -S python python-pip git

# Verify installation
python --version
```

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

### Mnemex Editable Install for Development

Source: https://github.com/simplemindedbot/mnemex/blob/main/README.md

Installs Mnemex in an editable mode for development purposes. This allows for direct code changes to be reflected without reinstallation. Requires cloning the repository first.

```bash
# Clone and install in editable mode
git clone https://github.com/simplemindedbot/mnemex.git
cd mnemex
uv pip install -e ".[dev]"
```

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

### Install Dependencies with UV

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

Installs project dependencies, including development dependencies, using the `uv` package manager. This command should be run from the project's root directory.

```powershell
# Install dependencies (including dev dependencies)
uv sync --all-extras

# Verify installation
uv run python -c "import mnemex; print('Mnemex installed successfully!')"
```

```bash
# Install dependencies (including dev dependencies)
uv sync --all-extras

# Verify installation
uv run python -c "import mnemex; print('Mnemex installed successfully!')"
```

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

### Install UV Package Manager on macOS using Homebrew

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

Installs the `uv` package manager on macOS using Homebrew.

```bash
brew install uv
```

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

### Install Python and Verify Version (Windows PowerShell)

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

This snippet shows how to verify the Python installation on Windows using PowerShell. It assumes Python has already been installed and added to the system's PATH environment variable.

```powershell
# Verify installation
python --version
# Should show Python 3.10 or higher
```

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

### Mnemex Server Configuration (.env file)

Source: https://github.com/simplemindedbot/mnemex/blob/main/examples/README.md

An example of a `.env` file used to configure Mnemex server settings. This includes storage paths, decay model parameters, and various thresholds for memory management. It also allows setting the log level.

```bash
# Storage paths
MNEMEX_STORAGE_PATH=~/.config/mnemex/jsonl
LTM_VAULT_PATH=~/Documents/Obsidian/Vault

# Decay model and parameters
MNEMEX_DECAY_MODEL=power_law
MNEMEX_PL_ALPHA=1.1
MNEMEX_PL_HALFLIFE_DAYS=3.0
MNEMEX_DECAY_BETA=0.6

# Thresholds
MNEMEX_FORGET_THRESHOLD=0.05
MNEMEX_PROMOTE_THRESHOLD=0.65

# Optional
MNEMEX_ENABLE_EMBEDDINGS=false
LOG_LEVEL=INFO
```

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

### Install UV Package Manager on Linux/macOS

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

Details two methods for installing the `uv` package manager: using `curl` with a script (recommended) or using `pip`. Includes instructions for adding `uv` to the PATH.

```bash
# Using curl (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv

# Add to PATH (if needed)
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify installation
uv --version
```

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

### Configure PyPI Metadata (pyproject.toml)

Source: https://github.com/simplemindedbot/mnemex/blob/main/pypi.txt

This snippet shows the essential metadata for PyPI packaging within the pyproject.toml file. It includes project name, version, description, readme, license, authors, keywords, classifiers, and build exclusions.

```toml
[project]
  name = "mnemex"
  version = "0.4.0"
  description = "A personal knowledge management system."
  readme = "README.md"
  license = "MIT"
  authors = [
    { name="Your Name", email="your.email@example.com" },
  ]
  keywords = ["knowledge management", "notes", "personal", "mnemex"]
  classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Developers",
    "Topic :: Software Development :: Libraries :: Python Modules",
  ]
  urls = {
    "Homepage" = "https://github.com/user/mnemex",
    "Repository" = "https://github.com/user/mnemex",
    "Documentation" = "https://user.github.io/mnemex",
    "Issue Tracker" = "https://github.com/user/mnemex/issues",
  }

[tool.hatch.build]
  exclude = ["marketing/**"]

```

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

### Mnemex Configuration File Example

Source: https://github.com/simplemindedbot/mnemex/blob/main/ELI5.md

An example of a Mnemex configuration file (`.env`) that allows customization of storage paths, memory half-life, and permanent storage locations. These settings control how Mnemex manages and stores conversation memories.

```bash
# Where to store memories (default: ~/.config/mnemex/jsonl)
MNEMEX_STORAGE_PATH=~/.config/mnemex/jsonl

# How fast memories fade (3 days = default)
MNEMEX_PL_HALFLIFE_DAYS=3.0

# Where to save important memories permanently (optional)
LTM_VAULT_PATH=~/Documents/Obsidian/MyVault
```

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

### Install UV Package Manager (Windows PowerShell)

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

This snippet provides instructions for installing the UV package manager on Windows using PowerShell. It includes both a recommended one-liner command and an alternative using pip.

```powershell
# Using PowerShell (recommended)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or using pip
pip install uv

# Verify installation
uv --version
```

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

### Backup Mnemex JSONL Storage

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Provides bash commands for creating simple, timestamped, and automated daily backups of Mnemex memory and relation files. It also includes instructions for scheduling backups using cron.

```bash
# Simple backup
cp ~/.config/mnemex/jsonl/memories.jsonl ~/.config/mnemex/backups/memories.jsonl.backup
cp ~/.config/mnemex/jsonl/relations.jsonl ~/.config/mnemex/backups/relations.jsonl.backup

# Timestamped backup
cp ~/.config/mnemex/jsonl/memories.jsonl ~/.config/mnemex/backups/memories.jsonl.$(date +%Y%m%d)
cp ~/.config/mnemex/jsonl/relations.jsonl ~/.config/mnemex/backups/relations.jsonl.$(date +%Y%m%d)

# Automated daily backup (cron)
0 2 * * * cp ~/.config/mnemex/jsonl/memories.jsonl ~/.config/mnemex/backups/memories.jsonl.$(date +%Y%m%d) && cp ~/.config/mnemex/jsonl/relations.jsonl ~/.config/mnemex/backups/relations.jsonl.$(date +%Y%m%d)
```

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

### Configure Mnemex Environment Variables

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

Copies the example environment file and provides commands to edit it. Includes macOS-specific paths for storage and LTM vault.

```bash
# Copy example config
cp .env.example .env

# Edit with your preferred editor
nano .env
# or
open -e .env  # TextEdit

# macOS-specific config (~/.config/mnemex/.env or project .env):

# Standard macOS paths
MNEMEX_STORAGE_PATH=~/.config/mnemex/jsonl

# Optional: LTM vault path
LTM_VAULT_PATH=~/Documents/Obsidian/Vault
```

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

### Install UV Package Manager on Linux/macOS

Source: https://github.com/simplemindedbot/mnemex/blob/main/CONTRIBUTING.md

Installs the 'uv' package manager using a recommended curl script or pip. Includes instructions for adding 'uv' to the system's PATH.

```bash
# Using curl (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using pip
pip install uv

# Add to PATH (if needed)
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify installation
uv --version
```

```bash
# Using Homebrew
brew install uv
```

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

### Bash Environment Variables for STM Tuning

Source: https://github.com/simplemindedbot/mnemex/blob/main/examples/usage_example.md

Bash shell configurations for tuning Short-Term Memory (STM) decay and promotion parameters. These examples illustrate adjusting decay lambda for different half-lives, setting forget thresholds, and defining the use count for promoting memories, tailored for fast-paced development, research, or high-volume scenarios.

```bash
STM_DECAY_LAMBDA=8.02e-6      # 1-day half-life
STM_FORGET_THRESHOLD=0.03
STM_PROMOTE_USE_COUNT=3
```

```bash
STM_DECAY_LAMBDA=1.145e-6     # 7-day half-life
STM_FORGET_THRESHOLD=0.08
STM_PROMOTE_USE_COUNT=7
```

```bash
STM_FORGET_THRESHOLD=0.10
STM_PROMOTE_THRESHOLD=0.70    # Higher bar for promotion
```

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

### Unified Search with mnemex-search CLI

Source: https://github.com/simplemindedbot/mnemex/blob/main/README.md

An example of using the mnemex-search command-line tool to perform a unified search across STM and LTM. It allows specifying search terms, tags, and limits for the results, with a verbose output option.

```bash
mnemex-search "typescript preferences" --tags preferences --limit 5 --verbose
```

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

### Mnemex Test Writing Guidelines - Fixtures

Source: https://github.com/simplemindedbot/mnemex/blob/main/CONTRIBUTING.md

Demonstrates using pytest fixtures in Python for common test setup, such as creating sample data.

```python
@pytest.fixture
def sample_memories():
    """Create sample memories for testing."""
    return [
        Memory(id="mem-1", content="Test content 1"),
        Memory(id="mem-2", content="Test content 2"),
    ]

def test_something(sample_memories):
    # Use the fixture
    assert len(sample_memories) == 2
```

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

### Running Mnemex Tests with pytest

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Executes the test suite for the Mnemex project using pytest. This includes options for running all tests, tests with coverage reporting, specific test files, and verbose output.

```bash
# Run all tests
pytest

# With coverage
pytest --cov=mnemex --cov-report=html

# Run specific test file
pytest tests/test_decay.py

# Run with verbose output
pytest -v
```

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

### Install Mnemex with uv tool (Shell)

Source: https://github.com/simplemindedbot/mnemex/blob/main/CONTRIBUTING.md

Command to install Mnemex using the uv tool. This is a common installation method mentioned in the bug report template.

```shell
uv tool install mnemex
```

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

### Topic Tracking with Mnemex (Python)

Source: https://github.com/simplemindedbot/mnemex/blob/main/examples/usage_example.md

Demonstrates topic tracking over time using Mnemex. It involves saving initial information, updating with progress and linking to previous entries using `touch_memory`, and finally searching across related memories within a specified timeframe.

```python
# Day 1: Initial information
save_memory({
  "content": "Started working on user authentication feature",
  "tags": ["auth", "feature"]
})

# Day 2: Progress update
save_memory({
  "content": "Implemented JWT token generation and validation",
  "tags": ["auth", "jwt"]
})
touch_memory("previous-auth-memory-id")  # Link to previous

# Day 5: Completion
save_memory({
  "content": "Auth feature complete, ready for testing",
  "tags": ["auth", "testing"]
})
touch_memory("initial-auth-memory-id")
touch_memory("jwt-memory-id")

# Week later: Search all auth memories
search_memory({
  "tags": ["auth"],
  "window_days": 14
})
```

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

### Python: Consolidate Memories Usage Examples

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/future_roadmap.md

Demonstrates how to use the `consolidate_memories` function in Python for memory consolidation. It shows examples for both previewing and applying consolidation, including setting auto-detect and cohesion threshold parameters. No specific dependencies are mentioned other than the function itself.

```python
# Auto-detect and preview
consolidate_memories(auto_detect=True, mode="preview", cohesion_threshold=0.75)

# Apply consolidation
consolidate_memories(auto_detect=True, mode="apply", cohesion_threshold=0.80)
```

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

### Example Pull Request Description

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

Provides a template for writing a comprehensive pull request description. It emphasizes clarity on the 'What', 'Why', and 'How' of the changes, including testing and breaking changes.

```markdown
## Description
Implement spaced repetition scheduling for memory review.

## Motivation
Users requested a way to get reminders for reviewing important memories
before they decay too much.

## Changes
- Add `calculate_next_review()` function to core/scheduling.py
- Add `get_review_queue()` MCP tool
- Add tests in tests/test_scheduling.py (100% coverage)
- Update README.md with usage examples

## Testing
- All existing tests pass
- Added 12 new tests for scheduling logic
- Tested manually with 100+ memories

## Breaking Changes
None - this is a new feature with no API changes.
```

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

### Mnemex Automatic Promotion Workflow (JSON)

Source: https://github.com/simplemindedbot/mnemex/blob/main/examples/usage_example.md

Automates the promotion of memories based on usage criteria. The first step performs a dry run to identify candidates, detailing reasons for promotion. If the candidates are approved, the second step executes the promotion without a dry run.

```json
// Step 1: Find promotion candidates
{
  "auto_detect": true,
  "dry_run": true
}

// Response shows candidates:
{
  "success": true,
  "candidates_found": 5,
  "candidates": [
    {
      "id": "mem-1",
      "content_preview": "Project requirements: must support...",
      "reason": "High use count (8 >= 5) within 14 days",
      "score": 0.7234,
      "use_count": 8,
      "age_days": 10.5
    }
  ]
}

// Step 2: Promote if candidates look good
{
  "auto_detect": true,
  "dry_run": false
}
```

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

### Mnemex Installation Dependency for Embeddings

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/configuration.md

Command to install the 'sentence-transformers' Python package using 'uv', which is required for enabling semantic search with embeddings in Mnemex.

```bash
uv pip install sentence-transformers
```

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

### Write Mnemex Pytest Tests with Fixtures and Parametrization

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

Illustrates writing Python tests using pytest, including using fixtures for setup, writing descriptive test names, testing edge cases, and using `parametrize` for multiple test cases.

```python
def test_merge_content_preserves_unique_information():
    """Test that content merging keeps unique info from all memories."""
    # Test implementation

@pytest.fixture
def sample_memories():
    """Create sample memories for testing."""
    return [
        Memory(id="mem-1", content="Test content 1"),
        Memory(id="mem-2", content="Test content 2"),
    ]

def test_something(sample_memories):
    # Use the fixture
    assert len(sample_memories) == 2

def test_merge_content_empty():
    """Test merging with empty list."""
    result = merge_content_smart([])
    assert result == ""

def test_merge_content_single():
    """Test merging with single memory."""
    memories = [Memory(id="1", content="Single")]
    result = merge_content_smart(memories)
    assert result == "Single"

@pytest.mark.parametrize("use_count,expected", [
    (1, 1.0),
    (5, 2.6),
    (10, 4.0),
])
def test_use_count_boost(use_count, expected):
    boost = calculate_boost(use_count)
    assert abs(boost - expected) < 0.1
```

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

### Decision Documentation with Mnemex (Python)

Source: https://github.com/simplemindedbot/mnemex/blob/main/examples/usage_example.md

Illustrates documenting important decisions using Mnemex. A decision is saved with relevant tags and context. Later, it can be searched using keywords and tags. If the decision remains relevant, it can be promoted, even forcefully if needed.

```python
# Save decision
save_memory({
  "content": "Decided to use PostgreSQL for analytics data due to better JSON query support",
  "tags": ["decision", "database", "analytics"],
  "source": "architecture review",
  "context": "Compared PostgreSQL vs MongoDB for analytics workload"
})

# Later: Review decision
search_memory({
  "query": "database decision",
  "tags": ["decision", "database"]
})

# If still relevant after multiple accesses: promote
promote_memory({
  "memory_id": "decision-memory-id",
  "force": true  # Even if doesn't meet auto-criteria
})
```

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

### Google-Style Docstrings in Python

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/CONTRIBUTING.md

Illustrates the use of Google-style docstrings for Python functions. This includes sections for Args, Returns, and Examples, promoting clear and consistent documentation.

```python
def merge_content_smart(memories: list[Memory]) -> str:
    """
    Intelligently merge content from multiple memories.

    Strategy:
    - If very similar (duplicates), keep the longest/most detailed version
    - If related but distinct, combine with clear separation
    - Preserve unique information from each memory

    Args:
        memories: List of memories to merge

    Returns:
        Merged content string

    Example:
        >>> memories = [Memory(id="1", content="Python is great")]
        >>> merge_content_smart(memories)
        'Python is great'
    """
    # Implementation
```

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

### List STM Notes in Obsidian Vault

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

A bash command to list the contents of the STM directory within an Obsidian vault, used after promoting memories to verify the creation of new Markdown notes.

```bash
ls ~/Documents/Obsidian/Vault/STM/
```

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

### Configure Memory Half-Life in .env (Bash)

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/quickstart.md

Adjusts the memory decay rate by increasing the `MNEMEX_PL_HALFLIFE_DAYS` variable in the `.env` file. This setting controls how long memories remain potent before decaying. The example shows increasing it from 3.0 to 7.0 days.

```bash
MNEMEX_PL_HALFLIFE_DAYS=7.0  # Increase from 3.0
```

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

### Check Mnemex Storage Path Existence

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Bash command to verify the existence and check permissions of the Mnemex JSONL storage directory.

```bash
ls -la ~/.config/mnemex/jsonl
```

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

### Mnemex Performance Tuning for Semantic Search

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Environment variables to configure Mnemex for semantic search performance by selecting different embedding models. Offers options for a lighter, more accurate model or a faster, less accurate one.

```bash
# Use lighter model
MNEMEX_EMBED_MODEL=all-MiniLM-L6-v2

# Or faster model (less accurate)
MNEMEX_EMBED_MODEL=paraphrase-MiniLM-L3-v2
```

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

### Mnemex Weekly Garbage Collection Configuration

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

JSON configuration object for performing weekly garbage collection in Mnemex, with options to disable dry runs and enable archiving.

```json
{
  "dry_run": false,
  "archive_instead": true
}
```

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

### Promote Memory using MCP Tool

Source: https://github.com/simplemindedbot/mnemex/blob/main/README.md

Examples of promoting a memory using the MCP tool. This includes an auto-detect dry run and promoting a specific memory to Obsidian. It also shows the request body format for promoting a memory as an MCP tool.

```json
{
  "auto_detect": true,
  "dry_run": true
}
```

```json
{
  "memory_id": "mem-123",
  "dry_run": false,
  "target": "obsidian"
}
```

```json
{
  "query": "typescript preferences",
  "tags": ["preferences"],
  "limit": 5,
  "verbose": true
}
```

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

### Mnemex Configuration: Standard Decay Profile

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Configures Mnemex with standard decay parameters, providing a balance for general use. This profile adjusts decay lambda for a 3-day half-life and sets default values for forget threshold, promote threshold, and use count.

```bash
# .env
MNEMEX_DECAY_LAMBDA=2.673e-6  # 3-day half-life
MNEMEX_FORGET_THRESHOLD=0.05
MNEMEX_PROMOTE_THRESHOLD=0.65
MNEMEX_PROMOTE_USE_COUNT=5
```

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

### Python Memory Strength Examples

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/scoring_algorithm.md

Demonstrates setting memory strength values in Python for different priorities, from critical to tentative. These values influence how memories are retained or forgotten.

```python
# Security credentials - critical
strength = 2.0

# User preferences - important
strength = 1.5

# Normal conversation context
strength = 1.0

# Tentative ideas, exploratory thoughts
strength = 0.5
```

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

### Python Context-Aware Tagging Example

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/prompts/memory_system_prompt.md

Illustrates the difference between system-centric and user-centric tagging strategies in Python. User-centric tagging focuses on reflecting the user's mental model, leading to more intuitive and effective memory retrieval.

```python
# Bad tagging (system-centric)
tags = ["data", "config", "string", "path"]

# Good tagging (user-centric)
tags = ["database", "credentials", "project-alpha", "security"]
```

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

### Capture Mnemex Server Logs

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

A bash command to capture Mnemex server logs written to stderr and simultaneously display them and save them to a file named 'server.log' in the Mnemex config directory.

```bash
mnemex 2>&1 | tee ~/.config/mnemex/server.log
```

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

### Mnemex Configuration: Fast Decay Profile

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Sets the Mnemex configuration for a 'Fast Decay' profile, suitable for information relevant for only a day or two. This involves adjusting decay lambda, forget threshold, promote threshold, and use count in the `.env` file.

```bash
# .env
MNEMEX_DECAY_LAMBDA=8.02e-6  # 1-day half-life
MNEMEX_FORGET_THRESHOLD=0.03
MNEMEX_PROMOTE_THRESHOLD=0.7
MNEMEX_PROMOTE_USE_COUNT=3
```

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

### Troubleshooting Python Version for Mnemex

Source: https://github.com/simplemindedbot/mnemex/blob/main/docs/deployment.md

Bash command to check the installed Python version, as Mnemex requires Python 3.10 or later.

```bash
python --version
```