Knowledge Graphs

TeamLoop builds a temporal knowledge graph from your enterprise tools. Unlike flat document stores, knowledge graphs capture relationships, enabling rich queries and synthesis.

What is a Knowledge Graph?

A knowledge graph consists of:

Entities - Things you know about (decisions, people, systems)
Relationships - How entities connect to each other
Embeddings - Vector representations for semantic search
Temporal metadata - When knowledge was valid

┌──────────┐       AUTHORED_BY       ┌──────────┐
│ Decision │ ─────────────────────── │  Person  │
│ Adopt    │                         │  Alice   │
│ Postgres │                         └──────────┘
└────┬─────┘
     │ PART_OF
     ▼
┌──────────┐       SUPERSEDES        ┌──────────┐
│Component │                         │ Decision │
│  Database│                         │Use MySQL │
│  Service │                         └──────────┘
└──────────┘

Entity Types

TeamLoop supports six core entity types:

DECISION

Architectural choices, policy changes, technology selections.

Fields:

name - The decision title
description - What was decided
rationale - Why this choice was made
alternatives - Other options considered
status - active, superseded, proposed
event_date - When the decision was made

Example:

{
  "type": "DECISION",
  "name": "Adopt PostgreSQL for primary database",
  "description": "Selected PostgreSQL over MySQL for the user service",
  "rationale": "Need JSONB support for flexible user preferences schema",
  "alternatives": ["MySQL", "MongoDB", "CockroachDB"],
  "status": "active",
  "event_date": "2024-03-15"
}

DOCUMENT

PRDs, ADRs, specs, meeting notes, wiki pages.

Fields:

name - Document title
description - Summary or excerpt
source_url - Link to original
event_date - Last modified date

Example:

{
  "type": "DOCUMENT",
  "name": "User Service PRD v2",
  "description": "Product requirements for user profile management",
  "source_url": "https://notion.so/...",
  "source_integration": "notion",
  "event_date": "2024-04-01"
}

CHANGE

Code commits, configuration changes, status updates.

Fields:

name - Change description
description - Details of the change
change_type - commit, field_update, status_change
event_date - When the change occurred

Example:

{
  "type": "CHANGE",
  "name": "Issue #123: Status changed to In Progress",
  "description": "Status: Backlog → In Progress (by Alice)",
  "change_type": "field_update",
  "event_date": "2024-05-10"
}

PERSON

Team members, authors, decision makers.

Fields:

name - Person’s name
description - Role or title

Example:

{
  "type": "PERSON",
  "name": "Alice Chen",
  "description": "Senior Backend Engineer, Auth Team"
}

PROJECT

Initiatives, features, workstreams.

Fields:

name - Project name
description - Project overview
status - active, completed, archived

Example:

{
  "type": "PROJECT",
  "name": "Auth Service Migration",
  "description": "Migrate from legacy auth to OAuth 2.0",
  "status": "active"
}

COMPONENT

Systems, services, modules, infrastructure.

Fields:

name - Component name
description - What it does

Example:

{
  "type": "COMPONENT",
  "name": "User Service",
  "description": "Handles user profiles, preferences, and authentication"
}

Relationship Types

Entities connect through typed relationships:

Type	Description	Example
`DECIDED_BY`	Who made a decision	Decision → Person
`AUTHORED_BY`	Who wrote a document	Document → Person
`PART_OF`	Component hierarchy	Change → Document
`RELATES_TO`	General association	Decision → Component
`SUPERSEDES`	Decision lineage	New Decision → Old Decision
`DEPENDS_ON`	Dependency chain	Component → Component
`IMPLEMENTS`	Decision realization	Component → Decision

Supersession

The SUPERSEDES relationship is special - it tracks decision evolution:

┌─────────────────┐
│ Use JWT Tokens  │  (2024-12)
│ (current)       │
└────────┬────────┘
         │ SUPERSEDES
         ▼
┌─────────────────┐
│ Use Session     │  (2024-06)
│ Cookies         │
└────────┬────────┘
         │ SUPERSEDES
         ▼
┌─────────────────┐
│ Use Basic Auth  │  (2024-01)
│ (original)      │
└─────────────────┘

Query this chain with teamloop_timeline using entity_id.

Building Your Graph

Automatic Extraction

When you query with teamloop_query, results include extraction instructions. Claude will suggest entities to create:

Found 5 results...

## Extraction Instructions
Based on these results, consider extracting:
- DECISION: "Adopt microservices architecture"
- COMPONENT: "Order Service"
- PERSON: "Bob (author)"

Manual Extraction

Use teamloop_save_knowledge to explicitly create entities:

teamloop_save_knowledge:
  entities:
    - type: DECISION
      name: "Use GraphQL for mobile API"
      rationale: "Better mobile performance with field selection"
      event_date: "2024-08-15"
  relationships:
    - source_name: "Use GraphQL for mobile API"
      source_type: DECISION
      target_name: "Mobile Team"
      target_type: PROJECT
      relationship_type: PART_OF

Semantic Search

All entities are embedded for semantic search:

Queries match by meaning, not just keywords
“database” finds “PostgreSQL”, “MySQL”, “data storage”
Similarity scores rank results

Temporal Metadata

Every entity tracks time:

Field	Description
`event_date`	When the event occurred (from source)
`created_at`	When added to TeamLoop
`updated_at`	Last modification
`valid_from`	Start of validity window
`valid_to`	End of validity (for superseded)

This enables:

Point-in-time queries (as_of)
Evolution tracking (from_date to to_date)
Comparison (date_a vs date_b)

Best Practices

1. Always Include event_date

{
  "type": "DECISION",
  "name": "Adopt Kubernetes",
  "event_date": "2024-03-15"  // Critical for temporal queries!
}

2. Use Source Attribution

{
  "source_url": "https://github.com/...",
  "source_integration": "github",
  "source_external_id": "issue-123"
}

3. Create Relationships

Isolated entities are less useful. Connect them:

{
  "relationships": [
    {
      "source_name": "New Decision",
      "source_type": "DECISION",
      "target_name": "Old Decision",
      "target_type": "DECISION",
      "relationship_type": "SUPERSEDES"
    }
  ]
}

4. Use Appropriate Types

DECISION for choices, not documents
DOCUMENT for artifacts, not decisions within them
CHANGE for modifications, not new entities

Querying the Graph

Once built, query your knowledge:

# Semantic search
teamloop_query:
  query: "authentication decisions"

# Timeline view
teamloop_timeline:
  query: "auth"

# Point-in-time
teamloop_query:
  query: "auth"
  mode: "as_of"
  as_of: "2024-01-01"

Next Steps

Subgraphs - Organize entities into collections
Synthesis - Generate documents from knowledge
MCP Tools Reference - All available tools