claudetools/CONTEXT_RECALL_ENDPOINTS.md

# Context Recall System - Complete Endpoint Reference

## Quick Reference - All 35 Endpoints

---

## 1. Conversation Contexts (8 endpoints)

### Base Path: `/api/conversation-contexts`

```
GET    /api/conversation-contexts
GET    /api/conversation-contexts/{context_id}
POST   /api/conversation-contexts
PUT    /api/conversation-contexts/{context_id}
DELETE /api/conversation-contexts/{context_id}
GET    /api/conversation-contexts/by-project/{project_id}
GET    /api/conversation-contexts/by-session/{session_id}
GET    /api/conversation-contexts/recall  ⭐ SPECIAL: Context injection
```

### Key Endpoint: Context Recall

**Purpose:** Main context recall API for Claude prompt injection

```bash
GET /api/conversation-contexts/recall?project_id={uuid}&tags=api,auth&limit=10&min_relevance_score=5.0
```

**Query Parameters:**
- `project_id` (optional): Filter by project UUID
- `tags` (optional): List of tags (OR logic)
- `limit` (default: 10, max: 50)
- `min_relevance_score` (default: 5.0, range: 0.0-10.0)

**Returns:** Token-efficient markdown formatted for Claude prompt

---

## 2. Context Snippets (9 endpoints)

### Base Path: `/api/context-snippets`

```
GET    /api/context-snippets
GET    /api/context-snippets/{snippet_id}  ⭐ Auto-increments usage_count
POST   /api/context-snippets
PUT    /api/context-snippets/{snippet_id}
DELETE /api/context-snippets/{snippet_id}
GET    /api/context-snippets/by-project/{project_id}
GET    /api/context-snippets/by-client/{client_id}
GET    /api/context-snippets/by-tags?tags=api,auth
GET    /api/context-snippets/top-relevant
```

### Key Features:

**Get by ID:** Automatically increments `usage_count` for tracking

**Get by Tags:**
```bash
GET /api/context-snippets/by-tags?tags=api,fastapi,auth
```
Uses OR logic - matches any tag

**Top Relevant:**
```bash
GET /api/context-snippets/top-relevant?limit=10&min_relevance_score=7.0
```
Returns highest scoring snippets

---

## 3. Project States (7 endpoints)

### Base Path: `/api/project-states`

```
GET    /api/project-states
GET    /api/project-states/{state_id}
POST   /api/project-states
PUT    /api/project-states/{state_id}
DELETE /api/project-states/{state_id}
GET    /api/project-states/by-project/{project_id}
PUT    /api/project-states/by-project/{project_id}  ⭐ UPSERT
```

### Key Endpoint: Upsert by Project

**Purpose:** Update existing or create new project state

```bash
PUT /api/project-states/by-project/{project_id}
```

**Body:**
```json
{
  "current_phase": "testing",
  "progress_percentage": 85,
  "blockers": "[\"Waiting for code review\"]",
  "next_actions": "[\"Deploy to staging\", \"Run integration tests\"]"
}
```

**Behavior:**
- If project state exists: Updates it
- If project state doesn't exist: Creates new one
- Unique constraint: One state per project

---

## 4. Decision Logs (9 endpoints)

### Base Path: `/api/decision-logs`

```
GET    /api/decision-logs
GET    /api/decision-logs/{log_id}
POST   /api/decision-logs
PUT    /api/decision-logs/{log_id}
DELETE /api/decision-logs/{log_id}
GET    /api/decision-logs/by-project/{project_id}
GET    /api/decision-logs/by-session/{session_id}
GET    /api/decision-logs/by-impact/{impact}  ⭐ Impact filtering
```

### Key Endpoint: Filter by Impact

**Purpose:** Retrieve decisions by impact level

```bash
GET /api/decision-logs/by-impact/{impact}?skip=0&limit=50
```

**Valid Impact Levels:**
- `low`
- `medium`
- `high`
- `critical`

**Example:**
```bash
GET /api/decision-logs/by-impact/high
```

---

## Common Patterns

### Authentication

All endpoints require JWT authentication:

