Deleting Documents from Claude OS MCP

When you need to remove previously uploaded documents from a knowledge base.

Method 1: API Endpoint (Recommended)

The MCP server now supports deleting documents by filename:

# Delete a single document by filename
curl -X DELETE "http://localhost:8051/api/kb/{kb_name}/documents/{filename}"

# Example: Delete api.md from Project KB
curl -X DELETE "http://localhost:8051/api/kb/Project%20KB/documents/api.md"

# Response on success:
{
  "success": true,
  "message": "Deleted 1 document(s)",
  "filename": "api.md",
  "kb_name": "Project KB"
}

Notes

Replace {kb_name} with the actual KB name (use URL encoding for spaces: %20)
The filename should match exactly what was uploaded
Deleting a document removes it and all its chunks from the vector database

Method 2: Manual SQLite Query (Alternative)

If the API endpoint has issues, you can delete documents directly from SQLite:

# Connect to SQLite database
sqlite3 data/claude-os.db

# Find documents to delete
SELECT id, json_extract(metadata, '$.filename') as filename, kb_id
FROM documents
WHERE json_extract(metadata, '$.filename') LIKE '%api.md%'
LIMIT 10;

# Delete specific document(s)
DELETE FROM documents
WHERE kb_id = (
  SELECT id FROM knowledge_bases WHERE name = 'project-memories'
)
AND json_extract(metadata, '$.filename') = 'api.md';

# Verify deletion
SELECT COUNT(*) FROM documents
WHERE kb_id = (
  SELECT id FROM knowledge_bases WHERE name = 'project-memories'
);

Method 3: Delete All Documents in a KB (Nuclear Option)

WARNING: This deletes everything. Use with caution.

# Delete entire KB and recreate it fresh
curl -X DELETE "http://localhost:8051/api/kb/Project%20KB"

Or via SQLite:

sqlite3 data/claude-os.db

-- Delete KB and all documents
DELETE FROM documents
WHERE kb_id = (
  SELECT id FROM knowledge_bases WHERE name = 'project-memories'
);

DELETE FROM knowledge_bases WHERE name = 'project-memories';

-- Recreate the KB fresh
INSERT INTO knowledge_bases (name, kb_type, slug)
VALUES ('project-memories', 'generic', 'project-memories');

Common Scenarios

Scenario 1: Remove Old Specs Before Re-importing

# Delete all spec documents
for spec_file in "spec.md" "requirements.md" "IMPLEMENTATION.md"; do
  curl -X DELETE "http://localhost:8051/api/kb/Project%20KB/documents/$spec_file"
done

# Then re-import fresh versions
curl -X POST "http://localhost:8051/api/kb/Project%20KB/import?directory_path=%2FUsers%2Fiamanmp%2FProjects%2Fpistn%2Fagent-os"

Scenario 2: Clean Up Old Documentation Before Adding New

# List what's in the KB
curl -s "http://localhost:8051/api/kb/Project%20KB/documents" | python3 -c "
import sys, json
docs = json.load(sys.stdin).get('documents', [])
for doc in docs:
    print(f'{doc[\"filename\"]}')"

# Delete specific old docs one by one

Scenario 3: Fresh Start (Delete Everything)

# Delete the entire KB
curl -X DELETE "http://localhost:8051/api/kb/Project%20KB"

# Recreate it
curl -X POST "http://localhost:8051/api/kb" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Project KB",
    "kb_type": "agent-os",
    "description": "Project KB code"
  }'

# Re-import everything fresh
curl -X POST "http://localhost:8051/api/kb/Project%20KB/import?directory_path=%2FUsers%2Fuser%2FProjects%2Fproject%2Fkb"

Troubleshooting

"Document not found" error

The filename might not match exactly. To find the correct filename:

# List all documents in KB
curl -s "http://localhost:8051/api/kb/Project%20KB/documents" | python3 -m json.tool

Delete endpoint returns "Not Found"

The endpoint might not have loaded properly. Restart the MCP server:

# Kill existing server
pkill -f "uvicorn.*8051"

# Restart
source /Users/iamanmp/Projects/claude-os/venv/bin/activate
python /Users/iamanmp/Projects/claude-os/mcp_server/server.py > /tmp/mcp_server.log 2>&1 &

# Wait for startup
sleep 3

# Test
curl -s "http://localhost:8051/health" | python3 -m json.tool

UI Delete Functionality

The web UI at http://localhost:5173 currently doesn't have a delete button.

To add it (optional enhancement):

The frontend would need a "Delete" button in the document list
This would call the new DELETE /api/kb/{kb_name}/documents/{filename} endpoint
See frontend/src/components/KBManagement.tsx for where to add this

For now, use the API or SQLite methods above.

Coming Soon

UI delete button in Knowledge Base Management
Bulk delete by date range (delete all docs older than X days)
Archive vs Delete (keep metadata but remove embeddings)
Delete confirmation dialog with document preview

4.7 KiB Raw Blame History