<div align="center">

ContextKeep 🧠

Infinite Long-Term Memory for AI Agents

ContextKeep is a powerful, standalone memory server that gives your AI tools (Claude, Cursor, VS Code, Gemini, OpenCode) a persistent, searchable brain. Stop repeating yourself—let your AI remember.

Features • Installation • Usage • Web Dashboard • Configuration

</div>

---

🌟 Features

• ♾️ Infinite Context: Store unlimited project details, preferences, and snippets.
• 💰 Save Money & Tokens: Reduce context window usage by only retrieving relevant memories, lowering API costs.
• 🔌 Universal Compatibility: Works with any MCP-compliant client via Stdio (Local) or SSE (Remote).
• 🖥️ Modern Web Dashboard: Manage your memories visually with Grid, List, and Calendar views.
• 🔒 Privacy First: 100% local storage. Your data never leaves your machine.
• 🔎 Smart Search: Find exactly what you need with semantic and keyword search.
• 🐧 Linux Service: Runs silently in the background as a system service.

---

---

🚀 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/Mac:

     python3 install.py
     

   • Windows:

     python install.py
     

3. Follow the Wizard: The installer will create a virtual environment, install dependencies, and generate a custom configuration file for you.

---

🔌 Configuration

After installation, you will find a mcp_config.json file in the root directory. Copy its contents into your AI client's configuration.

Example Configurations

1. Claude Desktop / Gemini CLI (Local)

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

2. Remote Access (SSH)

Perfect for running ContextKeep on a home server (e.g., Raspberry Pi) and accessing it from your laptop.

{
  "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'"
      ]
    }
  }
}

3. SSE Mode (Http)

If you prefer HTTP transport (great for OpenCode or web apps):

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

---

🌐 Web Dashboard

ContextKeep includes a beautiful web interface to manage your memories.

• URL: http://localhost:5000
• Features:
  • Dashboard: Overview of recent memories.
  • Calendar: Visual timeline of your work.
  • Search: Instant filtering.
  • CRUD: Create, Read, Update, Delete memories manually.

To start it manually:

./venv/bin/python webui.py

---

🐧 Linux Service Setup (Optional)

Run ContextKeep as a background service (systemd) on Linux/WSL:

chmod +x install_services.sh
./install_services.sh

This will install:

• contextkeep-server (Port 5100)
• contextkeep-webui (Port 5000)

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

☕ Support the Project

If ContextKeep helps you build cool things, consider buying me a coffee!

---

<div align="center"> _{Built with ❤️ by GeekJohn} </div>