🌟 Features

• ♾️ Infinite Context: Store unlimited project details, preferences, decisions, and snippets — no expiry, no size cap.
• 💰 Save Money & Tokens: Pull only the memories that matter, slashing context window usage and API costs.
• 🔌 Universal Compatibility: Works with any MCP-compliant client via Stdio (local) or SSE (remote/homelab).
• 🧭 Memory Index Protocol: A reliable two-step retrieval system — list_all_memories() → retrieve_memory() — so agents always find the right key, every time.
• 🖥️ Modern Web Dashboard: Manage your memories visually with Grid, List, and Calendar views in a sleek dark interface.
• 🔒 Privacy First: 100% local storage. Your data never touches an external server.
• 🔎 Smart Search: Keyword and semantic search across all memory content.
• 🐧 Linux Service: Runs silently in the background as a systemd service.
• 🐳 Docker Ready: One-command deployment with Docker Compose.
• ⬇️ Export & Backup: Export all memories as JSON via MCP tool or WebUI.

🆕 What's New in V1.3 — Harbor

🐳 Docker Support

The #1 community request. ContextKeep now ships with a Dockerfile and docker-compose.yml for one-command deployment:

docker compose up --build

That's it. MCP server on :5100, WebUI on :5000, with persistent storage via Docker volumes.

📦 Modern Python Packaging

• pyproject.toml — canonical dependency spec for uv, poetry, or pip
• uv support — the installer auto-detects uv and uses uv sync for blazing-fast setup
• Backwards compatible — pip install -r requirements.txt still works

🛠️ 3 New MCP Tools (5 → 8 total)

⬇️ WebUI Export

• Export All button in the toolbar (or press Ctrl+E)
• Downloads a timestamped contextkeep_backup_YYYY-MM-DD.json

🧹 Code Quality

• Fixed dead code in memory_manager.py (unreachable duplicate try/except)
• Added missing core/__init__.py for proper Python packaging
• Replaced bare except: with except Exception: throughout

🚀 Installation

Option 1: Quick Start (pip)

1. Clone the repository:

   git clone https://github.com/mordang7/ContextKeep.git
   cd ContextKeep
   

2. Run the Installer:

   • Linux/macOS:

     python3 install.py
     

   • Windows:

     python install.py
     

3. Follow the Wizard: The installer creates a virtual environment, installs dependencies, and generates a ready-to-use mcp_config.json.

Option 2: uv (Fast)

git clone https://github.com/mordang7/ContextKeep.git
cd ContextKeep
uv sync
uv run python server.py

Option 3: Docker (Recommended for Homelabs)

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

This starts:

Memories persist in a Docker volume (contextkeep-data).

🛠️ MCP Tools

ContextKeep exposes 8 MCP tools to any connected agent:

Recommended Agent Directive

Add this to your GEMINI.md, AGENTS.md, or CLAUDE.md:

## Memory Index Protocol (MANDATORY)
1. FIRST — call `list_all_memories()` to get the complete key directory
2. THEN — call `retrieve_memory(exact_key)` using the exact key from step 1
Only use `search_memories()` for content-based searches, NOT for key lookup.

🔌 Configuration

Copy the contents of mcp_config.example.json into your AI client's config file and update the paths.

Option 1: Local (Claude Desktop / Gemini CLI / Cursor)

{
  "mcpServers": {
    "context-keep": {
      "command": "/absolute/path/to/ContextKeep/venv/bin/python",
      "args": ["/absolute/path/to/ContextKeep/server.py"]
    }
  }
}

Option 2: Remote via SSH (Homelab / Raspberry Pi)

Run ContextKeep on a home server and access it from any machine on your network:

{
  "mcpServers": {
    "context-keep": {
      "command": "ssh",
      "args": [
        "-i", "/path/to/private_key",
        "[email protected]",
        "'/path/to/ContextKeep/venv/bin/python'",
        "'/path/to/ContextKeep/server.py'"
      ]
    }
  }
}

Option 3: SSE Mode (HTTP)

Ideal for OpenCode, web apps, or any client that prefers HTTP transport:

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

Option 4: Docker

Use mcp_config.docker.example.json or point your client to the container:

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

🌐 Web Dashboard

ContextKeep ships with a full-featured web UI to manage your memories without touching the CLI.

• URL: http://localhost:5000
• Grid View: Memory cards with tag chips, char counts, and inline actions
• List View: Dense, scannable table with all memories sorted by last updated
• Calendar View: Browse your memory history by month
• Search: Real-time filtering across titles, keys, and content
• Full CRUD: Create, view, edit, and delete memories from the browser
• Export: Download all memories as JSON with one click (Ctrl+E)

To start manually:

./venv/bin/python webui.py

🐧 Linux Service Setup (Recommended for Homelabs)

Run both the MCP server and Web UI as persistent background services:

chmod +x install_services.sh
./install_services.sh

This installs:

Manage services:

sudo systemctl status contextkeep-server
sudo systemctl restart contextkeep-webui

📋 Changelog

V1.3 — Harbor

• ✅ Docker Support — Dockerfile + docker-compose.yml for one-command deployment
• ✅ Modern Packaging — pyproject.toml + uv support alongside pip
• ✅ New MCP tool: delete_memory() — agents can now delete memories
• ✅ New MCP tool: get_memory_stats() — memory count & size at a glance
• ✅ New MCP tool: export_memories() — full backup as JSON
• ✅ WebUI: Export All button with Ctrl+E shortcut
• ✅ WebUI: Stats API endpoint
• ✅ Fix: Removed dead code in memory_manager.py
• ✅ Fix: Added missing core/__init__.py for Docker/package imports
• ✅ Fix: Bare except replaced with except Exception
• ✅ Updated installer to V1.3 with uv detection
• ✅ Community contributors credited 🙏

V1.2 — Obsidian Lab

• ✅ New list_all_memories() MCP tool — complete memory directory in one call
• ✅ Obsidian Lab UI redesign — dark premium aesthetic with cyan/neon accents
• ✅ Memory count live badge in the header
• ✅ Calendar month navigation (forward/back)
• ✅ Grid cards now show tag chips and character count badges
• ✅ Removed "Recent Memories" sidebar for a cleaner calendar layout
• ✅ Memory Index Protocol V1.2 — standardised two-step agent retrieval pattern

V1.1

• Web dashboard with Grid, List, and Calendar views
• SSE transport support alongside Stdio
• Linux systemd service installer
• Memory titles and timestamps

V1.0

• Core MCP server with store_memory, retrieve_memory, search_memories
• JSON-backed persistent storage
• SSH remote transport support

🤝 Contributing

Contributions are welcome. Open a PR, file an issue, or suggest a feature — all input is appreciated.

V1.3 Community Contributors

A huge thank you to everyone who contributed to the Harbor release:

• @shuft — Opened Issue #1 requesting Docker support
• @Cyberdogs7 — PR #2: Initial Docker & Docker Compose implementation
• @frehov — PR #3: Dockerfile, pyproject.toml, uv support, __init__.py fix
• @thinkstylestudio — Community advocacy

☕ Support the Project

If ContextKeep saves you time, tokens, or sanity — consider buying me a coffee.