ContextKeep

The list_all_memories tool has been removed in V2.1 to improve scaling. Agents should instead use a three-step retrieval pattern to find relevant information:

1. List categories: Call list_categories() to see available taxonomies.
2. List memories by category: Call list_memories(category="Relevant Category") to narrow down the search.
3. Retrieve specific memory: Call retrieve_memory(key="Exact_Key") to get the full content.

To efficiently find and read memory content, follow this sequence:

1. List Categories: Call list_categories() to see available groupings.
2. Filter: Choose the most relevant category from the list.
3. List Memories: Call list_memories(category="Category Name", limit=50) to find specific keys.
4. Retrieve Content: Call retrieve_memory(key="Exact_Key") to get the full content of the memory.
5. Fallback: If the category path is insufficient, use search_memories(query="...") for full-text search.

V2.1 uses categories instead of tags. A single memory can belong to multiple categories. To maintain an organized database, agents should follow this workflow:

1. List existing categories: Call list_categories first.
2. Reuse existing categories: Choose one or more existing categories whenever possible.
3. Create sparingly: Only call create_category if the memory represents a durable area that does not fit into the current list.
4. Update assignments: Use update_categories if you only need to change the category assignment of a memory.

Note: While the server will automatically create missing categories if a new name is passed to store_memory, following this deliberate workflow prevents category bloat.

ContextKeep backups are designed to be highly reliable. Before any upgrade proceeds, the backup tools perform the following integrity checks:

• Archive Integrity: The .zip archive can be opened and fully read.
• File Integrity: Every archived file matches its recorded SHA256 checksum.
• Database Integrity: SQLite databases pass PRAGMA integrity_check.
• Data Compatibility: V1 JSON memory files can be successfully parsed.
• Recoverability: A valid restore command is present in the backup folder.

If any check fails, the upgrade process stops immediately without modifying the existing installation.

When saving new information, follow these rules to ensure proper categorization:

1. Check Categories: Always call list_categories() before storing to see existing options.
2. Assign Categories: Assign at least one category from the live list. Use multiple categories if the information spans different topics.
3. Create if Necessary: If no existing category fits, call create_category() before attempting to store.
4. Avoid Assumptions: Never assume starter categories exist or retain their original names; always verify against the live list.
5. Avoid Over-segmentation: Do not create narrow, one-off categories if a combination of existing categories is appropriate.

list_categories()
create_category(name="New Category")
store_memory(..., categories=["Category A", "Category B"])

V2.1 uses a flexible category system instead of fixed tags:

• User-Owned Taxonomy: Users own the taxonomy; starter categories are only defaults.
• Multi-Category Support: Memories can belong to more than one category.
• Agent Behavior: Agents should inspect the live category list (via list_categories()) before storing memories. Agents should only create a new category if no existing category fits.

To deploy ContextKeep V2.1 using Docker, you can perform either a safe upgrade for existing installations or a fresh installation.

Upgrade an existing installation

Use the safe upgrade wrapper to create and verify a backup of your existing Docker data before rebuilding the V2.1 stack:

python scripts/upgrade_to_v2_1.py docker

Note: If your older deployment uses a different compose file, service name, or volume, consult SAFE_UPGRADE.md first.

Fresh installation

For a new deployment, use Docker Compose:

docker compose up -d --build

To prevent accidental data loss, follow these safety protocols:

• Memory Deletion: If requested to delete a memory, always ask for explicit confirmation before calling delete_memory.
• Category Deletion: Before deleting a category, ensure it is empty. If it contains memories, you must first reassign those memories to other categories or use merge_categories to move them.

Before migrating from V1 to V2, you must create a verified backup. The migration process reads your V1 data/memories folder and writes to a new SQLite database. Do not delete the V1 folder until the migration is complete and verified.

Use the backup script to create an archive that is automatically checksummed and checked for SQLite/JSON integrity.

python scripts/backup_contextkeep.py baremetal --install-dir /path/to/contextkeep

If you are running a customized installation or are unsure of the upgrade path, perform a manual backup first to ensure safety. Inspect the generated manifest.json and RESTORE_INSTRUCTIONS.md in the backups/ folder before attempting any upgrades.

# Backup bare-metal installation
python scripts/backup_contextkeep.py baremetal --install-dir /path/to/contextkeep

# Backup Docker volume
python scripts/backup_contextkeep.py docker --volume <docker-volume-name>

To upgrade a bare-metal installation to V2.1, run the upgrade script from the V2.1 folder. The script automatically backs up your current installation and verifies data integrity before proceeding.

If you are migrating from V1.x, you must provide the path to your old JSON memory folder using the --v1-source flag to ensure memories are imported into the new SQLite database. You can also use --reset-target to intentionally rebuild the target database during migration.

# Standard bare-metal upgrade
python scripts/upgrade_to_v2_1.py baremetal

# Upgrade from V1.x with JSON memory migration
python scripts/upgrade_to_v2_1.py baremetal --v1-source /path/to/old/data/memories

# Upgrade and force rebuild of the target database
python scripts/upgrade_to_v2_1.py baremetal --v1-source /path/to/old/data/memories --reset-target