Foresight

Foresight transforms TeamLoop from a system that records the past into one that anticipates the future. When a DECISION entity is saved, TeamLoop automatically generates predictions about downstream implications — follow-up actions, team impacts, and technical consequences — so your organization can plan ahead instead of reacting.

Why Foresight?

Standard knowledge management tells you what happened. Foresight tells you what’s likely to happen next.

Without Foresight	With Foresight
”We decided to migrate from REST to gRPC”	Prediction: “SDK team will need to regenerate client libraries within 4-6 weeks”
Decision is recorded, team moves on	Prediction: “API gateway selection required within 4 weeks”
Someone discovers the implication 3 weeks later	Prediction auto-fulfills when the gateway decision is saved

How It Works

Automatic prediction generation

When a DECISION entity is saved (via teamloop_save_knowledge, teamloop_remember, or the REST API), TeamLoop:

1. Gathers context: related entities (2 hops in the knowledge graph) and recent decisions from the last 90 days
2. Sends the decision with its context to an LLM
3. Generates 2-5 predictions, each with a confidence score and time horizon
4. Stores each prediction as a FORESIGHT entity linked to the source decision via a RELATES_TO relationship

This happens asynchronously — saving a decision returns immediately and predictions appear shortly after.

Prediction properties

Each foresight prediction includes:

• Prediction text — A concise statement of what will likely need to happen or what impact is expected
• Evidence — Why this prediction follows from the decision and context
• Confidence — 0.0 to 1.0 (0.5 = possible, 0.7 = likely, 0.9 = near-certain)
• Time horizon — Estimated days until the impact is felt (7 = one week, 30 = one month, 90 = one quarter)
• Status — active, fulfilled, dismissed, or expired

Auto-fulfillment

When a new DECISION or CHANGE entity is saved, TeamLoop checks whether it fulfills any active predictions:

1. The new entity’s embedding is compared against all active FORESIGHT entities using semantic search
2. If cosine similarity exceeds 0.80, the prediction is automatically marked as fulfilled
3. A FULFILLS relationship is created linking the new entity to the prediction

This means predictions resolve themselves — you don’t need to manually track which predictions came true.

Prediction lifecycle

DECISION saved
    |
    v
FORESIGHT entities generated (async)
    |
    v
Status: "active"
    |
    |---> Matching DECISION/CHANGE entity saved ---> Status: "fulfilled" (auto)
    |---> User dismisses prediction              ---> Status: "dismissed"
    |---> Time horizon passes                    ---> Status: "expired"

MCP Tool

teamloop_foresight

Query predictions by topic, by decision, or list all active predictions.

Parameters:

Parameter	Type	Required	Description
query	string	No	Search predictions by topic (e.g., “API migration”, “SDK updates”)
decision_id	string	No	Get predictions for a specific decision by UUID
status	string	No	Filter by status: active (default), fulfilled, dismissed, expired, all

If no parameters are provided, all active predictions are returned.

Search by topic:

Tool: teamloop_foresight
Input: {
  "query": "API migration",
  "status": "active"
}

Get predictions for a specific decision:

Tool: teamloop_foresight
Input: {
  "decision_id": "550e8400-e29b-41d4-a716-446655440000"
}

List all predictions (including fulfilled):

Tool: teamloop_foresight
Input: {
  "status": "all"
}

Example output:

# Foresight matching "API migration"

Found 3 prediction(s).

## 1. SDK team will need to regenerate client libraries
The shift from REST to gRPC will require all client SDKs to be regenerated...

- Confidence: 85%
- Status: active
- Horizon end: 2025-04-15
- Time horizon: 42 days
- Evidence: gRPC uses protocol buffers which require code generation...
- Source decision: 550e8400-e29b-41d4-a716-446655440000
- ID: 7c9e6679-7425-40de-944b-e07fc1f90ae7
- Created: 2025-03-04

REST API

All endpoints require authentication.

List and search predictions

GET /v1/foresight

Query parameters:

Parameter	Type	Default	Description
query	string	—	Semantic search across predictions
status	string	active	Filter by status: active, fulfilled, dismissed, expired, all

Response:

{
  "foresight": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "SDK team will need to regenerate client libraries",
      "description": "The shift from REST to gRPC will require...",
      "confidence": 0.85,
      "status": "active",
      "end_date": "2025-04-15",
      "time_horizon_days": 42,
      "source_decision_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2025-03-04T10:30:00Z"
    }
  ],
  "count": 1
}

Get predictions for a decision

GET /v1/entities/:id/foresight

Returns all predictions linked to a specific decision entity.

Query parameters:

Parameter	Type	Default	Description
status	string	active	Filter by status

Response:

{
  "foresight": [...],
  "count": 2,
  "has_foresight": true
}

Dismiss a prediction

POST /v1/foresight/:id/dismiss

Marks a prediction as no longer relevant. Use this when a prediction is incorrect or the situation has changed.

Response:

{
  "success": true,
  "status": "dismissed"
}

Manually fulfill a prediction

POST /v1/foresight/:id/fulfill

Manually marks a prediction as fulfilled. Use this when auto-fulfillment didn’t detect the match (e.g., the fulfilling action happened outside the system).

Response:

{
  "success": true,
  "status": "fulfilled"
}

Workflow

Day 1: Architecture decision

User: "Remember: We decided to migrate the public API from REST to gRPC.
       The main drivers are performance for mobile clients and strong typing
       with protobuf. We evaluated GraphQL but chose gRPC for backend-to-backend
       communication patterns."

AI: [uses teamloop_remember]
→ Remembered 3 entities. Conflict detection: no conflicts found.

Behind the scenes, TeamLoop generates foresight predictions:

• “SDK client libraries will need regeneration for gRPC/protobuf” (85%, 42 days)
• “API gateway may need gRPC-compatible replacement” (70%, 30 days)
• “Integration test suite will need rewrite for new protocol” (75%, 56 days)

Day 15: Check predictions

User: "What predictions do we have about the API migration?"

AI: [uses teamloop_foresight with query: "API migration"]
→ 3 active predictions found...

Day 25: Prediction auto-fulfills

User: "Remember: We selected Envoy as our new API gateway to support
       gRPC routing. Alex led the evaluation."

AI: [uses teamloop_remember]
→ Remembered 2 entities.

Behind the scenes, the new DECISION entity (“Selected Envoy as API gateway”) auto-fulfills the prediction about API gateway selection (similarity: 0.87).

Tips

• Predictions are generated only for DECISION entities — CHANGE, PERSON, PROJECT, and other entity types do not trigger foresight generation.
• LLM required — Foresight generation requires an LLM to be configured. Without one, decisions are saved normally but no predictions are generated.
• Review predictions periodically — Use teamloop_foresight with status: "active" to review current predictions. Dismiss any that are no longer relevant to keep the feed useful.
• Auto-fulfillment threshold is 0.80 — Predictions are automatically fulfilled when a new DECISION or CHANGE entity has cosine similarity above 0.80. If a prediction should be fulfilled but wasn’t detected, use the manual fulfill endpoint.
• Context improves predictions — The more entities and relationships in your knowledge graph, the better the context available for prediction generation. Rich graphs produce more specific and actionable predictions.