ContextKeep 🧠

Infinite Long-Term Memory for AI Agents

ContextKeep is a powerful, standalone memory server that gives your AI agents (Claude, Cursor, Gemini, OpenCode, and more) a persistent, searchable brain. Stop repeating yourself — let your AI remember everything, permanently.

Features • What's New in V1.2 • Installation • MCP Tools • Web Dashboard • Configuration

🌟 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.

🆕 What's New in V1.2

🧭 list_all_memories() — The Memory Index Tool

The headline feature of V1.2. Agents can now call list_all_memories() to receive a complete directory of every stored memory — key, title, tags, and last-updated timestamp — in a single call. This eliminates unreliable fuzzy key guessing and makes memory retrieval 100% deterministic.

📚 Memory Directory — 140 total memories:
==================================================

🔑 Key:     GJ_Personal_Setup_Master
   Title:   Personal System Specifications (Master Record)
   Tags:    setup, specs, desktop, homelab
   Updated: 2026-02-19T12:37

🔑 Key:     GeekJ_Video_Shield_vs_Streamer_2026
   Title:   GeekJ Video: Shield TV Pro vs Google TV Streamer 4K
   Tags:    GeekJ, YouTube, video, streaming
   Updated: 2026-02-10T22:06
...

The recommended retrieval protocol for agents:

Step 1: Call list_all_memories() → scan the directory for the exact key. Step 2: Call retrieve_memory(exact_key) → fetch the full content.

Only use search_memories() for content-based searches, not key lookup.

🎨 Obsidian Lab UI Redesign

The web dashboard has been completely reskinned with a premium dark "Obsidian Lab" aesthetic:

• Deep navy background with electric cyan (#00e5ff) accents

• JetBrains Mono for memory keys — instantly distinguishable at a glance

• Violet tag chips on Grid cards

• Live memory count badge in the top-right header

📅 Enhanced Calendar View

• Full month navigation — scroll forward and backward through your memory timeline

• Cleaned-up layout — the "Recent Memories" sidebar has been removed for a focused, distraction-free calendar experience

🃏 Richer Grid Cards

Grid view cards now show:

• Tag chips — all tags displayed as coloured pills directly on the card

• Character count badge — instant size indicator per memory (e.g. 2.1k chars)

🚀 Installation

Prerequisites

• Python 3.10 or higher

• Git (optional)

Quick Start

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.

🛠️ MCP Tools

ContextKeep exposes 5 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",
        "user@192.168.1.X",
        "'/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"
    }
  }
}

🌐 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

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.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

• SQLite-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.

☕ Support the Project

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