Skip to content
Back to search

ContextKeep

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mordang7--contextkeep/badge.svg)](/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)

  1. <div align="center">
  2. ![ContextKeep Banner](assets/banner.png)
  3. # ContextKeep
  4. ### Long-Term Memory for AI Agents
  5. [![Version: 2.1](https://img.shields.io/badge/Version-2.1-brightgreen?style=for-the-badge)](https://github.com/mordang7/ContextKeep)
  6. [![Status: Stable](https://img.shields.io/badge/Status-Stable-blue?style=for-the-badge)](https://github.com/mordang7/ContextKeep)
  7. [![Platform: Linux | Windows | macOS](https://img.shields.io/badge/Platform-Linux%20%7C%20Windows%20%7C%20macOS-lightgrey?style=for-the-badge)](https://github.com/mordang7/ContextKeep)
  8. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://opensource.org/licenses/MIT)
  9. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge)](https://www.python.org/downloads/)
  10. [![MCP Ready](https://img.shields.io/badge/MCP-Ready-green.svg?style=for-the-badge)](https://modelcontextprotocol.io/)
  11. [![Docker Ready](https://img.shields.io/badge/Docker-Ready-2496ED.svg?style=for-the-badge&logo=docker&logoColor=white)](https://docs.docker.com/)
  12. **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.
  13. [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)
  14. </div>
  15. ---
  16. ## Features
  17. - Persistent local memory for MCP-compatible agents.
  18. - SQLite storage with FTS5 full-text search.
  19. - User-editable categories instead of fixed tags.
  20. - Multiple categories per memory.
  21. - WebUI for browsing, editing, searching, exporting, and category management.
  22. - Streamable HTTP MCP endpoint at `/mcp`, with SSE fallback for older clients.
  23. - Docker Compose support with one default service for WebUI and MCP.
  24. - Verified backup and restore helpers for bare-metal and Docker upgrades.
  25. - Server identity checks through `get_contextkeep_info`.
  26. ![ContextKeep Showcase](assets/Showcase.png)
  27. ## What's New In V2.1 Atlas
  28. V2.1 is the first category-first ContextKeep release.
  29. - `list_all_memories` has been removed.
  30. - Agents now use `list_categories` and `list_memories` before `retrieve_memory`.
  31. - `tags` are replaced by user-editable `categories`.
  32. - Memories can belong to more than one category.
  33. - V1 tags are preserved as `legacy_tags` migration metadata.
  34. - Docker now runs WebUI and MCP together by default so both use the same SQLite database.
  35. - `get_contextkeep_info` reports version, storage path, database ID, tool list, and migration status.
  36. - Upgrade scripts create verified backups before continuing.
  37. Older releases remain available through GitHub releases and tags. V2.1 is the recommended version for new installs and upgrades.
  38. ## Safe Upgrade First
  39. 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.
  40. Bare-metal:
  41. ```bash
  42. python scripts/upgrade_to_v2_1.py baremetal
  43. ```
  44. Docker:
  45. ```bash
  46. python scripts/upgrade_to_v2_1.py docker
  47. ```
  48. V1 JSON migration:
  49. ```bash
  50. python scripts/upgrade_to_v2_1.py baremetal --v1-source /path/to/old/data/memories
  51. ```
  52. See [docs/SAFE_UPGRADE.md](docs/SAFE_UPGRADE.md) for backup, restore, Docker volume, and rollback details.
  53. ## Install
  54. ### Fresh Bare-Metal Install
  55. ```bash
  56. git clone https://github.com/mordang7/ContextKeep.git
  57. cd ContextKeep
  58. python -m venv .venv
  59. ```
  60. Linux/macOS:
  61. ```bash
  62. source .venv/bin/activate
  63. pip install -r requirements.txt
  64. ```
  65. Windows PowerShell:
  66. ```powershell
  67. .\.venv\Scripts\Activate.ps1
  68. pip install -r requirements.txt
  69. ```
  70. You can also run the installer:
  71. ```bash
  72. python install.py
  73. ```
  74. ### Fresh Docker Install
  75. ```bash
  76. git clone https://github.com/mordang7/ContextKeep.git
  77. cd ContextKeep
  78. docker compose up -d --build
  79. ```
  80. Default ports:
  81. | Service | URL |
  82. |---------|-----|
  83. | WebUI | `http://localhost:5000` |
  84. | MCP HTTP | `http://localhost:5100/mcp` |
  85. ## Run
  86. Local MCP over stdio:
  87. ```bash
  88. python server.py
  89. ```
  90. Remote MCP over HTTP:
  91. ```bash
  92. python server.py --transport http --host 0.0.0.0 --port 5100
  93. ```
  94. WebUI:
  95. ```bash
  96. python webui.py --host 0.0.0.0 --port 5000
  97. ```
  98. Then open:
  99. ```text
  100. http://localhost:5000
  101. ```
  102. ## MCP Tools
  103. ContextKeep V2.1 exposes 16 tools:
  104. | Tool | Purpose |
  105. |------|---------|
  106. | `get_contextkeep_info` | Confirm version, storage path, database ID, schema, tools, and migration status |
  107. | `list_categories` | List live user-editable categories |
  108. | `create_category` | Create a category when no existing category fits |
  109. | `update_category` | Rename or edit category metadata |
  110. | `delete_category` | Delete an empty category or reassign memories |
  111. | `merge_categories` | Merge one category into another |
  112. | `list_memories` | List memory keys/titles, optionally filtered by category |
  113. | `retrieve_memory` | Retrieve a memory by exact key |
  114. | `search_memories` | Full-text search memory content |
  115. | `list_recent_memories` | List recently updated memories |
  116. | `store_memory` | Store or update a memory with categories |
  117. | `update_categories` | Reassign one memory to one or more categories |
  118. | `get_edit_history` | View edit history for a memory |
  119. | `delete_memory` | Delete a memory permanently |
  120. | `get_memory_stats` | Show memory/category counts and storage path |
  121. | `export_memories` | Export all memories as JSON |
  122. Recommended retrieval flow:
  123. ```text
  124. list_categories -> list_memories -> retrieve_memory
  125. ```
  126. Use `search_memories` for topic discovery, then retrieve the exact matching memory before relying on it.
  127. ## MCP Client Configuration
  128. Most clients that support streamable HTTP:
  129. ```json
  130. {
  131. "mcpServers": {
  132. "context-keep": {
  133. "url": "http://localhost:5100/mcp"
  134. }
  135. }
  136. }
  137. ```
  138. Antigravity IDE uses `serverURL`:
  139. ```json
  140. {
  141. "mcpServers": {
  142. "context-keep": {
  143. "serverURL": "http://localhost:5100/mcp"
  144. }
  145. }
  146. }
  147. ```
  148. SSE fallback:
  149. ```json
  150. {
  151. "mcpServers": {
  152. "context-keep": {
  153. "url": "http://localhost:5100/sse"
  154. }
  155. }
  156. }
  157. ```
  158. For a remote machine, replace `localhost` with the hostname or address of the machine running ContextKeep.
  159. 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.
  160. ## Verify The Right Server
  161. After connecting a client, call `get_contextkeep_info`.
  162. Expected V2.1 values:
  163. - `version`: `2.1.0`
  164. - `schema_version`: `2`
  165. - `storage_backend`: `sqlite`
  166. - `storage_path`: `/app/data/contextkeep.db` in Docker, or your configured local path
  167. - V2.1 tool list including `list_memories`, `list_categories`, `update_categories`, and `get_edit_history`
  168. 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.
  169. ## Backup And Restore
  170. Create a verified bare-metal backup:
  171. ```bash
  172. python scripts/backup_contextkeep.py baremetal --install-dir /path/to/contextkeep
  173. ```
  174. Create a verified Docker backup:
  175. ```bash
  176. python scripts/backup_contextkeep.py docker --volume <docker-volume-name>
  177. ```
  178. Restore commands are written into every backup folder. The full guide is in [docs/SAFE_UPGRADE.md](docs/SAFE_UPGRADE.md).
  179. 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.
  180. ## Docs
  181. - [Safe Upgrade Guide](docs/SAFE_UPGRADE.md)
  182. - [V2.1 Release Notes](RELEASE_NOTES_V2.1.md)
  183. - [Docker V2.1 Guide](docs/DOCKER_V2_1.md)
  184. - [Client Configuration](docs/CLIENT_CONFIGURATION.md)
  185. - [Migration Guide](docs/MIGRATION_GUIDE.md)
  186. - [Upgrading From V1](docs/UPGRADING_FROM_V1.md)
  187. - [Directive Update Block](docs/DIRECTIVE_UPDATE.md)
  188. ## Changelog
  189. ### V2.1 Atlas
  190. - SQLite database with FTS5 search.
  191. - User-editable categories with multi-category memory assignment.
  192. - WebUI category management.
  193. - V1 JSON migration with legacy tag preservation.
  194. - One-container Docker default for shared WebUI/MCP database access.
  195. - `get_contextkeep_info` identity checks.
  196. - Verified backup and restore tooling.
  197. - Updated MCP client examples for HTTP, Antigravity, and SSE fallback.
  198. ### V1.3 Harbor
  199. - Docker support.
  200. - Modern Python packaging.
  201. - New tools: `delete_memory`, `get_memory_stats`, `export_memories`.
  202. - WebUI export.
  203. - Packaging and code quality fixes.
  204. ### V1.2 Obsidian Lab
  205. - Memory directory tool.
  206. - Obsidian Lab UI redesign.
  207. - Calendar and memory count improvements.
  208. ### V1.1
  209. - Web dashboard.
  210. - SSE transport support.
  211. - Linux systemd service installer.
  212. - Memory titles and timestamps.
  213. ### V1.0
  214. - Core MCP server with persistent JSON-backed memory.
  215. - Local stdio and remote access patterns.
  216. ## Contributing
  217. Issues, feature ideas, and pull requests are welcome. If you build a client guide, migration recipe, or workflow pattern around ContextKeep, please share it.
  218. ### V1.3 Community Contributors
  219. Thank you to everyone who contributed to the Harbor release:
  220. - [@shuft](https://github.com/shuft) opened the Docker support request.
  221. - [@Cyberdogs7](https://github.com/Cyberdogs7) contributed the initial Docker and Docker Compose implementation.
  222. - [@frehov](https://github.com/frehov) contributed Dockerfile, `pyproject.toml`, `uv` support, and packaging fixes.
  223. - [@thinkstylestudio](https://github.com/thinkstylestudio) supported the project through community advocacy.
  224. ## Support
  225. If ContextKeep saves you time, tokens, or context-window pain, support is appreciated.
  226. [![Ko-Fi](https://img.shields.io/badge/Ko--Fi-Support%20Me-F16061?style=flat&logo=ko-fi&logoColor=white)](https://ko-fi.com/geekj)
  227. ---
  228. <div align="center">
  229. <sub>Built by GeekJohn</sub>
  230. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.