ContextKeep

Long-Term Memory for AI Agents

ContextKeep gives AI agents a persistent, searchable memory they can use across sessions. V2.1 adds SQLite, full-text search, user-editable categories, safer Docker defaults, and verified backup-first upgrades.

What's New | Safe Upgrade | Install | MCP Tools | Configuration | Docs

Features

• Persistent local memory for MCP-compatible agents.

• SQLite storage with FTS5 full-text search.

• User-editable categories instead of fixed tags.

• Multiple categories per memory.

• WebUI for browsing, editing, searching, exporting, and category management.

• Streamable HTTP MCP endpoint at /mcp, with SSE fallback for older clients.

• Docker Compose support with one default service for WebUI and MCP.

• Verified backup and restore helpers for bare-metal and Docker upgrades.

• Server identity checks through get_contextkeep_info.

Related MCP server: LumenCore

What's New In V2.1 Atlas

V2.1 is the first category-first ContextKeep release.

• list_all_memories has been removed.

• Agents now use list_categories and list_memories before retrieve_memory.

• tags are replaced by user-editable categories.

• Memories can belong to more than one category.

• V1 tags are preserved as legacy_tags migration metadata.

• Docker now runs WebUI and MCP together by default so both use the same SQLite database.

• get_contextkeep_info reports version, storage path, database ID, tool list, and migration status.

• Upgrade scripts create verified backups before continuing.

Older releases remain available through GitHub releases and tags. V2.1 is the recommended version for new installs and upgrades.

Safe Upgrade First

Before replacing an existing install, use the safe upgrade wrapper. It creates a backup, verifies the archive, checks SQLite/JSON integrity, and stops if anything looks wrong.

Bare-metal:

python scripts/upgrade_to_v2_1.py baremetal

Docker:

python scripts/upgrade_to_v2_1.py docker

V1 JSON migration:

python scripts/upgrade_to_v2_1.py baremetal --v1-source /path/to/old/data/memories

See docs/SAFE_UPGRADE.md for backup, restore, Docker volume, and rollback details.

Install

Fresh Bare-Metal Install

git clone https://github.com/mordang7/ContextKeep.git
cd ContextKeep
python -m venv .venv

Linux/macOS:

source .venv/bin/activate
pip install -r requirements.txt

Windows PowerShell:

.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

You can also run the installer:

python install.py

Fresh Docker Install

git clone https://github.com/mordang7/ContextKeep.git
cd ContextKeep
docker compose up -d --build

Default ports:

Run

Local MCP over stdio:

python server.py

Remote MCP over HTTP:

python server.py --transport http --host 0.0.0.0 --port 5100

WebUI:

python webui.py --host 0.0.0.0 --port 5000

Then open:

http://localhost:5000

MCP Tools

ContextKeep V2.1 exposes 16 tools:

Recommended retrieval flow:

list_categories -> list_memories -> retrieve_memory

Use search_memories for topic discovery, then retrieve the exact matching memory before relying on it.

MCP Client Configuration

Most clients that support streamable HTTP:

{
  "mcpServers": {
    "context-keep": {
      "url": "http://localhost:5100/mcp"
    }
  }
}

Antigravity IDE uses serverURL:

{
  "mcpServers": {
    "context-keep": {
      "serverURL": "http://localhost:5100/mcp"
    }
  }
}

SSE fallback:

{
  "mcpServers": {
    "context-keep": {
      "url": "http://localhost:5100/sse"
    }
  }
}

For a remote machine, replace localhost with the hostname or address of the machine running ContextKeep.

Do not keep an old SSH/stdin config active for the same context-keep server name. It may launch an older server that writes to a different database than the WebUI.

Verify The Right Server

After connecting a client, call get_contextkeep_info.

Expected V2.1 values:

• version: 2.1.0

• schema_version: 2

• storage_backend: sqlite

• storage_path: /app/data/contextkeep.db in Docker, or your configured local path

• V2.1 tool list including list_memories, list_categories, update_categories, and get_edit_history

If an agent stores a memory but the WebUI cannot see it, compare WebUI /api/info with MCP get_contextkeep_info. The database_id, storage_path, and memory count should match.

Backup And Restore

Create a verified bare-metal backup:

python scripts/backup_contextkeep.py baremetal --install-dir /path/to/contextkeep

Create a verified Docker backup:

python scripts/backup_contextkeep.py docker --volume <docker-volume-name>

Restore commands are written into every backup folder. The full guide is in docs/SAFE_UPGRADE.md.

If you use container auto-update software, keep an external backup routine. The safe upgrade scripts can verify backups before an upgrade, but unattended image replacement cannot ask you to confirm backup health.

Docs

• Safe Upgrade Guide

• V2.1 Release Notes

• Docker V2.1 Guide

• Client Configuration

• Migration Guide

• Upgrading From V1

• Directive Update Block

Changelog

V2.1 Atlas

• SQLite database with FTS5 search.

• User-editable categories with multi-category memory assignment.

• WebUI category management.

• V1 JSON migration with legacy tag preservation.

• One-container Docker default for shared WebUI/MCP database access.

• get_contextkeep_info identity checks.

• Verified backup and restore tooling.

• Updated MCP client examples for HTTP, Antigravity, and SSE fallback.

V1.3 Harbor

• Docker support.

• Modern Python packaging.

• New tools: delete_memory, get_memory_stats, export_memories.

• WebUI export.

• Packaging and code quality fixes.

V1.2 Obsidian Lab

• Memory directory tool.

• Obsidian Lab UI redesign.

• Calendar and memory count improvements.

V1.1

• Web dashboard.

• SSE transport support.

• Linux systemd service installer.

• Memory titles and timestamps.

V1.0

• Core MCP server with persistent JSON-backed memory.

• Local stdio and remote access patterns.

Contributing

Issues, feature ideas, and pull requests are welcome. If you build a client guide, migration recipe, or workflow pattern around ContextKeep, please share it.

V1.3 Community Contributors

Thank you to everyone who contributed to the Harbor release:

• @shuft opened the Docker support request.

• @Cyberdogs7 contributed the initial Docker and Docker Compose implementation.

• @frehov contributed Dockerfile, pyproject.toml, uv support, and packaging fixes.

• @thinkstylestudio supported the project through community advocacy.

Support

If ContextKeep saves you time, tokens, or context-window pain, support is appreciated.