```http
Authorization: Bearer <jwt_token>
```

### Pagination

Standard pagination for list endpoints:

```bash
GET /api/{resource}?skip=0&limit=100
```

**Parameters:**
- `skip` (default: 0, min: 0): Records to skip
- `limit` (default: 100, min: 1, max: 1000): Max records

**Response:**
```json
{
  "total": 250,
  "skip": 0,
  "limit": 100,
  "items": [...]
}
```

### Error Responses

**404 Not Found:**
```json
{
  "detail": "ConversationContext with ID abc123 not found"
}
```

**409 Conflict:**
```json
{
  "detail": "ProjectState for project ID xyz789 already exists"
}
```

**422 Validation Error:**
```json
{
  "detail": [
    {
      "loc": ["body", "context_type"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

---

## Usage Examples

### 1. Store Conversation Context

```bash
POST /api/conversation-contexts
Authorization: Bearer <token>
Content-Type: application/json

{
  "context_type": "session_summary",
  "title": "API Development - Auth Module",
  "dense_summary": "{\"phase\": \"api_dev\", \"completed\": [\"JWT auth\", \"refresh tokens\"]}",
  "key_decisions": "[{\"decision\": \"Use JWT\", \"rationale\": \"Stateless\"}]",
  "tags": "[\"api\", \"auth\", \"jwt\"]",
  "relevance_score": 8.5,
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "session_id": "660e8400-e29b-41d4-a716-446655440000"
}
```

### 2. Recall Contexts for Prompt

```bash
GET /api/conversation-contexts/recall?project_id=550e8400-e29b-41d4-a716-446655440000&tags=api,auth&limit=5&min_relevance_score=7.0
Authorization: Bearer <token>
```

**Response:**
```json
{
  "context": "## Context Recall\n\n**Decisions:**\n- Use JWT for auth [api, auth, jwt]\n- Implement refresh tokens [api, auth]\n\n**Session Summaries:**\n- API Development - Auth Module [api, auth]\n\n*2 contexts loaded*\n",
  "project_id": "550e8400-e29b-41d4-a716-446655440000",
  "tags": ["api", "auth"],
  "limit": 5,
  "min_relevance_score": 7.0
}
```

### 3. Create Context Snippet

```bash
POST /api/context-snippets
Authorization: Bearer <token>
Content-Type: application/json

