Claude Code Memory

Local-first память для Claude Code

Лёгкая приватная память для Claude Code: ассистент сам сохраняет важные факты диалога, подхватывает их в начале каждой сессии и умеет искать по ним «по смыслу» — при этом эмбеддинги считаются локально (Ollama), наружу не уходит ничего лишнего.

Три кирпича:

1. Авто-память — папка markdown-файлов, по одному факту на файл + индекс MEMORY.md.
2. Stop-хук — перед завершением сессии модель сама решает, что записать в память.
3. Семантический поиск — локальный (Ollama + nomic-embed-text), доступен ассистенту

как MCP-инструмент semantic_search. Никакой внешней векторной БД: один Python-скрипт без зависимостей и тонкая MCP-обёртка.

Всё под macOS (под Linux отличаются только пути; Keychain не требуется).

---

Как устроена память

Память — это папка markdown-файлов (по умолчанию ~/claude-memory/). Правила:

• Один файл = один факт, имя — короткий kebab-case слаг.
• У каждого файла frontmatter с name, description и metadata.type.
• Индекс MEMORY.md — по строке-ссылке на каждый факт; его Claude Code подгружает

в контекст в начале сессии.

• Claude Code знает про папку через настройку autoMemoryDirectory в settings.json.

Типы фактов (metadata.type):

| type | что храним | |-------------|-----------------------------------------------------------------------| | user | кто пользователь: роль, экспертиза, предпочтения | | feedback | как ассистенту работать — правила, корректировки; всегда с «почему» | | project | текущие задачи/цели/ограничения, не выводимые из кода и git-истории | | reference | указатели на внешние ресурсы (URL, дашборды, доки) |

Пример файла памяти:

---
name: prefers-typescript-strict
description: Пользователь всегда хочет strict-режим TypeScript в новых проектах
metadata:
  type: feedback
---

Всегда включай `strict: true` в tsconfig для новых проектов.

**Почему:** ловит ошибки типов на этапе компиляции, пользователь на этом настаивает.
**Как применять:** при инициализации любого TS-проекта ставь strict без напоминания.

Строка в MEMORY.md: - [Заголовок](имя-файла.md) — короткий крючок

---

Установка

0. Зависимости

brew install jq          # для хука
brew install ollama      # или https://ollama.com
ollama serve &           # поднимется на 127.0.0.1:11434
ollama pull nomic-embed-text
mkdir -p ~/claude-memory
printf '# Memory index\n' > ~/claude-memory/MEMORY.md

1. Stop-хук авто-сохранения

Скопируй [hooks/memory-save-on-stop.sh](hooks/memory-save-on-stop.sh):

mkdir -p ~/.claude/hooks
cp hooks/memory-save-on-stop.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/memory-save-on-stop.sh

В ~/.claude/settings.json добавь (слей с существующими ключами, $USER замени на своё имя — echo $HOME покажет полный путь):

{
  "autoMemoryDirectory": "/Users//claude-memory",
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command",
        "command": "/Users//.claude/hooks/memory-save-on-stop.sh",
        "timeout": 30 } ] }
    ]
  }
}

Путь в command — абсолютный. Перезапусти Claude Code.

2. Семантический поиск

mkdir -p ~/semsearch
cp semsearch/semsearch.py semsearch/mcp_server.py ~/semsearch/
python3 ~/semsearch/semsearch.py reindex
python3 ~/semsearch/semsearch.py search "предпочтения пользователя по коду"

3. MCP-сервер в Claude Code

В ~/.claude.json внутрь mcpServers добавь (не перезаписывай файл целиком):

{
  "mcpServers": {
    "semsearch": {
      "type": "stdio",
      "command": "python3",
      "args": ["/Users//semsearch/mcp_server.py"]
    }
  }
}

Перезапусти Claude Code — появится инструмент semantic_search.

---

Использование

• Копится само: в конце сессий ассистент складывает новые факты в ~/claude-memory.
• Вспоминается в начале: MEMORY.md подгружается в контекст новой сессии.
• Ищется по смыслу: при большом объёме ассистент зовёт semantic_search.
• Периодически запускай python3 ~/semsearch/semsearch.py reindex, чтобы поиск видел

свежие факты (индекс не обновляется сам — при желании повесь на cron или SessionStart-хук).

Приватность

Хук и память — локальные файлы. Эмбеддинги считает локальный Ollama, индекс лежит на диске. Наружу уходит только то, что и обычно при работе с Claude Code.

Расширяемость

Движок сделан по источникам (ingest_memory в semsearch.py). Хочешь индексировать что-то ещё (заметки, доки, тикеты) — добавь свою ingest_*-функцию, возвращающую записи того же формата, и включи её в reindex.

Лицензия

MIT — см. [LICENSE](LICENSE).

Source & license

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

• Author: tak-ne-4estno
• Source: tak-ne-4estno/claude-code-memory
• License: MIT

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