Journal

Journal entries let you record freeform thoughts, decisions, and observations that connect to your existing knowledge graph. Unlike raw entity extraction, journaling preserves your own voice and reasoning while still participating in search, linking, and temporal queries.

Why Journal?

Knowledge graphs are great at storing structured facts, but not everything fits neatly into entities and relationships. You might want to capture:

• A decision and its rationale before the formal ADR exists
• Open questions you want to revisit later
• Planning notes for an upcoming sprint or initiative
• Reflections on how a project evolved over time

Journal entries bridge this gap. They live inside the knowledge graph as first-class entities with embeddings, so they show up in semantic search and can link to the entities they reference.

Creating Entries

Every journal entry has a title and content. You can optionally classify it with a mood and organize it with tags.

Mood Classification

Mood categorizes the intent of your entry:

Mood	Use case
reflection	Looking back at what happened and why
planning	Forward-looking notes about what to do next
decision	Capturing a choice and its reasoning
note	General-purpose observation or context
question	Something unresolved you want to track

Mood is optional. If omitted, the entry is unclassified.

Tags

Tags are freeform strings for organizing entries. Use them for project names, sprints, themes, or anything that helps you filter later.

tags: ["architecture", "q1-planning", "auth-service"]

You can retrieve all tags in use via the GET /v1/journal/tags endpoint to see what categories already exist.

Entity Linking

The most powerful aspect of journal entries is their connection to the knowledge graph. Entries can link to any existing entity — decisions, people, components, documents — creating a web of context around your notes.

Auto-Linking

When auto_link is enabled (the default), TeamLoop scans your entry content and automatically links to entities it recognizes. This uses two strategies:

1. Exact match — If an entity name (3+ characters) appears verbatim in your content, it links with 0.9 confidence.
2. Semantic similarity — If embeddings are available, the content is compared against entity embeddings. Matches with 0.7+ confidence are linked.

Only high-confidence matches (>= 0.7) are auto-linked. Lower-confidence suggestions are available via the link suggestion endpoint.

Manual Linking

You can also specify entity IDs explicitly when creating or updating an entry. Manual and auto-linked entities are merged — duplicates are deduplicated automatically.

Link Suggestions

Not sure which entities to link? The suggestion endpoint analyzes your content and returns ranked candidates:

POST /v1/journal/suggest-links

{
  "content": "We discussed the auth service migration with Sarah...",
  "limit": 10
}

Each suggestion includes:

• entity_id — The entity to link
• entity_name and entity_type — For display
• confidence — 0.0 to 1.0 score
• reason — Either exact_match or semantic_similarity

Searching Entries

Text Search

List entries with text filtering using the search query parameter. This does case-insensitive substring matching against titles and content.

GET /v1/journal?search=authentication

Tag Filtering

Filter by tags using comma-separated values:

GET /v1/journal?tags=architecture,q1-planning

Tag filtering uses array overlap — entries matching any of the specified tags are returned.

Mood Filtering

Filter by mood classification:

GET /v1/journal?mood=decision

Date Range

Filter entries by date range:

GET /v1/journal?start_date=2025-01-01&end_date=2025-03-31

Semantic Search

Journal entries are embedded at creation time (title + content), so they participate in semantic search across the knowledge graph. When you use teamloop_recall or teamloop_get_context, relevant journal entries surface alongside structured entities.

Pagination

All list queries support limit (max 100, default 50) and offset parameters. The response includes total count and has_more flag.

MCP Tool

teamloop_create_journal_entry

Create entries directly from an AI assistant conversation using the MCP tool.

Parameters:

Parameter	Type	Required	Description
title	string	Yes	Title for the journal entry
content	string	Yes	The entry content — thoughts, notes, or context
mood	string	No	Entry type: reflection, planning, decision, note, question
tags	array	No	Tags to categorize the entry
link_entity_ids	array	No	Entity IDs to explicitly link
auto_link	boolean	No	Automatically find and link related entities (default: true)

Example usage in conversation:

User: "We decided to use PostgreSQL instead of MongoDB for the new service"

AI uses teamloop_create_journal_entry:
  title: "Database decision for new service"
  content: "We decided to use PostgreSQL instead of MongoDB..."
  mood: "decision"
  tags: ["database", "new-service"]
  auto_link: true

The tool returns confirmation with the entry ID, mood, tags, and number of linked entities.

REST API

All endpoints require authentication and use the /v1/journal prefix.

Method	Endpoint	Description
GET	/v1/journal	List entries with filtering and pagination
POST	/v1/journal	Create a new entry
GET	/v1/journal/tags	Get all unique tags in use
GET	/v1/journal/:id	Get a single entry by ID
PUT	/v1/journal/:id	Update an entry
DELETE	/v1/journal/:id	Delete an entry
POST	/v1/journal/:id/links	Add entity links to an existing entry
POST	/v1/journal/suggest-links	Get link suggestions for content

Create Entry

POST /v1/journal

{
  "title": "Sprint 4 Retrospective",
  "content": "The auth migration went smoother than expected...",
  "mood": "reflection",
  "tags": ["sprint-4", "retrospective"],
  "linked_entity_ids": ["uuid-of-auth-migration"],
  "auto_link": true
}

Update Entry

PUT /v1/journal/:id

{
  "title": "Updated title",
  "content": "Revised content...",
  "mood": "decision",
  "tags": ["updated-tags"]
}

All fields are optional on update. Only provided fields are changed.

Add Links

POST /v1/journal/:id/links

{
  "entity_ids": ["uuid-1", "uuid-2"]
}

New links are merged with existing ones. Duplicates are ignored.

Tips

• Journal as you go — Capture decisions and context immediately rather than reconstructing them later. The value of a journal entry is highest when it’s written close to the event.
• Use mood consistently — Filtering by mood is most useful when you apply it consistently. A decision mood entry should capture a specific choice; use note for general observations.
• Let auto-link work — Keep auto_link enabled by default. It connects your entries to the graph automatically, making them discoverable when you later recall or get context on related topics.
• Combine with recall — Use teamloop_recall to check what you already know before writing a journal entry. This avoids duplicating context and helps you build on prior entries.
• Tag for retrieval — Think of tags as filters you will want later. Project names, sprint identifiers, and topic areas make good tags.