{
  "category": "tech_decision",
  "title": "FastAPI Async Support",
  "dense_content": "Using FastAPI for native async/await support in API endpoints",
  "tags": "[\"fastapi\", \"async\", \"performance\"]",
  "relevance_score": 9.0,
  "project_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### 4. Update Project State (Upsert)

```bash
PUT /api/project-states/by-project/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>
Content-Type: application/json

{
  "current_phase": "testing",
  "progress_percentage": 85,
  "blockers": "[\"Waiting for database migration approval\"]",
  "next_actions": "[\"Deploy to staging\", \"Run integration tests\", \"Update documentation\"]",
  "context_summary": "Auth module complete. Testing in progress.",
  "key_files": "[\"api/auth.py\", \"api/middleware/jwt.py\", \"tests/test_auth.py\"]"
}
```

### 5. Log Decision

```bash
POST /api/decision-logs
Authorization: Bearer <token>
Content-Type: application/json

{
  "decision_type": "architectural",
  "decision_text": "Use PostgreSQL for primary database",
  "rationale": "Strong ACID compliance, JSON support, mature ecosystem",
  "alternatives_considered": "[\"MongoDB\", \"MySQL\", \"SQLite\"]",
  "impact": "high",
  "tags": "[\"database\", \"architecture\", \"postgresql\"]",
  "project_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### 6. Get High-Impact Decisions

```bash
GET /api/decision-logs/by-impact/high?skip=0&limit=20
Authorization: Bearer <token>
```

### 7. Get Top Relevant Snippets

```bash
GET /api/context-snippets/top-relevant?limit=10&min_relevance_score=8.0
Authorization: Bearer <token>
```

### 8. Get Context Snippets by Tags

```bash
GET /api/context-snippets/by-tags?tags=fastapi,api,auth&skip=0&limit=50
Authorization: Bearer <token>
```

---

## Integration Workflow

### Typical Claude Session Flow:

1. **Session Start**
   - Call `/api/conversation-contexts/recall` to load relevant context
   - Inject returned markdown into Claude's prompt

2. **During Work**
   - Create context snippets for important decisions/patterns
   - Log decisions via `/api/decision-logs`
   - Update project state via `/api/project-states/by-project/{id}`

3. **Session End**
   - Create session summary via `/api/conversation-contexts`
   - Update project state with final progress
   - Tag contexts for future retrieval

### Context Recall Strategy:

```python
# High-level workflow
def prepare_claude_context(project_id, relevant_tags):
    # 1. Get project state
    project_state = GET(f"/api/project-states/by-project/{project_id}")

    # 2. Recall relevant contexts
    contexts = GET(f"/api/conversation-contexts/recall", params={
        "project_id": project_id,
        "tags": relevant_tags,
        "limit": 10,
        "min_relevance_score": 6.0
    })

    # 3. Get top relevant snippets
    snippets = GET("/api/context-snippets/top-relevant", params={
        "limit": 5,
        "min_relevance_score": 8.0
    })

    # 4. Get recent high-impact decisions
    decisions = GET(f"/api/decision-logs/by-project/{project_id}", params={
        "skip": 0,
        "limit": 5
    })

    # 5. Format for Claude prompt
    return format_prompt(project_state, contexts, snippets, decisions)
```

---

## Testing with Swagger UI

Access interactive API documentation:

**Swagger UI:** `http://localhost:8000/api/docs`
**ReDoc:** `http://localhost:8000/api/redoc`

### Swagger UI Features:
- Try endpoints directly in browser
- Auto-generated request/response examples
- Authentication testing
- Schema validation

---

## Response Formats

### List Response (Paginated)

```json
{
  "total": 150,
  "skip": 0,
  "limit": 100,
  "items": [
    {
      "id": "uuid",
      "field1": "value1",
      "created_at": "2026-01-16T12:00:00Z",
      "updated_at": "2026-01-16T12:00:00Z"
    }
  ]
}
```

### Single Item Response

```json
{
  "id": "uuid",
  "field1": "value1",
  "field2": "value2",
  "created_at": "2026-01-16T12:00:00Z",
  "updated_at": "2026-01-16T12:00:00Z"
}
```

### Delete Response

```json
{
  "message": "Resource deleted successfully",
  "resource_id": "uuid"
}
```

### Recall Context Response

```json
{
  "context": "## Context Recall\n\n**Decisions:**\n...",
  "project_id": "uuid",
  "tags": ["api", "auth"],
  "limit": 10,
  "min_relevance_score": 5.0
}
```

---

## Performance Considerations

### Database Indexes

All models have optimized indexes:

**ConversationContext:**
- `session_id`, `project_id`, `machine_id`
- `context_type`, `relevance_score`

**ContextSnippet:**
- `project_id`, `client_id`
- `category`, `relevance_score`, `usage_count`

**ProjectState:**
- `project_id` (unique)
- `last_session_id`, `progress_percentage`

**DecisionLog:**
- `project_id`, `session_id`
- `decision_type`, `impact`

### Query Optimization

- List endpoints ordered by most relevant fields
- Pagination limits prevent large result sets
- Tag filtering uses JSON containment operators
- Relevance scoring computed at query time

---

## Summary

**Total Endpoints:** 35
- Conversation Contexts: 8
- Context Snippets: 9
- Project States: 7
- Decision Logs: 9
- Special recall endpoint: 1
- Special upsert endpoint: 1

**Special Features:**
- Context recall for Claude prompt injection
- Usage tracking on snippet retrieval
- Upsert functionality for project states
- Impact-based decision filtering
- Tag-based filtering with OR logic
- Relevance scoring for prioritization

**All endpoints:**
- Require JWT authentication
- Support pagination where applicable
- Include comprehensive error handling
- Are fully documented in OpenAPI/Swagger
- Follow RESTful conventions