Back to search
ContextKeep
SkillGitHub
Infinite Long-Term Memory for AI Agents (MCP Server)
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/mordang7--contextkeep)HTML
<a href="/listings/mordang7--contextkeep"><img src="/api/listings/mordang7--contextkeep/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
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:
| Service | URL | |---------|-----| | WebUI | `http://localhost:5000` | | MCP HTTP | `http://localhost:5100/mcp` |
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 325 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <div align="center">
- 
- # ContextKeep
- ### Long-Term Memory for AI Agents
- [](https://github.com/mordang7/ContextKeep)
- [](https://github.com/mordang7/ContextKeep)
- [](https://github.com/mordang7/ContextKeep)
- [](https://opensource.org/licenses/MIT)
- [](https://www.python.org/downloads/)
- [](https://modelcontextprotocol.io/)
- [](https://docs.docker.com/)
- **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](#whats-new-in-v21-atlas) | [Safe Upgrade](#safe-upgrade-first) | [Install](#install) | [MCP Tools](#mcp-tools) | [Configuration](#mcp-client-configuration) | [Docs](#docs)
- </div>
- ---
- ## 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`.
- 
- ## 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:
- ```bash
- python scripts/upgrade_to_v2_1.py baremetal
- ```
- Docker:
- ```bash
- python scripts/upgrade_to_v2_1.py docker
- ```
- V1 JSON migration:
- ```bash
- python scripts/upgrade_to_v2_1.py baremetal --v1-source /path/to/old/data/memories
- ```
- See [docs/SAFE_UPGRADE.md](docs/SAFE_UPGRADE.md) for backup, restore, Docker volume, and rollback details.
- ## Install
- ### Fresh Bare-Metal Install
- ```bash
- git clone https://github.com/mordang7/ContextKeep.git
- cd ContextKeep
- python -m venv .venv
- ```
- Linux/macOS:
- ```bash
- source .venv/bin/activate
- pip install -r requirements.txt
- ```
- Windows PowerShell:
- ```powershell
- .\.venv\Scripts\Activate.ps1
- pip install -r requirements.txt
- ```
- You can also run the installer:
- ```bash
- python install.py
- ```
- ### Fresh Docker Install
- ```bash
- git clone https://github.com/mordang7/ContextKeep.git
- cd ContextKeep
- docker compose up -d --build
- ```
- Default ports:
- | Service | URL |
- |---------|-----|
- | WebUI | `http://localhost:5000` |
- | MCP HTTP | `http://localhost:5100/mcp` |
- ## Run
- Local MCP over stdio:
- ```bash
- python server.py
- ```
- Remote MCP over HTTP:
- ```bash
- python server.py --transport http --host 0.0.0.0 --port 5100
- ```
- WebUI:
- ```bash
- python webui.py --host 0.0.0.0 --port 5000
- ```
- Then open:
- ```text
- http://localhost:5000
- ```
- ## MCP Tools
- ContextKeep V2.1 exposes 16 tools:
- | Tool | Purpose |
- |------|---------|
- | `get_contextkeep_info` | Confirm version, storage path, database ID, schema, tools, and migration status |
- | `list_categories` | List live user-editable categories |
- | `create_category` | Create a category when no existing category fits |
- | `update_category` | Rename or edit category metadata |
- | `delete_category` | Delete an empty category or reassign memories |
- | `merge_categories` | Merge one category into another |
- | `list_memories` | List memory keys/titles, optionally filtered by category |
- | `retrieve_memory` | Retrieve a memory by exact key |
- | `search_memories` | Full-text search memory content |
- | `list_recent_memories` | List recently updated memories |
- | `store_memory` | Store or update a memory with categories |
- | `update_categories` | Reassign one memory to one or more categories |
- | `get_edit_history` | View edit history for a memory |
- | `delete_memory` | Delete a memory permanently |
- | `get_memory_stats` | Show memory/category counts and storage path |
- | `export_memories` | Export all memories as JSON |
- Recommended retrieval flow:
- ```text
- 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:
- ```json
- {
- "mcpServers": {
- "context-keep": {
- "url": "http://localhost:5100/mcp"
- }
- }
- }
- ```
- Antigravity IDE uses `serverURL`:
- ```json
- {
- "mcpServers": {
- "context-keep": {
- "serverURL": "http://localhost:5100/mcp"
- }
- }
- }
- ```
- SSE fallback:
- ```json
- {
- "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:
- ```bash
- python scripts/backup_contextkeep.py baremetal --install-dir /path/to/contextkeep
- ```
- Create a verified Docker backup:
- ```bash
- 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](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](docs/SAFE_UPGRADE.md)
- - [V2.1 Release Notes](RELEASE_NOTES_V2.1.md)
- - [Docker V2.1 Guide](docs/DOCKER_V2_1.md)
- - [Client Configuration](docs/CLIENT_CONFIGURATION.md)
- - [Migration Guide](docs/MIGRATION_GUIDE.md)
- - [Upgrading From V1](docs/UPGRADING_FROM_V1.md)
- - [Directive Update Block](docs/DIRECTIVE_UPDATE.md)
- ## 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](https://github.com/shuft) opened the Docker support request.
- - [@Cyberdogs7](https://github.com/Cyberdogs7) contributed the initial Docker and Docker Compose implementation.
- - [@frehov](https://github.com/frehov) contributed Dockerfile, `pyproject.toml`, `uv` support, and packaging fixes.
- - [@thinkstylestudio](https://github.com/thinkstylestudio) supported the project through community advocacy.
- ## Support
- If ContextKeep saves you time, tokens, or context-window pain, support is appreciated.
- [](https://ko-fi.com/geekj)
- ---
- <div align="center">
- <sub>Built by GeekJohn</sub>
- </div>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.