README.md•3.33 kB
# Debug History
<!-- MEMORY_ANCHOR: debug_history_documentation -->
This directory contains tools for tracking, searching, and visualizing debugging sessions.
## Why
Debugging is a time-consuming process, and developers often encounter similar issues multiple times. By tracking debugging sessions, we can build a knowledge base of common issues and their solutions, making it easier to solve problems in the future. The vector database enables semantic search, finding conceptually similar errors even when the wording is different.
## Contents
- `vector_db.py`: Script to build and search a vector database of debug history entries
- `web_interface.py`: Web interface for searching and browsing debug history
- `templates/`: HTML templates for the web interface
- `static/`: Static files for the web interface
- `vector_index.faiss`: Faiss index for semantic search (generated by `vector_db.py`)
- `vector_metadata.pkl`: Metadata for the Faiss index (generated by `vector_db.py`)
## Debug Entry Format
Debug history entries are stored as JSON files with the following structure:
```json
{
"id": "unique-id",
"component": "component-name",
"error_type": "error-type",
"error_message": "Error message text",
"error_description": "Detailed description of the error",
"solution_description": "Description of the solution",
"solution_code": "Code snippet that solves the issue",
"tags": ["tag1", "tag2"],
"created_at": "2023-01-01T00:00:00Z"
}
```
## Usage
### Building the Vector Index
To build the vector index:
```bash
python claude/debug_history/vector_db.py build
```
This will:
1. Load all debug history entries from JSON files
2. Create a Faiss index for semantic search
3. Save the index and metadata
### Searching the Vector Index
To search the vector index from the command line:
```bash
python claude/debug_history/vector_db.py search "your search query"
```
This will:
1. Load the Faiss index and metadata
2. Search for entries similar to the query
3. Display the results
### Using the Web Interface
To start the web interface:
```bash
python claude/debug_history/web_interface.py
```
This will:
1. Create HTML templates if they don't exist
2. Build the vector index if it doesn't exist
3. Start a Flask web server
Then open a web browser and navigate to `http://localhost:5000` to use the web interface.
## Adding New Debug Entries
To add a new debug entry:
1. Create a JSON file in the `debug_history` directory with the structure shown above
2. Rebuild the vector index:
```bash
python claude/debug_history/vector_db.py build
```
## Integration with Other Components
The debug history component integrates with:
- **Knowledge Graph**: Error and solution information is included in the knowledge graph
- **Code Health**: Error patterns can be used to identify areas of the codebase that need attention
- **Feedback Loop**: Developers can provide feedback on solutions to improve them over time
## Dependencies
- Python 3.6+
- faiss-cpu: For vector search
- sentence-transformers: For generating embeddings
- flask: For the web interface
Install dependencies with:
```bash
pip install faiss-cpu sentence-transformers flask
```
## Maturity
The debug history component is currently in **beta** status. It is functional but may undergo changes as the codebase evolves.