llama-memory

MCP-сервис памяти для llama-server с постоянной историей и семантической памятью на основе Postgres + PGVector.

Примечание: этот проект предназначен только для локального/демонстрационного использования. Не публикуйте его напрямую в интернет без дополнительной защиты (HTTPS, надлежащая аутентификация, резервное копирование).

Что делает

• Семантическая память: сохраняйте и извлекайте воспоминания по смыслу, а не только по ключевым словам.

• Мост бесед: LLM автоматически создаёт беседы; воспоминания связываются.

• Межсессионное припоминание: спросите «о чём мы говорили раньше?» и получите точные ответы.

• Протокол MCP: работает напрямую со встроенной поддержкой MCP в llama-server.

Related MCP server: engram

Требования

• Python 3.11 (рекомендуется Miniconda)

• PostgreSQL 16+ с расширением PGVector

• llama-server с флагом --jinja (требуется для вызова инструментов)

• nomic-embed-text, запущенный на llama-server (порт 8081 по умолчанию)

Установка

# Clone the repo
git clone https://github.com/noualit/llama-memory-local.git
cd llama-memory-local

# Create environment
conda create -n llama-memory python=3.11
conda activate llama-memory

# Install dependencies
pip install -e .

Конфигурация

Скопируйте .env.example в .env и отредактируйте:

cp .env.example .env

Пример:

# Database
DATABASE_URL="postgresql://postgres:yourpassword@localhost:5432/llamamem"

# Llama-server (LLM)
LLAMA_SERVER_BASE_URL="http://localhost:8080"

# Embedding model (nomic-embed-text via llama-server)
EMBEDDING_MODEL_URL="http://localhost:8081"

# Embedding model name (default: nomic-embed-text)
EMBEDDING_MODEL_NAME="nomic-embed-text"

# Service port
SERVICE_PORT=9001

Настройка базы данных

Создайте базу данных и выполните миграции:

psql -U postgres -c "CREATE DATABASE llamamem;"
alembic upgrade head

Приложение также автоматически создаёт базовую схему при запуске для удобства.

Запуск сервиса

# Using the script
.\scripts\run_server.ps1

# Or directly
python -m uvicorn app.main:app --host 0.0.0.0 --port 9001

Подключение к llama-server

Добавьте в конфигурацию MCP вашего llama-server:

{
  "mcpServers": {
    "llama-memory": {
      "url": "http://YOUR_SERVER_IP:9001/mcp"
    }
  }
}

Сервис должен быть доступен из llama-server. Используйте фактический IP-адрес, а не localhost, если они работают на разных машинах.

MCP-инструменты

Системный промпт

Вы можете:

• Получить рекомендуемый системный промпт из сервиса:

  • GET /system-prompt → возвращает обычный текст.

• Или вставьте эту минимальную версию в llama-server:

MEMORY WORKFLOW:
- At the start of each new conversation, call create_conversation with a short title.
- Use the conversation_id from create_conversation when calling save_memory.
- Before answering questions about past topics, call search_memories FIRST.
- When the user shares important information, save it with save_memory.
- If list_conversations has previous chats, check get_conversation_history for context.

Проверка состояния

curl http://localhost:9001/health

Возвращает статус БД, статус сервиса эмбеддингов и количество инструментов.

Архитектура

Высокоуровневая структура:

• app/main.py — приложение FastAPI, жизненный цикл, /system-prompt

• app/settings.py — настройки Pydantic из .env

• app/clients/embeddings.py — вызовы nomic-embed-text для векторов

• app/db/engine.py — пул соединений asyncpg (синглтон)

• app/db/schema.py — автоматическое создание таблиц при запуске

• app/mcp/endpoint.py — обработчики протокола MCP, ограничитель скорости

• app/mcp/tools/ — реализации отдельных инструментов

• migrations/ — миграции базы данных Alembic

Разработка

# Run tests
pytest tests/ -v

# Run with auto-reload
python -m uvicorn app.main:app --host 0.0.0.0 --port 9001 --reload

См. CONTRIBUTING.md с рекомендациями по внесению вклада.

Лицензия

MIT (см. файл LICENSE).