claude-mnemos

claude-mnemos

Long-term memory for Claude Code. Sessions become structured per-project knowledge bases in Obsidian-compatible vaults.

Claude Code holds context only within one session. claude-mnemos stores every conversation as atomic markdown wiki pages in your vault, then injects the most relevant ones into the next session's system prompt — so Claude effectively remembers what you did before.

Status

0.0.1 — early development. Single-user, runs locally, no server-side anything. Not on PyPI yet — install from source.

Installing from a release (no terminal required)

Download the latest installer for your OS from github.com/DeveloperrOp/claude-mnemos/releases:

OS	File
Windows 10/11 (x64)	claude-mnemos-setup-x64.exe
macOS 11+ (Apple Silicon and Intel)	claude-mnemos.dmg
Linux x86_64	claude-mnemos-x86_64.AppImage

Windows

1. Double-click the .exe.
2. SmartScreen may say "Windows protected your PC" — click More info → Run anyway. We have not yet purchased a code-signing certificate; the warning is expected.
3. Accept the autostart checkbox (default on) — claude-mnemos will start with Windows.
4. Click Install. The dashboard opens automatically when setup finishes.

macOS

1. Open the .dmg and drag claude-mnemos to Applications.
2. The first launch will fail with "unidentified developer" — open System Settings → Privacy & Security → Open Anyway, or right-click the app and choose Open to bypass once.
3. The app lives in the menu bar (top-right). Click the icon to open the dashboard.

Linux

1. Make the AppImage executable: chmod +x claude-mnemos-x86_64.AppImage.
2. Run it: ./claude-mnemos-x86_64.AppImage.
3. Optional — integrate with your DE: ./claude-mnemos-x86_64.AppImage --integrate (linuxdeploy adds a desktop entry).

Uninstalling

• Windows: Settings → Apps → claude-mnemos → Uninstall. Removes the daemon, autostart entry, and Claude Code hooks.
• macOS: drag the app to Trash. To remove the LaunchAgent, run mnemos tray uninstall from terminal first (or just delete ~/Library/LaunchAgents/com.yarik.claude-mnemos.plist).
• Linux: delete the .AppImage. To remove the autostart entry, delete ~/.config/autostart/claude-mnemos.desktop.

Install

Recommended path uses pipx (industry-standard isolated installer for Python CLI tools). System-Python pip install -e . is documented as a fallback but not recommended — it produces dependency conflicts and orphan files over time.

Get the source

git clone https://github.com/<your-fork>/claude-mnemos.git
cd claude-mnemos

Install via pipx (recommended)

If you don't have pipx yet:

# Windows
py -3.12 -m pip install --user pipx
py -3.12 -m pipx ensurepath

# macOS / Linux
python3 -m pip install --user pipx
python3 -m pipx ensurepath

Open a new terminal so pipx is on PATH, then install mnemos editable:

pipx install --editable . --python 3.12

This puts mnemos in an isolated venv (~/pipx/venvs/claude-mnemos/ on Windows, ~/.local/share/pipx/venvs/claude-mnemos/ on Unix) and publishes three commands on your PATH: mnemos, mnemos-mcp, mnemos-tray.

To upgrade later: cd <path> && git pull && pipx reinstall claude-mnemos. To uninstall cleanly: pipx uninstall claude-mnemos.

Fallback: pip in your own venv

If you prefer manual venv management:

python3.12 -m venv .venv
source .venv/bin/activate          # macOS / Linux
.venv\Scripts\Activate.ps1         # Windows PowerShell
pip install -e .

You'll need to activate that venv every time before running mnemos commands. pipx avoids that step.

Avoid: pip install -e . directly into system Python. It works at first, but every future pip install <other-package> may conflict with mnemos's pinned deps; partial uninstalls leave orphan files behind.

Verify

mnemos --version
mnemos --help

You should see subcommands (project, daemon, tray, settings, ingest, lint, ontology, …).

Python requirement: 3.12+.

Quickstart

# 1. Authenticate Claude Code (uses your Pro/Max subscription — no separate API key needed)
claude login
claude -p "hi"            # smoke test

# 2. Create a project (registers a vault and CWD patterns)
mnemos project add my-project \
  --vault ~/code/my-project/.mnemos \
  --cwd-pattern "~/code/my-project/**"

# 3. Start the daemon (FastAPI on 127.0.0.1:5757)
mnemos daemon start

# 4. (Optional) Tray icon + autostart on every login
mnemos tray install

Then open http://localhost:5757/ — the dashboard is live.

Now run Claude Code in a folder covered by your CWD patterns. After you exit, the session JSONL gets ingested automatically into the vault. Re-launch Claude in the same folder, and the SessionStart hook injects the most relevant pages into the system prompt.

How it works