Skip to content

Team Collaboration

Jump to bottom
Chris & Mike edited this page Apr 21, 2026 · 19 revisions

Team Collaboration

Redesigned in v2.1.0

Overview

Memory Journal supports team collaboration through a dedicated team database with separate tools, resources, and author attribution. Team entries live in their own SQLite database, completely independent from your personal journal.

Key Concepts

  • Separate database — Team entries are stored in a dedicated file configured via TEAM_DB_PATH
  • Author attribution — Every team entry records who created it
  • Dedicated tools — 25 tools across 9 sub-categories for team operations
  • Team resources — 4 read-only resources for browsing team data and flag status
  • Cross-DB search — search_entries and search_by_date_range automatically merge team results with a source marker

🔧 Configuration

Environment Variables

Variable Description Default
TEAM_DB_PATH Absolute path to the team database file (none — team disabled)
TEAM_AUTHOR Override author name for team entries git config user.name

⚠️ Security Warning: Because TEAM_DB_PATH is accessed by multiple users or processes, it must be placed on a secure shared volume with strict access controls to prevent unauthorized data access or modification.

MCP Client Configuration

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "env": {
        "DB_PATH": "./data/memory_journal.db",
        "TEAM_DB_PATH": "./data/team.db",
        "TEAM_AUTHOR": "Alice",
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Docker

environment:
  - TEAM_DB_PATH=/data/team.db
  - TEAM_AUTHOR=Alice
volumes:
  - ./data:/data

Note

If TEAM_DB_PATH is not set, all 25 team tools and 4 team resources return structured errors indicating team collaboration is disabled. No other functionality is affected.

🛠️ Tools (25)

Core (4)

team_create_entry

Create an entry in the team database with author attribution.

Parameters:

Parameter Type Required Description
content string ✅ Entry content (1–50,000 chars)
author string ❌ Override author (default: auto-detected)
entry_type string ❌ Entry type (default: personal_reflection)
tags string[] ❌ Tags to attach
significance_type string ❌ Significance marker
issue_number number ❌ Link to GitHub issue (auto-populates issueUrl)
pr_number number ❌ Link to GitHub PR
project_number number ❌ Link to GitHub Project

Author Detection Priority:

  1. Explicit author parameter (if provided)
  2. TEAM_AUTHOR environment variable
  3. git config user.name
  4. "unknown" (fallback)

Example:

team_create_entry({
  content:
    "Decision: Switched to event-driven architecture for order processing.",
  entry_type: "project_decision",
  tags: ["architecture", "decisions"],
  issue_number: 42,
});

Response:

{
  "success": true,
  "entry": {
    "id": 15,
    "content": "Decision: Switched to event-driven architecture...",
    "entry_type": "project_decision",
    "timestamp": "2026-03-05T19:00:00.000Z",
    "tags": ["architecture", "decisions"],
    "author": "Alice",
    "issueUrl": "https://github.com/org/repo/issues/42"
  },
  "author": "Alice"
}

team_get_recent

Retrieve recent entries from the team database.

Parameters:

Parameter Type Required Description
limit number ❌ Max entries to return (default: 10)
sort_by string ❌ "timestamp" (default) or "importance" — when "importance", entries include importanceScore

Example:

team_get_recent({ limit: 5 });

Response:

{
  "entries": [
    {
      "id": 15,
      "content": "Decision: Switched to event-driven architecture...",
      "entry_type": "project_decision",
      "timestamp": "2026-03-05T19:00:00.000Z",
      "tags": ["architecture"],
      "author": "Alice"
    }
  ],
  "count": 1
}

team_get_entry_by_id

Retrieve a specific team entry with relationships and importance scoring.

Parameters:

Parameter Type Required Description
entry_id number ✅ ID of the team entry
include_relationships boolean ❌ Include linked entries (default: true)

Example:

team_get_entry_by_id({ entry_id: 15 });

team_list_tags

List all tags used in the team database with usage counts.

Parameters: None

Response:

{
  "success": true,
  "tags": [
    { "name": "architecture", "count": 12 },
    { "name": "decisions", "count": 8 }
  ],
  "count": 2
}

Search (2)

team_search

Search team entries by text, tags, or both.

Parameters:

Parameter Type Required Description
query string ❌ Full-text search query
tags string[] ❌ Filter by tags
limit number ❌ Max results (default: 10)
sort_by string ❌ "timestamp" (default) or "importance"

If neither query nor tags is provided, falls back to returning recent entries.

Examples:

// Text search
team_search({ query: "authentication" });

// Tag filter
team_search({ tags: ["architecture", "security"] });

// Combined
team_search({ query: "JWT", tags: ["authentication"], limit: 5 });

team_search_by_date_range

Search team entries within a date range with optional filters.

Parameters:

Parameter Type Required Description
start_date string ✅ Start date (YYYY-MM-DD)
end_date string ✅ End date (YYYY-MM-DD)
entry_type string ❌ Filter by entry type
tags string[] ❌ Filter by tags
limit number ❌ Max results (default: 50)
sort_by string ❌ "timestamp" (default) or "importance"

Example:

team_search_by_date_range({
  start_date: "2026-03-01",
  end_date: "2026-03-31",
  tags: ["architecture"],
});

Admin (3)

team_update_entry

Update an existing team entry.

Parameters:

Parameter Type Required Description
entry_id number ✅ ID of entry to update
content string ❌ New content
entry_type string ❌ New entry type
tags string[] ❌ Replace tags (not additive)

Example:

team_update_entry({
  entry_id: 15,
  content: "Updated: Using RabbitMQ with 5-retry policy",
  tags: ["architecture", "decisions", "verified"],
});

team_delete_entry

Permanently delete a team entry.

Parameters:

Parameter Type Required Description
entry_id number ✅ ID of entry to delete

team_merge_tags

Merge a source tag into a target tag across all team entries.

Parameters:

Parameter Type Required Description
source_tag string ✅ Tag to merge from (deleted)
target_tag string ✅ Tag to merge into (kept)

Response:

{
  "success": true,
  "message": "Merged tag 'arch' into 'architecture'",
  "entriesUpdated": 5,
  "sourceDeleted": true
}

Analytics (3)

team_get_statistics

Get team database statistics including entry counts, type breakdown, top tags, and author activity.

Parameters:

Parameter Type Required Description
group_by string ❌ Group by period: day, week, month (default: week)

Response:

{
  "success": true,
  "totalEntries": 42,
  "periodEntries": 12,
  "entryTypes": { "project_decision": 15, "technical_achievement": 12 },
  "topTags": [{ "name": "architecture", "count": 20 }],
  "authors": [
    { "author": "Alice", "count": 20 },
    { "author": "Bob", "count": 15 }
  ]
}

team_get_cross_project_insights

Analyze patterns across GitHub Projects tracked in the team database.

Parameters:

Parameter Type Required Description
start_date string ❌ Start date (YYYY-MM-DD)
end_date string ❌ End date (YYYY-MM-DD)
min_entries integer ❌ Minimum entries to include a project (default: 3)

Example:

team_get_cross_project_insights({
  start_date: "2026-01-01",
  end_date: "2026-03-31",
  min_entries: 1,
});

Response:

{
  "project_count": 3,
  "total_entries": 28,
  "projects": [
    {
      "project_number": 2,
      "entry_count": 15,
      "entry_types": { "project_decision": 8, "technical_achievement": 7 },
      "date_range": { "first": "2026-01-05", "last": "2026-03-18" }
    }
  ]
}

team_get_collaboration_matrix

Evaluate team health and interactions by generating a matrix of cross-author interactions based on relationship data.

Parameters:

Parameter Type Required Description
start_date string ❌ Start date (YYYY-MM-DD)
end_date string ❌ End date (YYYY-MM-DD)

Example:

team_get_collaboration_matrix({
  start_date: "2026-01-01",
  end_date: "2026-03-31"
});

Response:

{
  "matrix": {
    "Alice": { "Bob": 2, "Carol": 1 },
    "Bob": { "Alice": 1 }
  },
  "density": 0.35,
  "healthAssessment": "Strong cross-collaboration between Alice and Bob."
}

Vector Search (4)

team_semantic_search

Search team entries using ML-powered semantic similarity.

Parameters:

Parameter Type Required Description
query string ✅ Search query
limit integer ❌ Max results (default: 10)
similarity_threshold float ❌ Min similarity 0.0–1.0 (default: 0.25)
is_personal boolean ❌ Filter by personal vs project

Example:

team_semantic_search({
  query: "authentication architecture decisions",
  limit: 5,
  similarity_threshold: 0.4,
});

Response:

{
  "query": "authentication architecture decisions",
  "entries": [
    {
      "id": 15,
      "content": "Decision: Switched to event-driven architecture...",
      "entry_type": "project_decision",
      "timestamp": "2026-03-05T19:00:00.000Z",
      "tags": ["architecture"],
      "author": "Alice",
      "similarity": 0.687
    }
  ],
  "count": 1
}

team_get_vector_index_stats

Get statistics about the team vector index including entry counts and model information.

Parameters: None

Response:

{
  "available": true,
  "itemCount": 42,
  "modelName": "all-MiniLM-L6-v2",
  "dimensions": 384,
  "success": true
}

team_rebuild_vector_index

Rebuild the team's semantic search vector index from all entries.

Parameters: None

Response:

{
  "success": true,
  "entriesIndexed": 42
}

team_add_to_vector_index

Add or re-index a specific team entry in the vector index.

Parameters:

Parameter Type Required Description
entry_id integer ✅ ID of team entry to index

Response:

{
  "success": true,
  "entryId": 15
}

Relationships (2)

team_link_entries

Create a typed relationship between two team entries.

Parameters:

Parameter Type Required Description
from_entry_id number ✅ Source entry ID
to_entry_id number ✅ Target entry ID
relationship_type string ❌ Type: references, implements, clarifies, etc. (default: references)
description string ❌ Description of the relationship

team_visualize_relationships

Generate a Mermaid diagram of team entry relationships.

Parameters:

Parameter Type Required Description
entry_id number ❌ Root entry for visualization
tag string ❌ Filter entries by tag
depth number ❌ Traversal depth 1–5 (default: 2)

Export (1)

team_export_entries

Export team entries to JSON or Markdown.

Parameters:

Parameter Type Required Description
format string ❌ json or markdown (default: json)
start_date string ❌ Start date (YYYY-MM-DD)
end_date string ❌ End date (YYYY-MM-DD)
entry_type string ❌ Filter by entry type
tags string[] ❌ Filter by tags
limit number ❌ Max entries (default: 100, max: 5000)

Example:

team_export_entries({
  format: "markdown",
  start_date: "2026-03-01",
  end_date: "2026-03-31",
  tags: ["architecture"],
});

Backup (2)

team_backup

Create a timestamped backup of the team database.

Parameters:

Parameter Type Required Description
name string ❌ Custom backup name (default: auto-timestamp)

Response:

{
  "success": true,
  "filename": "team-backup-2026-03-20.db",
  "path": "/data/backups/team-backup-2026-03-20.db",
  "sizeBytes": 524288
}

team_list_backups

List all available team database backup files.

Response:

{
  "success": true,
  "backups": [
    {
      "filename": "team-backup-2026-03-20.db",
      "path": "/data/backups/team-backup-2026-03-20.db",
      "sizeBytes": 524288,
      "createdAt": "2026-03-20T10:30:00Z"
    }
  ],
  "total": 1,
  "backupsDirectory": "/data/backups"
}

### Flags — Hush Protocol (2)

#### pass_team_flag

Signal a team communication flag (blocker, needs_review, help_requested, fyi).

**Parameters:**

| Parameter       | Type   | Required | Description                                                       |
| --------------- | ------ | -------- | ----------------------------------------------------------------- |
| `flag_type`     | string | ✅       | Flag vocabulary term (e.g., `blocker`, `needs_review`)            |
| `message`       | string | ✅       | Description of the flag (1–49,000 chars)                          |
| `target_user`   | string | ❌       | Target user or team (with or without @)                           |
| `link`          | string | ❌       | Relatable URL or reference link                                   |
| `author`        | string | ❌       | Override author (default: auto-detected)                          |
| `project_number`| number | ❌       | Link to GitHub Project                                            |
| `issue_number`  | number | ❌       | Link to GitHub Issue                                              |

**Example:**

```javascript
pass_team_flag({
  flag_type: "blocker",
  message: "DB migration blocks deploy — schema conflict on users table",
  tags: ["deploy", "database"],
  issue_number: 42
});

Response:

{
  "success": true,
  "entry": {
    "id": 58,
    "content": "⚠️ [BLOCKER] DB migration blocks deploy \u2014 schema conflict on users table",
    "entry_type": "flag",
    "timestamp": "2026-04-12T17:00:00.000Z",
    "tags": ["deploy", "database"],
    "author": "Alice"
  },
  "flag_type": "blocker",
  "author": "Alice"
}

resolve_team_flag

Mark an active flag as resolved. Idempotent — resolving an already-resolved flag returns success.

Parameters:

Parameter Type Required Description
flag_id number ✅ ID of the flag entry to resolve
resolution string ❌ Resolution explanation

Example:

resolve_team_flag({
  flag_id: 58,
  resolution: "Resolved via PR #88 — migration reordered"
});

Response:

{
  "success": true,
  "entry": {
    "id": 58,
    "content": "⚠️ [BLOCKER] DB migration blocks deploy \u2014 schema conflict on users table",
    "entry_type": "flag",
    "timestamp": "2026-04-12T17:00:00.000Z",
    "tags": ["deploy", "database"],
    "author": "Alice"
  },
  "flag_type": "blocker",
  "resolved": true,
  "resolution": "Resolved via PR #88 — migration reordered"
}

Vocabulary: Configurable via FLAG_VOCABULARY env var (CLI: --flag-vocabulary). Default: blocker, needs_review, help_requested, fyi.

📡 Resources (4)

memory://team/recent

Returns the 10 most recent team entries, enriched with author information.

Response:

{
  "entries": [
    {
      "id": 15,
      "content": "...",
      "entry_type": "project_decision",
      "timestamp": "2026-03-05T19:00:00.000Z",
      "tags": ["architecture"],
      "author": "Alice"
    }
  ],
  "count": 1,
  "source": "team"
}

memory://team/statistics

Provides team database statistics including author breakdown.

Response:

{
  "configured": true,
  "totalEntries": 42,
  "entriesByType": {
    "project_decision": 15,
    "technical_achievement": 12,
    "learning": 8,
    "bug_fix": 7
  },
  "authors": [
    { "author": "Alice", "count": 20 },
    { "author": "Bob", "count": 15 },
    { "author": "Carol", "count": 7 }
  ],
  "source": "team"
}

memory://flags

Active (unresolved) team flags dashboard. Returns all flags where auto_context.resolved is false.

Response:

{
  "activeFlags": [
    {
      "id": 58,
      "flag_type": "blocker",
      "message": "DB migration blocks deploy",
      "author": "Alice",
      "createdAt": "2026-04-12T17:00:00.000Z"
    }
  ],
  "count": 1
}

memory://flags/vocabulary

Returns the configured flag vocabulary terms.

Response:

{
  "vocabulary": ["blocker", "needs_review", "help_requested", "fyi"],
  "source": "default"
}

🔍 Cross-Database Search

When TEAM_DB_PATH is configured, the standard search tools automatically merge results from both databases:

search_entries

search_entries({ query: "authentication" });

Results include a source marker on each entry:

{
  "entries": [
    { "id": 42, "content": "...", "source": "personal" },
    { "id": 15, "content": "...", "source": "team", "author": "Alice" }
  ]
}

search_by_date_range

search_by_date_range({
  start_date: "2026-01-01",
  end_date: "2026-03-31",
});

Team entries are merged into results with source: "team" markers.

📊 Integration Points

Team data is surfaced in several existing resources:

Resource Team Integration
memory://briefing Includes "Team DB" row with team entry count and active flags in the session table
memory://health Includes teamDatabase block with configured, entryCount, authors

🎨 Use Cases

Architecture Decisions

team_create_entry({
  content:
    "Decision: Using microservices for the payment system. Rationale: Better scalability, independent deployment.",
  entry_type: "project_decision",
  tags: ["architecture", "microservices", "payments"],
  significance_type: "technical_breakthrough",
});

Implementation Notes

team_create_entry({
  content:
    "Completed payment gateway integration. Webhook endpoints at /api/webhooks/stripe, retry with exponential backoff.",
  entry_type: "technical_achievement",
  tags: ["implementation", "payments", "stripe"],
  project_number: 2,
});

Bug Investigation Results

team_create_entry({
  content:
    "Root cause: Race condition in concurrent transaction handling. Fixed with database-level locking. See PR #85.",
  entry_type: "bug_fix",
  tags: ["debugging", "payments", "concurrency"],
  pr_number: 85,
});

Session Handoffs

// Triggered seamlessly via the `/team-session-summary` prompt
team_create_entry({
  content:
    "Session summary: Integrated payment gateway. Pending: Add tests for webhook retries. Next up: Verify Stripe dashboard events.",
  entry_type: "retrospective",
  tags: ["session-summary", "payments"],
  significance_type: "milestone",
});

🔒 Security & Privacy

Separation Model

  • Personal database (DB_PATH) — Your private journal, never shared
  • Team database (TEAM_DB_PATH) — Shared entries with author attribution
  • No cross-contamination — Tools operate on one database at a time; only search merges results read-only
  • Author transparency — Every team entry records who created it

Access Control

  • Control access by managing who can read/write the team database file
  • In Git-based workflows, use repository permissions
  • In Docker, mount the team DB as a shared volume with appropriate permissions
  • Never store sensitive personal data in the team database

🔍 Troubleshooting

Team Database Not Configured

Error: "Team database not configured. Set TEAM_DB_PATH environment variable to enable team collaboration."

Solution: Add TEAM_DB_PATH to your MCP client configuration pointing to a writable file path. The database file is created automatically on first use.

Schema Migration

If you encounter "no such column" errors after upgrading, the server automatically detects and adds missing columns to existing team databases. Restart the MCP server to trigger migration.

Author Shows as "unknown"

Cause: Neither TEAM_AUTHOR env var nor git config user.name is set.

Solution:

# Option 1: Set env var
export TEAM_AUTHOR="Your Name"

# Option 2: Configure Git
git config --global user.name "Your Name"

📚 Related Documentation

Questions? See Troubleshooting or open an issue on GitHub.

🏠 Home

Getting Started

Core Features

Knowledge Graph

GitHub Integration

Workflows

Deployment

Architecture

Clone this wiki locally