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

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:

GET /api/context-snippets/by-tags?tags=api,fastapi,auth

Uses OR logic - matches any tag

Top Relevant:

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

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

Body:

{
  "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

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

Valid Impact Levels:

• low
• medium
• high
• critical

Example:

GET /api/decision-logs/by-impact/high

---

Common Patterns

Authentication

All endpoints require JWT authentication:

Authorization: Bearer <jwt_token>

Pagination

Standard pagination for list endpoints:

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:

{
  "total": 250,
  "skip": 0,
  "limit": 100,
  "items": [...]
}

Error Responses

404 Not Found:

{
  "detail": "ConversationContext with ID abc123 not found"
}

409 Conflict:

{
  "detail": "ProjectState for project ID xyz789 already exists"
}

422 Validation Error:

{
  "detail": [
    {
      "loc": ["body", "context_type"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

---

Usage Examples

1. Store Conversation Context

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

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:

{
  "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

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)

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

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

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

7. Get Top Relevant Snippets

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

8. Get Context Snippets by Tags

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:

# 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)

{
  "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

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

Delete Response

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

Recall Context Response

{
  "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