mnemonic

Mnemonic

Organizational knowledge management system with semantic search and progressive depth layers.

Built in Go. Designed for Claude Code.

---

Quick Start (5 minutes)

For users who want to get up and running fast:

# 1. Start ChromaDB (if you don't have one already)
docker run -d --name chromadb -p 8000:8000 \
  -v chromadb_data:/chroma/chroma \
  -e IS_PERSISTENT=TRUE -e ANONYMIZED_TELEMETRY=FALSE \
  chromadb/chroma:latest

# 2. Install mnemonic (detects OS/arch automatically, creates config)
curl -fsSL https://raw.githubusercontent.com/marioser/mnemonic/main/scripts/install.sh | bash

# 3. Edit config if ChromaDB is remote
#    nano ~/.mnemonic/config.yaml

# 4. Verify
mnemonic status

# 5. Install Claude Code plugin
claude plugin marketplace add marioser/mnemonic
claude plugin install mnemonic@mnemonic

# 6. Restart Claude Code — done!

Alternative install methods:

# Via Go (requires Go 1.24+ and GOPATH in PATH)
go install github.com/marioser/mnemonic/cmd/mnemonic@latest

# Manual download (replace OS and ARCH)
# OS: linux, darwin  |  ARCH: amd64, arm64
curl -L https://github.com/marioser/mnemonic/releases/latest/download/mnemonic_0.1.0_linux_amd64.tar.gz | tar xz
sudo mv mnemonic /usr/local/bin/

After restarting Claude Code, mnemonic will:

• Inject the Knowledge Protocol at session start
• Provide 25 MCP tools for searching and saving knowledge
• Give contextual nudges when you mention clients, projects, or equipment

---

Step-by-Step Guide for New Users

Step 1: Set up ChromaDB

Mnemonic stores all knowledge in ChromaDB, a vector database. You need a running ChromaDB server.

Option A: Docker (easiest)

docker run -d \
  --name chromadb \
  -p 8000:8000 \
  -v chromadb_data:/chroma/chroma \
  -e IS_PERSISTENT=TRUE \
  -e ANONYMIZED_TELEMETRY=FALSE \
  chromadb/chroma:latest

Option B: Docker Compose

# docker-compose.yaml
services:
  chromadb:
    image: chromadb/chroma:latest
    ports:
      - "8000:8000"
    volumes:
      - chromadb_data:/chroma/chroma
    environment:
      IS_PERSISTENT: "TRUE"
      ANONYMIZED_TELEMETRY: "FALSE"
    restart: unless-stopped

volumes:
  chromadb_data:

docker compose up -d

Option C: Use an existing ChromaDB server

If your team already has a ChromaDB server (e.g., on a remote server or cloud), just note its IP and port for the config step.

Verify ChromaDB is running:

curl http://localhost:8000/api/v2/heartbeat
# {"nanosecond heartbeat":...}

Step 2: Install the mnemonic binary

You need the mnemonic binary in your system PATH.

Option A: Go install (requires Go 1.24+)

go install github.com/marioser/mnemonic/cmd/mnemonic@latest

Option B: Download pre-built binary

# macOS Apple Silicon (M1/M2/M3/M4)
curl -L https://github.com/marioser/mnemonic/releases/latest/download/mnemonic_darwin_arm64.tar.gz | tar xz
sudo cp mnemonic /usr/local/bin/

# macOS Intel
curl -L https://github.com/marioser/mnemonic/releases/latest/download/mnemonic_darwin_amd64.tar.gz | tar xz
sudo cp mnemonic /usr/local/bin/

# Linux x64
curl -L https://github.com/marioser/mnemonic/releases/latest/download/mnemonic_linux_amd64.tar.gz | tar xz
sudo cp mnemonic /usr/local/bin/

# Linux ARM
curl -L https://github.com/marioser/mnemonic/releases/latest/download/mnemonic_linux_arm64.tar.gz | tar xz
sudo cp mnemonic /usr/local/bin/

Option C: Build from source

git clone https://github.com/marioser/mnemonic.git
cd mnemonic
go build -o mnemonic ./cmd/mnemonic/
sudo cp mnemonic /usr/local/bin/

Verify installation:

mnemonic version
# mnemonic v0.1.0 (darwin/arm64)

Step 3: Configure mnemonic

Create a global config file. Mnemonic will use this from any project.

mkdir -p ~/.mnemonic
cat > ~/.mnemonic/config.yaml << 'EOF'
# ChromaDB connection
chromadb:
  host: "localhost"        # Change to your ChromaDB IP if remote
  port: 8000
  token: ""                # Bearer token if auth is enabled
  ssl: false
  collection_prefix: "mn"

# HTTP server (used by hooks)
server:
  port: 7438
  host: "127.0.0.1"

# Search defaults
search:
  default_results: 5
  min_similarity: 0.7

# Dolibarr ERP (optional — skip if you don't use Dolibarr)
dolibarr:
  url: ""                  # e.g. "https://your-dolibarr.com"
  api_key: ""              # Your DOLAPIKEY from Dolibarr user settings
  sync:
    batch_size: 100
    entities:
      customers: true
      projects: true
      proposals: true
      products: true

log:
  level: "info"
EOF

For project-specific config, create config/mnemonic.yaml in your project directory. This overrides the global config for that project.

Verify config:

mnemonic status

You should see: