Skip to main content
Glama

Memory Journal MCP Server

GitHub npm Docker Pulls License: MIT Status MCP Registry Security GitHub Stars TypeScript Coverage E2E Tests Benchmarks CI

๐Ÿ“š Full Documentation (Wiki) โ€ข Changelog โ€ข Security โ€ข Release Article

TIP

Value Proposition Bridge disconnected AI sessions seamlessly. Enable persistent project memory instantly. Automate handoffs with robust GitHub integration. Eliminate AI amnesia today.

๐Ÿš€ Quick Deploy:

  • npm Package - npm install -g memory-journal-mcp (or pnpm add -g memory-journal-mcp)

  • Docker Hub - Alpine-based with full semantic search

๐Ÿง  Eliminate AI Amnesia

Large projects face a critical challenge. You lose context between sessions.

  • Stop Thread Amnesia - AI conversations start fresh. They ignore previous work.

  • Retain Deep Context - Decisions and code scatter across threads; Memory Journal preserves them automatically.

  • End Repeated Work - AI repeats failed solutions; persistent history tracks every prior attempt.

  • Prevent Context Overload - Manual history copying wastes tokens; dynamic briefings deliver targeted context automatically.

Memory Journal builds your project's long-term memory. It acts as a Project Context Graph for AI-assisted engineering. It bridges human workflows (Issues, PRs, Kanban, Milestones) with agent execution (Git, tests, decisions).


Experience true context-aware development:

  • "Why did we choose SQLite over Postgres for this service last month?" (Semantic search)

  • "Run the /issue-commander (triage workflow) on the top priority ticket in the Kanban board." (GitHub operations)

  • "Who has been touching the auth module recently, and what's our team collaboration density?" (Team analytics)

  • "Commit the changes and automatically generate a structured journal entry using the `--journal` wrapper flag." (Automated lifecycles)

  • "Draw a visual graph showing how my last 10 architectural decisions relate to each other." (Knowledge graph)

Comprehensive access to internal state via resources (memory://briefing, memory://workflows, memory://rules, memory://health, memory://help, memory://staleness, GitHub status/milestones, team stats, and metrics/latency). Dynamic repo variants also support cross-repo targeting (like memory://briefing/{+repo} or memory://kanban/{+repo}/{project_number}). Resources documentation โ†’


Related MCP server: claude-engram

๐ŸŽฏ What Sets Us Apart

MCP Tools ยท Workflow Prompts ยท Resources ยท Tool Groups ยท Code Mode ยท GitHub Commander (Issue Triage, PR Review, Milestone Sprints, Security/Quality/Perf Audits) ยท GitHub Integration (Issues, PRs, Actions, Kanban, Milestones, Insights) ยท Team Collaboration (Shared DB, Vector Search, Cross-Project Insights)

Feature

Description

Session Intelligence

Auto-query project history, create checkpoints, and hand off context between sessions automatically.

GitHub Integration

Manage Issues, PRs, Actions, Kanban boards, and milestones. Access Copilot reviews and repository insights.

Dynamic Project Routing

Switch contexts seamlessly and access CI/Issue tracking across multiple repositories from a single server instance.

Knowledge Graphs

Link specifications, implementations, tests, and PRs visually using Mermaid diagrams.

Hybrid Search

Find entries instantly using a blend of keyword, semantic, and date-range searches.

Code Mode

Execute multi-step operations efficiently in a sandboxed environment to reduce token usage.

Adaptive Session Briefing

Deliver real-time workspace context dynamically, including live CI health, local Git status, and unreleased changes.

Reports & Analytics

Generate standups, retrospectives, PR summaries, digests, and period analyses.

Heuristic Scoring

Optimize context delivery by scoring entries based on veracity and impact.

Team Collaboration

Share databases across teams with cross-project insights, author attribution, and role-based access control.

Data Interoperability

Export schemas safely, sync Markdown directories, and maintain a unified IO namespace.

Backup & Restore

Secure data with automated scheduling, retention policies, and one-command restores.

Auto-Pruning

Soft-delete low-value entries automatically to maintain search relevance over long-running projects.

Security & Transport

Ensure secure connections with OAuth 2.1, Streamable HTTP, rate limiting, and SQL injection prevention.

Structured Error Handling

Provide agents with classification, remediation hints, and recoverability signals on every tool call.

Agent Collaboration

Share context between IDE agents and Copilot. Search review findings and let agents suggest reusable rules.

Native Agent Skills

Establish permanent AI behavior and architecture rules using bundled foundational coding paradigms.

GitHub Commander

Audit code, triage issues, review PRs, and run sprint milestones via automated pipeline skills.


Isolate Environments with Multi-Tenancy

Memory Journal supports multi-tenancy out of the box via the workspace_id construct, acting as a strict isolation barrier for multiple journals sharing the same SQLite database file.

  • Auto-Resolution: When workspace_id is omitted, the server automatically resolves the target workspace. It matches project_number against PROJECT_REGISTRY, checks content/tag keyword aliases, or inspects process.cwd() before falling back to DEFAULT_WORKSPACE_ID (default: default).

  • Data Partitioning & Cross-Workspace Queries: Core CRUD, Soft-Delete/Restore, FTS5 Search, Vector Semantic Search (semantic_search), and Analytics tools enforce workspace_id isolation end-to-end. Read and search tools accept workspace_id: "*" to query across all workspaces. External write and mutation paths reject wildcard overrides.

  • Immutability & Controlled Migration: Entries receive a workspace_id upon creation that standard updates cannot overwrite directly. To migrate an entry across workspaces, call update_entry with workspace_id: "*" and target_workspace_id.

  • Server Config: Set --default-workspace-id (or the DEFAULT_WORKSPACE_ID environment variable) to configure the default fallback workspace for the server instance. This lets you run multiple isolated journal interfaces on a single physical database.


flowchart TB
    subgraph Session["๐Ÿค– AI Session Start"]
        Briefing["๐Ÿ“‹ Read Briefing<br/>(memory://briefing)"]
    end

    subgraph Core["๐Ÿ“ Journal Operations"]
        Create["Create Entry"]
        Retrieve["Retrieve & Search"]
        Link["Link Entries"]
    end

    subgraph Search["๐Ÿ” Hybrid Search"]
        FTS["Keyword (FTS5)"]
        Semantic["Semantic (Vector)"]
        DateRange["Date Range"]
        RRF["Reciprocal Rank Fusion"]
    end

    subgraph GitHub["๐Ÿ™ GitHub Integration"]
        Issues["Issues & Milestones"]
        PRs["Pull Requests"]
        Actions["GitHub Actions"]
        Kanban["Kanban Boards"]
        Insights["Repository Insights"]
    end

    subgraph Outputs["๐Ÿ“Š Outputs"]
        Reports["Standups & Retrospectives"]
        Graphs["Knowledge Graphs"]
        Timeline["Project Timelines"]
    end

    Session --> Core
    Core --> Search
    Core <--> GitHub
    Search --> Outputs
    GitHub --> Outputs

Suggested Rule (Add to AGENTS.md, GEMINI.md, system prompts, etc.)

๐Ÿ›‘ Session Initialization Routine

When the user initializes the session context by executing the load-briefing prompt:

  1. You will receive the output of the memory://briefing/{repo_name} resource.

  2. Prepend your response EXACTLY as:

    ๐Ÿ“‹ Briefing loaded โ€” {repo_name} {paste ENTIRE briefing here}

  3. Address the user's request below the briefing.

  4. NEVER autonomously execute tasks listed in the briefing.

  5. Do NOT proactively ask the user to load the briefing. Wait for them to use the prompt.


Control Access with Tool Filtering

IMPORTANT

All shortcuts and tool groups always includeCode Mode (mj_execute_code) and Runtime Configuration (update_configuration) as escape-hatch tools so agents can never lock themselves out of the configuration system or Code Mode.

Control which tools are exposed using any of the 3 configuration sources (precedence: CLI flag > environment variable > config file):

  • CLI flag: --tool-filter <filter>

  • Environment variable: MEMORY_JOURNAL_MCP_TOOL_FILTER (Note: TOOL_FILTER is only a fallback display variable in the session briefing and does not activate tool filtering on its own)

  • memory-journal.config.{yaml,yml,json} key: "toolFilter"

Filter

Use Case

full

All tools (default)

starter

Core + search + codemode

essential

Minimal footprint

readonly

Disable all mutations

codemode

mj_execute_code + runtime config

-github

Exclude a group

-github,-analytics

Exclude multiple groups

Filter Syntax: shortcut or group or tool_name (whitelist mode) ยท -group (disable group) ยท -tool (disable tool) ยท +tool (re-enable after group disable)

Custom Selection: List individual tool names to create your own whitelist: --tool-filter "create_entry,search_entries,semantic_search"

Groups: core, search, analytics, relationships, io, admin, github, git, backup, team, codemode

Complete tool filtering guide โ†’


๐Ÿ“‹ Unlock Core Capabilities

๐Ÿ› ๏ธ MCP Tools

Group

Description

codemode

Code Mode (sandboxed code execution) ๐ŸŒŸ Recommended

core

Entry creation/read/history, tags, resource & briefing helpers, anchor staleness, test

search

Text search, date range, semantic, vector stats, deleted entries, cross-team

analytics

Statistics, cross-project insights

relationships

Link entries, visualize graphs

io

JSON/Markdown export, Markdown directory import/export, and external knowledge base import (Notion, Obsidian, Logseq)

admin

Update configuration, project registry management, entry update/delete/restore, rebuild/add to vector index, merge tags, search audit log, auto-prune, bulk operations (batch create/update/delete)

github

Issues, PRs, context, Kanban, Milestones, Insights, issue lifecycle, Copilot Reviews

git

Commit history, search, release info, patterns, staleness checks

backup

Backup, list, restore, cleanup

team

CRUD, search, stats, relationships, IO (Markdown & external import/export), backup, vector search, cross-project insights, matrix, RBAC member management, author aliases (requires TEAM_DB_PATH)

Complete tools reference โ†’

๐ŸŽฏ Workflow Prompts

Specialized workflow prompts cover session briefing, standup & retro prep, goal tracking, PR & issue command, session summaries, and journal optimization. Additional prompts support CMS REM supervision, adversarial plan reviews, code & security audits, secure commit workflows, and anti-hallucination healing. Complete prompts guide โ†’

๐Ÿ“ก Resources

See the Complete resources guide โ†’ for the full list of dynamic context resources, including memory://briefing, memory://instructions, GitHub integration endpoints, telemetry metrics, and templated views.

  • Dynamic Resource Templates: Resources memory://briefing/{+repo}, memory://agent-context/{+repo}, memory://agent-id/{+repo}, memory://actions/recent/{+repo}, memory://github/status/{+repo}, memory://github/milestones/{+repo}, memory://milestones/{+repo}/{number}, and memory://kanban/{+repo}/{project_number} accept an RFC 6570 {+repo} path parameter for targeted project context.


โšก Code Mode: Maximum Efficiency (90% Token Savings)

Code Mode (mj_execute_code) reduces token usage by up to 90% and is included by default in all presets. Instead of spending thousands of tokens on sequential tool calls, AI agents use a single sandboxed execution to reason faster.

Code executes in a pre-warmed worker_threads V8 isolate pool + secondary vm.createContext boundary designed as a secure multi-tenant process isolation environment. All mj.* API calls execute against the journal within the sandbox, providing:

  • V8 code generation restrictions โ€” eval() and Function() construction from strings disabled at the V8 engine level via codeGeneration: { strings: false, wasm: false }

  • Frozen prototypes & cross-realm constructor lockdown โ€” all built-in prototypes (Object, Function, Array, Error, etc.) and mj.* API bindings are frozen, and .constructor is neutered across Object, Function, AsyncFunction, GeneratorFunction, and AsyncGeneratorFunction prototypes in both the inner vm realm and outer worker realm to prevent dynamic constructor chain escapes

  • Single-pass lexical validation โ€” pre-validation rate-limiting and 50KB byte caps run before any code normalization, followed by a single-pass lexical comment/string scanner (preserving ${...} template expressions) and static rules blocking require(), import(), process, eval(), Reflect.*, Symbol.*, Object.getPrototypeOf/setPrototypeOf/defineProperty, new Proxy(), and filesystem/network access

  • Proxy constructor nullified โ€” Proxy: undefined in the sandbox prevents meta-object protocol abuse

  • Prototype-safe RPC allowlist โ€” host-side Object.hasOwn() validation, recursion-bounded argument normalization, and --tool-filter enforcement prevent workers from invoking unauthorized or filtered API methods

  • Rate limiting โ€” 60 executions per minute per client

  • Hard timeouts โ€” configurable execution limit (default 30s) with bounded async timer tracking (setTimeout/sleep capped and cleared on completion)

  • Egress boundary enforcement โ€” result serialization capped (default 100KB via CODE_MODE_MAX_RESULT_SIZE) with automatic payload compaction to prevent OOM via oversized payloads

  • Full API access โ€” all tool groups are available via mj.* (e.g., mj.core.createEntry(), mj.search.searchEntries(), mj.github.getGithubIssues())

  • Strict Readonly Contract โ€” Calling any mutation method under --tool-filter readonly safely halts the sandbox to prevent execution, returning a structured { success: false, error: "..." } response to the agent instead of a raw MCP protocol exception.

โšก Code Mode Minimal Surface (Maximum Token Savings)

Run with the codemode filter and --codemode-internal-full-access to expose only the escape-hatch tools (mj_execute_code and update_configuration) on the MCP tool list while retaining full internal access to the mj.* API inside the sandbox:

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "args": ["--tool-filter", "codemode", "--codemode-internal-full-access"]
    }
  }
}

This exposes only mj_execute_code and update_configuration to the client's tools/list, reducing tool schema overhead to the minimum while preserving full programmatic capability via mj.*. The agent writes JavaScript against the typed mj.* SDK โ€” composing operations across all tool groups and returning exactly the data it needs โ€” in one execution. This mirrors the Code Mode pattern pioneered by Cloudflare for their entire API: fixed token cost regardless of how many capabilities exist. Without --codemode-internal-full-access (or CODEMODE_INTERNAL_FULL_ACCESS=true), internal mj.* methods are scoped to the active --tool-filter.


๐Ÿš€ Quick Start & Deployment

Note: Configuration is resolved using strict precedence: CLI flags > Environment Variables > Config File > Defaults.

๐Ÿ› ๏ธ Debugging Configuration: Run memory-journal-mcp --dump-config (or pass --dump-config as an arg) to print the fully resolved configuration payload with automatically redacted secrets. This is the primary method for diagnosing overriding issues.

Configure Basics Quickly

๐Ÿ’ก Tip: Don't want to manually escape JSON strings for PROJECT_REGISTRY? Run npx memory-journal-mcp project create <name> --path <repo-path> [--number <project-number>] in your terminal to automatically bootstrap and update your MCP configuration!

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "PROJECT_REGISTRY": "{\"my-repo\":{\"path\":\"/path/to/your/git/repo\",\"project_number\":1}}",
        "ALLOWED_IO_ROOTS": "/path/to/your/git/repo"
      }
    }
  }
}

Power Up with Advanced Configuration

Showcasing the full power of the server, including Multi-Project Routing, Team Collaboration, Copilot awareness, and Context Injections.

๐Ÿ’ก Tip: Use npx memory-journal-mcp project create <name> --path <repo-path> [--number <project-number>] to easily configure multiple repositories into your PROJECT_REGISTRY without manual JSON escaping!

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "memory-journal-mcp",
      "args": ["--tool-filter", "codemode"],
      "env": {
        "DB_PATH": "/path/to/your/memory_journal.db",
        "TEAM_DB_PATH": "/path/to/shared/team.db",
        "GITHUB_TOKEN": "ghp_your_token_here",
        "PROJECT_REGISTRY": "{\"my-repo\":{\"path\":\"/path/to/repo\",\"project_number\":1},\"other-repo\":{\"path\":\"/path/to/other\",\"project_number\":5}}",
        "ALLOWED_IO_ROOTS": "/path/to/repo,/path/to/other,/path/to/your/skills",
        "AUTO_REBUILD_INDEX": "true",
        "CODEMODE_INTERNAL_FULL_ACCESS": "true",
        "BRIEFING_ENTRY_COUNT": "3",
        "BRIEFING_SUMMARY_COUNT": "1",
        "BRIEFING_INCLUDE_TEAM": "true",
        "BRIEFING_ISSUE_COUNT": "3",
        "BRIEFING_PR_COUNT": "3",
        "BRIEFING_PR_STATUS": "true",
        "BRIEFING_WORKFLOW_COUNT": "3",
        "BRIEFING_WORKFLOW_STATUS": "true",
        "BRIEFING_COPILOT_REVIEWS": "true",
        "RULES_FILE_PATH": "/path/to/your/RULES.md",
        "SKILLS_DIR_PATH": "/path/to/your/skills",
        "MEMORY_JOURNAL_WORKFLOW_SUMMARY": "/deploy: prod deployment | /audit: security scan",
        "AUDIT_LOG_PATH": "/path/to/your/mcp-audit.jsonl",
        "TEAM_AUTHOR": "your_username"
      }
    }
  }
}

๐Ÿ’ก Tip: Optimize your context window! Journal entries (BRIEFING_ENTRY_COUNT) capture frequent, granular actions (e.g. bug fixes, implementation steps). Session summaries (BRIEFING_SUMMARY_COUNT) surface high-level retrospectives meant to pass strategic context continuously across distinct AI sessions. Use both appropriately to keep the agent briefing highly focused!

๐Ÿ“‹ Customizing the Session Briefing

The memory://briefing resource is dynamically assembled at each session start to provide rich, token-efficient ambient context. By default, it automatically surfaces:

  • System State: Server version, capability statuses, resource/tool counts, test health, and memory://metrics/summary breadcrumbs.

  • Repository Context: Git working tree status, unreleased changes, exact code-map paths, and prioritized gatekeeper CI workflows.

  • Ambient Context: Active workspace paths, local time, analytics.

You control exactly what additional content your agent sees across three dimensions:

Dimension

Variables

What It Controls

Focus

MEMORY_JOURNAL_MCP_TOOL_FILTER (CLI: --tool-filter, config: "toolFilter")

Control tool exposure: full (default), starter, essential, readonly, codemode

Journal Content

BRIEFING_ENTRY_COUNT, BRIEFING_SUMMARY_COUNT, BRIEFING_COMMIT_COUNT, BRIEFING_IMPORTANCE_THRESHOLD, BRIEFING_INCLUDE_TEAM

How many recent entries, session summaries, commits, and whether team entries appear

GitHub Enrichment

BRIEFING_ISSUE_COUNT, BRIEFING_PR_COUNT, BRIEFING_PR_STATUS, BRIEFING_MILESTONE_COUNT, BRIEFING_WORKFLOW_COUNT, BRIEFING_WORKFLOW_STATUS, BRIEFING_COPILOT_REVIEWS

Issues, PRs, milestones, CI runs, and Copilot review state surfaced in the briefing

Context Injections: Set RULES_FILE_PATH and SKILLS_DIR_PATH to surface user rules and agent skills as companion resources (memory://rules, memory://skills) alongside the briefing.

Repo Targeting: In multi-repo setups, agents read memory://briefing/{+repo} to get a briefing scoped to a specific repository registered in PROJECT_REGISTRY.

Minimal (fast sessions) โ€” Reduce briefing to bare essentials for quick interactions:

"BRIEFING_ENTRY_COUNT": "1",
"BRIEFING_SUMMARY_COUNT": "0",
"MEMORY_JOURNAL_MCP_TOOL_FILTER": "essential"

Full Context (onboarding agents) โ€” Maximize context for agents unfamiliar with the project:

"BRIEFING_ENTRY_COUNT": "5",
"BRIEFING_SUMMARY_COUNT": "3",
"BRIEFING_INCLUDE_TEAM": "true",
"BRIEFING_ISSUE_COUNT": "5",
"BRIEFING_PR_COUNT": "3",
"BRIEFING_PR_STATUS": "true",
"BRIEFING_COPILOT_REVIEWS": "true",
"MEMORY_JOURNAL_MCP_TOOL_FILTER": "full"

DevOps-Heavy โ€” Emphasize CI/CD and GitHub state for infrastructure workflows:

"BRIEFING_WORKFLOW_COUNT": "5",
"BRIEFING_WORKFLOW_STATUS": "true",
"BRIEFING_ISSUE_COUNT": "3",
"BRIEFING_PR_COUNT": "3",
"BRIEFING_PR_STATUS": "true",
"BRIEFING_COPILOT_REVIEWS": "true"

Full briefing customization guide โ†’

Variants (modify the config above):

Variant

Change

Minimal (no GitHub)

Remove the env block entirely

npx (no install)

Replace "command" with "npx" and add "args": ["-y", "memory-journal-mcp"]

From source

Replace "command" with "node" and add "args": ["dist/cli.js"]

Code Mode minimal

Add "args": ["--tool-filter", "codemode", "--codemode-internal-full-access"] (mj_execute_code + update_configuration, all mj.* capabilities)

Docker

Replace "command" with "docker" and add "args": ["run", "-i", "--rm", "-v", "./data:/app/data", "-e", "GITHUB_TOKEN", "-e", "PROJECT_REGISTRY", "-e", "ALLOWED_IO_ROOTS", "writenotenow/memory-journal-mcp:latest"] (forward any "env" keys via -e <VAR>)

Team collaboration

Add "TEAM_DB_PATH": "./team.db" to env

Restart your MCP client and start journaling!

Connect Remotely with HTTP/SSE Transport

IMPORTANT

Security Posture: Stdio vs HTTP (Fail-Closed Startup Guards)

  • Stdio (Default): Runs implicitly within the secure boundaries of your local IDE or command-line environment. No explicit authentication is required because the execution context is already trusted (ALLOWED_IO_ROOTS defaults to fail-closed [] unless configured).

  • HTTP/SSE (--transport http): Exposes the server over a network socket and enforces three fail-closed startup guards:

    1. Mandatory Filesystem Boundary (ALLOWED_IO_ROOTS / --allowed-io-roots): Always required in HTTP mode so filesystem boundaries are explicitly declared.

    2. Mandatory Public Authentication: By default, HTTP binds ONLY to localhost and blocks wildcard CORS to prevent unauthorized access and CSRF attacks. Binding to a non-loopback address (--server-host 0.0.0.0) requires explicit authentication (MCP_AUTH_TOKEN / --auth-token or --oauth-enabled).

    3. Mandatory Public Origin for Non-Loopback OAuth (PUBLIC_ORIGIN / --public-origin): When --oauth-enabled is bound to a non-loopback address, --public-origin (PUBLIC_ORIGIN) is strictly required so RFC 9728 Protected Resource Metadata cannot be spoofed via Host headers.

For remote access or web-based clients, run the server in HTTP mode:

memory-journal-mcp --transport http --port 3000 --allowed-io-roots /path/to/allowed/dir

To bind to all interfaces (required for containers) and enable the automated proactive analytics scheduler (e.g. daily digest), you MUST provide both ALLOWED_IO_ROOTS and an authentication token:

export MCP_AUTH_TOKEN="your_secure_random_token"
export MCP_AUTH_SCOPES="full" # Defaults to "read" if omitted
export ALLOWED_IO_ROOTS="/path/to/allowed/dir"
memory-journal-mcp --transport http --port 3000 --server-host 0.0.0.0 --digest-interval 1440

Endpoints:

Endpoint

Description

Mode

GET /

Server info and available endpoints

Both

POST /mcp

JSON-RPC requests (initialize, tools/call, etc.)

Both

GET /mcp

SSE stream for server-to-client notifications

Stateful

DELETE /mcp

Session termination (204 No Content)

Both

GET / POST /sse

Legacy SSE connection & stateless/stateful POST (MCP 2024-11-05)

GET: Stateful / POST: Both

POST /messages

Legacy SSE message endpoint

Stateful

GET /health

Health check ({ status, timestamp })

Both

GET /metrics

Prometheus metrics export (requires flag)

Both

GET /.well-known/oauth-protected-resource

RFC 9728 Protected Resource Metadata (requires --oauth-enabled)

Both

Session Management: The server uses stateful sessions by default. Include the mcp-session-id header (returned from initialization) in subsequent requests.

  • OAuth 2.1 โ€” RFC 9728/8414, JWT/JWKS, granular scopes (opt-in via --oauth-enabled)

  • Comprehensive Security Headers โ€” CSP, HSTS (opt-in), X-Frame-Options, and more

  • Rate Limiting โ€” 100 req/min per subject/IP ยท CORS โ€” configurable multi-origin (exact-match) ยท 1MB body limit

  • Server Timeouts โ€” Request (120s), keep-alive (65s), headers (66s) ยท 404 handler ยท Cross-protocol guard

  • Build Provenance ยท SBOM ยท Supply Chain Attestations ยท Non-root execution

Example with curl:

Initialize session (returns mcp-session-id header):

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

List tools (with session):

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Stateless Mode (Serverless)

For serverless deployments (Lambda, Workers, Vercel), use stateless mode:

memory-journal-mcp --transport http --port 3000 --stateless --allowed-io-roots /path/to/projects

Mode

Progress Notifications

Legacy SSE

Serverless

Stateful (default)

โœ… Yes

โœ… Yes

โš ๏ธ Complex

Stateless (--stateless)

โŒ No

โŒ No

โœ… Native

Automated Scheduling (HTTP Only)

When running in HTTP/SSE mode, enable periodic maintenance jobs with CLI flags. These jobs run in-process on setInterval โ€” no external cron needed.

Note: These flags are ignored for stdio transport because stdio sessions are short-lived (tied to your IDE session). For stdio, use OS-level scheduling (Task Scheduler, cron) or run the backup/cleanup tools manually.

memory-journal-mcp --transport http --port 3000 \
  --allowed-io-roots /path/to/projects \
  --backup-interval 60 --keep-backups 10 \
  --vacuum-interval 1440 \
  --rebuild-index-interval 720

Flag

Default

Description

--backup-interval <min>

0 (off)

Create timestamped database backups and prune old ones automatically

--keep-backups <count>

5

Max backups retained during automated cleanup

--vacuum-interval <min>

0 (off)

Run PRAGMA optimize and flush database to disk

--rebuild-index-interval <min>

0 (off)

Full vector index rebuild to maintain semantic search quality

--report-interval <min>

0 (off)

Scheduled report generation interval in minutes

--report-webhook-url <url>

โ€”

HTTPS webhook URL for scheduled report delivery

--report-webhook-auth <header>

โ€”

Custom Authorization header for webhook requests

--report-content-type <type>

slack

Webhook payload format: slack, discord, or json (env: REPORT_CONTENT_TYPE)

--digest-interval <min>

0 (off)

Scheduled periodic digest analysis report

--auto-prune-interval <min>

0 (off)

Run autonomous garbage collection (archive, soft-delete, hard-delete)

--archive-older-than-days <days>

0 (off)

Auto-archive low-importance entries older than N days

--prune-older-than-days <days>

0 (off)

Auto soft-delete entries older than N days

--hard-delete-older-than-days <days>

0 (off)

Permanently purge soft-deleted entries older than N days

--prune-importance-threshold <score>

0.15

Max importance score (0.0โ€“1.0) eligible for archiving/pruning

--prune-dry-run

false

Log auto-prune candidates without mutating entries

--prune-exclude-tags <tags>

โ€”

Comma-separated tags exempt from auto-prune (archived always kept)

Each job is error-isolated โ€” a failure in one job won't affect the others. Scheduler status (last run, result, next run) is visible via memory://health.

Integrate Seamlessly with GitHub

The GitHub tools (get_github_issues, get_github_prs, etc.) auto-detect the repository from your git context when PROJECT_REGISTRY is configured or the MCP server is run inside a git repository.

Multi-Project Workflows: For agents to seamlessly support multiple projects, configure your PROJECT_REGISTRY (tip: use npx memory-journal-mcp project create <name> --path <repo-path> [--number <project-number>]).

Dynamic Context Resolution & Auto-Detection

When executing GitHub tools (issues, PRs, context, etc.), the server resolves repository context in this order:

  1. Dynamic Project Routing: If the agent passes a repo string that matches a key in your PROJECT_REGISTRY, the server dynamically mounts the physical directory mapped to that project. It executes git commands locally and automatically infers the owner.

  2. Explicit Override: If the agent provides both owner and repo explicitly, those values override auto-detection for API calls.

  3. Missing Context: Without PROJECT_REGISTRY or explicit parameters, the server blocks execution and returns {requiresUserInput: true} to prompt the agent. If an agent encounters this blocked state, it can seamlessly recover by invoking the mj.admin.registerProject() method via Code Mode to auto-configure the project registry on the fly.

Automatic Project Routing (Kanban / Issues)

When opening an issue or viewing/moving a Kanban card, the server needs a GitHub Project number. It determines this via:

  1. Exploring the raw project_number argument passed by the agent.

  2. Checking if the repo string precisely matches an entry in your PROJECT_REGISTRY, seamlessly mapping it to its pre-configured project_number.

  3. Falling back to the globally defined DEFAULT_PROJECT_NUMBER if set.

๐Ÿ” OAuth 2.1 Authentication

For production deployments, enable OAuth 2.1 authentication on the HTTP transport:

Component

Status

Description

Protected Resource Metadata

โœ…

RFC 9728 /.well-known/oauth-protected-resource

Auth Server Discovery

โœ…

RFC 8414 metadata discovery with caching

Token Validation

โœ…

JWT validation with JWKS support

Scope Enforcement

โœ…

Granular read, write, team, audit, admin, full scopes

HTTP Transport

โœ…

Streamable HTTP with OAuth middleware

Supported Scopes:

Scope

Tool Groups

read

core (read-only), search, analytics, relationships (visualize_relationships), io (export_entries), git

write

github (+ all read groups and create_entry / create_entry_minimal / link_entries / mark_anchors_stale / import_external / import_markdown / export_markdown)

team

team (dedicated team collaboration scope; combine with read/write for personal journal access)

audit

memory://audit resource access (included in admin/full; search_audit_log requires admin or full)

admin

admin, backup, codemode (+ all read/write/team/audit groups)

full

Unrestricted access to all operations

Quick Start:

memory-journal-mcp --transport http --port 3000 \
  --allowed-io-roots /path/to/projects \
  --oauth-enabled \
  --oauth-issuer https://auth.example.com/realms/mcp \
  --oauth-audience memory-journal-mcp \
  --oauth-jwks-uri https://auth.example.com/realms/mcp/protocol/openid-connect/certs

Or via environment variables:

export ALLOWED_IO_ROOTS="/path/to/projects"
export OAUTH_ENABLED=true
export OAUTH_ISSUER=https://auth.example.com/realms/mcp
export OAUTH_AUDIENCE=memory-journal-mcp
export OAUTH_JWKS_URI=https://auth.example.com/realms/mcp/protocol/openid-connect/certs
export OAUTH_CLOCK_TOLERANCE=60
memory-journal-mcp --transport http --port 3000

Note: OAuth is opt-in. When not enabled, the server falls back to simple token authentication via MCP_AUTH_TOKEN environment variable, or runs without authentication.

๐Ÿ”„ Session Management

  1. Session start โ†’ agent reads memory://briefing (or memory://briefing/{repo}) and shows project context

  2. Session summary โ†’ use /session-summary to capture progress and next-session context

  3. Next session's briefing includes the previous summary โ€” context flows seamlessly

๐Ÿ”ง Configuration

Environment Variables

Variable

Description

Core Database & Server

DB_PATH

Path to the personal journal SQLite database (CLI: --db, --database, default: ./memory_journal.db)

DB_ENCRYPTION_KEY

SQLCipher at-rest database encryption key (alias: MJ_DB_ENCRYPTION_KEY)

TEAM_DB_PATH

Path to the shared team SQLite database (CLI: --team-db, --team-database)

TEAM_AUTHOR

Display name attached to team entries (used for local author identity; OAuth identity claims take precedence when creating team entries and RBAC ownership under active OAuth)

TEAM_DEFAULT_ROLE

Default RBAC role for unlisted team authors: admin, member, viewer, denied (CLI: --team-default-role, default: denied)

TEAM_ADMIN

Bootstrap admin author name when the team_members table is empty (CLI: --team-admin)

ADDITIONAL_TEAM_DBS

JSON mapping of label to path for additional read-only team SQLite databases (CLI: --additional-team-dbs)

DEFAULT_WORKSPACE_ID

Default workspace ID for multi-tenant isolation (CLI: --default-workspace-id, default: default; MCP_WORKSPACE_ID provides a session-scoped schema-healing fallback on tool payloads)

MEMORY_JOURNAL_CONFIG

Path to configuration file (.yaml, .yml, .json; CLI: --config)

LOG_LEVEL

Server log verbosity: debug, info, notice, warning, error, critical (CLI --log-level accepts debug, info, warning, error; default: info)

TRANSPORT / PORT / MCP_HOST / STATELESS

Transport mode (stdio or http; CLI: --transport), HTTP port (--port, default: 3000), bind address (--server-host, fallback: HOST, default: localhost), and stateless HTTP mode (--stateless, default: false)

CORS_ORIGIN / MCP_CORS_ORIGIN / MCP_RATE_LIMIT_MAX

Allowed CORS origins (--cors-origin) and per-IP/minute HTTP rate limit (default: 100)

GITHUB_TOKEN

Personal access token for GitHub integrations

DEFAULT_PROJECT_NUMBER

Default GitHub Project number for issue auto-assignment (CLI: --default-project)

PROJECT_REGISTRY

JSON map of repo names to local paths and project numbers

EMBEDDING_MODEL

HuggingFace transformers model for semantic search (CLI: --embedding-model, default: Xenova/all-MiniLM-L6-v2)

AUTO_REBUILD_INDEX

Rebuild vector search index on startup (true/false, CLI: --auto-rebuild-index)

Security & Tooling

ALLOWED_IO_ROOTS

Comma-separated paths for Code Mode and IO filesystem boundaries (fail-closed in stdio; mandatory when --transport http is used)

MEMORY_JOURNAL_MCP_TOOL_FILTER

Control tool exposure (full, starter, essential, codemode, readonly, -github; CLI: --tool-filter, memory-journal.config.{yaml,yml,json} key: "toolFilter". Note: TOOL_FILTER is a display fallback only)

CODE_MODE_MAX_RESULT_SIZE

Max execution payload buffer size in Code Mode (bytes, default: 102400)

CODEMODE_INTERNAL_FULL_ACCESS

Allow Code Mode to bypass tool filters internally (default: false)

MCP_AGENT_HEALING

Enable/disable autonomous tool & parameter healing (true/false, CLI: --no-agent-healing)

MAX_TOOL_INPUT_ELEMENTS

Max array/object elements in tool inputs (default: 25000, 0 or Infinity = disabled)

MCP_AUTH_TOKEN / MCP_AUTH_SCOPES

Static Bearer authentication token (--auth-token, --auth-scopes) and comma-separated granted scopes for HTTP transport (default: read)

MCP_ENABLE_HSTS / TRUST_PROXY

Enable Strict-Transport-Security header (--enable-hsts) and reverse-proxy X-Forwarded-For trust (--trust-proxy)

Briefing & Context

BRIEFING_ENTRY_COUNT

Number of granular journal entries in briefing (default: 3)

BRIEFING_SUMMARY_COUNT

Number of session summaries in briefing (default: 1)

BRIEFING_COMMIT_COUNT

Number of git commits in briefing (default: 3)

BRIEFING_IMPORTANCE_THRESHOLD

Minimum importance score for briefing entries (default: 0.3)

BRIEFING_INCLUDE_TEAM

Include entries from the team database (default: false)

BRIEFING_ISSUE_COUNT / BRIEFING_PR_COUNT / BRIEFING_PR_STATUS

GitHub Issues (default: 0), PRs (default: 0), and PR status breakdown (default: false) in briefing

BRIEFING_MILESTONE_COUNT

GitHub Milestones to list with titles (default: 3)

BRIEFING_WORKFLOW_COUNT / BRIEFING_WORKFLOW_STATUS / BRIEFING_COPILOT_REVIEWS

CI workflow runs (default: 0), status breakdown (default: false), and Copilot review state (default: false)

STALENESS_ACTIVE_HOURS / STALENESS_RECENT_DAYS / STALENESS_STALE_DAYS

Thresholds for memory://staleness project classification (defaults: 24h / 7d / 30d)

RULES_FILE_PATH / SKILLS_DIR_PATH / MEMORY_JOURNAL_WORKFLOW_SUMMARY

Injected behavioral rules, skills boundaries, and workflow summary

OAuth (HTTP Mode)

OAUTH_ENABLED

Enable OAuth 2.1 authentication (default: false)

OAUTH_ISSUER / OAUTH_AUDIENCE / OAUTH_JWKS_URI / OAUTH_CLOCK_TOLERANCE / PUBLIC_ORIGIN / OAUTH_ALLOW_PLAINTEXT_LOOPBACK

OAuth token verification parameters (clock tolerance default: 60s), non-loopback RFC 9728 public origin (--public-origin), and local dev plaintext loopback issuer flag (--oauth-allow-plaintext-loopback)

Telemetry & Administration

AUDIT_LOG_PATH / AUDIT_REDACT / AUDIT_READS / AUDIT_LOG_MAX_SIZE

Path to JSONL audit log file, argument/result redaction, read-call logging, and rotation size limit (default: 10MB)

METRICS_EXPORT / PERSIST_METRICS / METRICS_PATH / MJ_METRICS_PORT / MJ_METRICS_HOST

Prometheus export (METRICS_EXPORT=prometheus auto-starts the standalone metrics server on 127.0.0.1:9465 in addition to mounting /metrics on the HTTP transport), disk-persisted metrics (--persist-metrics, --metrics-path), and dedicated scrape port/host

AUTO_PRUNE_INTERVAL_MINUTES / ARCHIVE_OLDER_THAN_DAYS / PRUNE_OLDER_THAN_DAYS / HARD_DELETE_OLDER_THAN_DAYS / PRUNE_IMPORTANCE_THRESHOLD / PRUNE_DRY_RUN / PRUNE_EXCLUDE_TAGS

Autonomous lifecycle pruning, archiving (interval/days default: 0 = disabled), importance threshold (default: 0.15), dry-run (default: false), and exclusion tags

BACKUP_INTERVAL / KEEP_BACKUPS / VACUUM_INTERVAL / REBUILD_INDEX_INTERVAL / DIGEST_INTERVAL

Scheduled HTTP maintenance intervals in minutes (--backup-interval, --vacuum-interval, --rebuild-index-interval, --digest-interval) and backup retention count (--keep-backups, default: 5)

REPORT_INTERVAL / REPORT_WEBHOOK_URL / REPORT_WEBHOOK_AUTH / REPORT_CONTENT_TYPE / ALLOW_INSECURE_WEBHOOK_HTTP

Scheduled HTTP reports, webhook delivery headers/content-type, and local dev HTTP webhook override

DEBUG / DISABLE_ISSUE_LOGGING

Verbose debug logging and suppression of automated runtime issue logging

GitHub Integration (Optional)

export GITHUB_TOKEN="your_token"              # For Projects/Issues/PRs

Scopes: repo, project, read:org (org-level project discovery only)

Manage GitHub Seamlessly

Memory Journal provides a hybrid approach to GitHub management:

Capability Source

Purpose

MCP Server

Specialized features: Kanban visualization, Milestones, journal linking, project timelines

Agent (gh CLI)

Full GitHub mutations: create/close issues, create/merge PRs, manage releases

MCP Server Tools (Read + Kanban + Milestones + Issue Lifecycle):

See the Complete tools reference for all supported GitHub integration capabilities, including query commands, Kanban management, milestone tracking, analytics, and issue lifecycle events.

Why this design? The MCP server focuses on value-added features that integrate journal entries with GitHub (Kanban views, Milestones, timeline resources, context linking). Standard GitHub mutations (create/close issues, merge PRs, manage releases) are handled directly by agents via gh CLI.

Complete GitHub integration guide โ†’

Automate with GitHub Commander Workflows

The server natively bundles the memory-journal-mcp agent skill (served via SEP-2640 and memory://skills). It also provides built-in issue-commander, pr-commander, and cms-rem-supervisor MCP workflow prompts for autonomous DevOps stewardship: Issue Triage, Milestone Sprints, PR Reviews, Copilot Audits, Security Audits, Code Quality Audits, Performance Audits, Roadmap Kickoffs, and Dependency Updates. These workflows enforce multi-gate validation (lint, typecheck, test, and security checks) locally during agent tasks.

๐Ÿ—๏ธ Architecture

Data Flow

flowchart TB
    AI["๐Ÿค– AI Agent<br/>(Cursor, Windsurf, Claude)"]

    subgraph MCP["MCP Server Capabilities"]
        direction LR
        Tools["๐Ÿ› ๏ธ MCP Tools"]
        Resources["๐Ÿ“ก Resources"]
        Prompts["๐Ÿ’ฌ Prompts"]
    end

    subgraph Storage["Persistence Layer"]
        SQLite[("๐Ÿ’พ SQLite<br/>Entries, Tags, Relationships")]
        Vector[("๐Ÿ” Vector Index<br/>Semantic Embeddings")]
        Backups["๐Ÿ“ฆ Backups"]
    end

    subgraph External["External Integrations"]
        GitHub["๐Ÿ™ GitHub API<br/>Issues, PRs, Actions"]
        Kanban["๐Ÿ“‹ Projects v2<br/>Kanban Boards"]
    end

    AI <-->|"MCP Protocol"| MCP
    Tools --> Storage
    Tools --> External
    Resources --> Storage
    Resources --> External

Stack

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ MCP Server Layer (TypeScript)                               โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚ Tools           โ”‚  โ”‚ Resources       โ”‚  โ”‚ Prompts     โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚ Native SQLite Engine                                        โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚ better-sqlite3  โ”‚  โ”‚ sqlite-vec      โ”‚  โ”‚ transformersโ”‚  โ”‚
โ”‚  โ”‚ (High-Perf I/O) โ”‚  โ”‚ (Vector Index)  โ”‚  โ”‚ (Embeddings)โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚ SQLite Database with Hybrid Search                          โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚
โ”‚  โ”‚ entries + tags + relationships + embeddings + backups   โ”‚โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

๐Ÿ”ง Technical Highlights

Performance & Portability

  • TypeScript + Native SQLite - High-performance better-sqlite3 with synchronous I/O

  • sqlite-vec - Vector similarity search via SQLite extension

  • @huggingface/transformers - Local ML embedding models in JavaScript

  • Background Warmup - Model weights (~23MB) are loaded into memory asynchronously on server startup to avoid first-request latency. If the server is invoked before warmup completes, the first semantic search or vector insertion will incur a network-bound cold start (~1.5s - 3s) while the weights are cached locally.

Performance Benchmarks

Memory Journal is designed for extremely low overhead during AI task execution. We include a vitest bench suite across database, vector search, and MCP server routines to maintain these baseline guarantees:

  • Database Operations (sqlite-adapter.bench.ts): calculateImportance runs at ~51,600 ops/sec (~0.03ms mean, ~27x faster than retrieving 50 recent entries) via a 256-entry LRU prepared statement cache. getRecentEntries (limit 50) executes at ~1,870 ops/sec (~0.63ms mean), updateEntry at ~2,380 ops/sec (~0.79ms mean), createEntry at ~1,060 ops/sec (~1.69ms mean), and searchEntries (FTS5 BM25 + batch importance hydration) at ~176 ops/sec (~6.2ms mean).

  • Vector Search Engine (vector-search.bench.ts): Both k-NN similarity search (~1,050 ops/sec, ~1.8ms mean with batch entry hydration) and vector indexing (~4,220 ops/sec, ~0.41ms mean) are high-throughput via sqlite-vec (vec0 with chunk_size=256).

  • Core MCP Routines (mcp-server.bench.ts): getTools uses cached O(1) dispatch (~7.2Mโ€“9.4M ops/sec, ~0.0001ms). Full end-to-end callTool invocations (including interceptor, token estimation, and project registry resolution) run at ~1,775 ops/sec (~0.65ms) for get_recent_entries, ~205 ops/sec (~5.4ms) for search_entries, and ~800 ops/sec (~2.4ms) for create_entry.

To run the benchmarking suite locally:

pnpm run bench

Testing

Extensively tested across two frameworks:

Suite

Command

Covers

Vitest (unit/integration)

pnpm test

Extensive Vitest unit and integration suite with strict quality gates (database, tools, resources, handlers, security, GitHub, vector search, codemode)

Playwright (e2e)

pnpm run test:e2e

HTTP/SSE transport, auth, sessions, CORS, security headers, scheduler

pnpm test          # Unit + integration tests
pnpm run test:e2e  # End-to-end HTTP/SSE transport tests

Security

Note: When updating schemas or validation logic, please refer to the /zod skill for best practices on Standard Schema and Safe Parsing.

  • Deterministic error handling - Every tool returns structured {success, error, code, category, suggestion, recoverable} responses with actionable context โ€” no raw exceptions, no silent failures, no misleading messages

  • Local-first - All data stored locally, no external API calls (except optional GitHub)

  • Input validation - Zod schemas, content size limits, SQL injection prevention, and <untrusted_remote_content> prompt-injection boundary tagging

  • Path traversal & SSRF protection - ALLOWED_IO_ROOTS sandbox containment with URL-decode/symlink verification, backup path validation, and outbound webhook DNS/IP SSRF blocking

  • Multi-tenant & filter enforcement - End-to-end workspace_id isolation across SQLite and Vector search, plus execution-layer --tool-filter enforcement across tools/call, Code Mode (mj.*), and fallback handlers

  • MCP 2025-11-25 annotations & icons - Behavioral hints (readOnlyHint, destructiveHint, etc.) and capability icons

  • HTTP transport hardening - OAuth 2.1 tokenClaims propagation, principal-bound stateful sessions (100 max active sessions), comprehensive security headers, configurable multi-origin CORS, 1MB body/stream limit, built-in per-subject/IP rate limiting (100 req/min), server timeouts, HSTS (opt-in), 30-min session timeout, and localhost-bound metrics (METRICS_EXPORT=prometheus automatically starts the standalone metrics server on 127.0.0.1:9465, customizable via MJ_METRICS_PORT and MJ_METRICS_HOST, in addition to mounting /metrics on the HTTP transport)

  • Token scrubbing - GitHub tokens and credentials automatically redacted from error and audit logs

Data & Privacy

  • Single SQLite file - You own your data

  • Portable - Move your .db file anywhere

  • Soft delete - Entries can be recovered

  • Auto-backup on restore - Never lose data accidentally


๐Ÿ“š Documentation & Resources


๐Ÿ“„ License

MIT License - See LICENSE file for details.

๐Ÿค Contributing

Built by developers, for developers. PRs welcome! Ensure all unit and E2E tests, linting, and typechecks pass. See CONTRIBUTING.md for guidelines.

Upgrading from an earlier version? Your existing SQLite database is automatically migrated on startup.

Available Tools

113 tools
add_kanban_itemAdd Kanban ItemA
Idempotent
Inspect

Add an existing GitHub Issue or Pull Request to a Kanban board (GitHub Project v2). Returns the project item ID on success.

Inputs: repo, owner, use_test_db, issue_number, +1 more. Returns: code, error, itemId, details, +5 more

add_to_vector_indexAdd Entry to Vector IndexC
Idempotent
Inspect

Add a specific entry to the semantic search vector index

Inputs: entry_id, project_number. Returns: code, error, details, entryId, +5 more

analyze_commit_patternsAnalyze Commit PatternsC
Read-onlyIdempotent
Inspect

Analyze patterns in a list of commits or recent history

Inputs: maxCount, use_test_db. Returns: code, error, details, success, +5 more

backup_journalBackup Journal DatabaseBInspect

Create a timestamped backup of the journal database. Backups are stored in the backups/ directory.

Inputs: name, compress, use_test_db. Returns: code, path, error, details, +8 more

batch_create_entriesBatch Create EntriesCInspect

Create multiple journal entries at once. Max 50 per batch. Use this for imports or bulk creation. Select the most accurate entry_type for each. REQUIRED: You MUST include project_number. Extract this by querying memory://agent-id. REQUIRED: You MUST include impact_score, trust_score, and validation_status. REQUIRED: You MUST use related_to to anchor entries to previous context.

Inputs: entries, auto_index, workspace_id, project_number. Returns: code, count, error, details, +7 more

batch_delete_entriesBatch Delete EntriesB
Destructive
Inspect

Delete multiple existing journal entries in a single transaction. Max 50 per batch.

Inputs: entry_ids, permanent, workspace_id, project_number. Returns: code, count, error, deleted, +9 more

batch_update_entriesBatch Update EntriesAInspect

Update multiple existing journal entries in a single transaction. Max 50 per batch. REQUIRED: You MUST include project_number. Extract this by querying memory://agent-id.

Inputs: updates, auto_index, workspace_id, project_number. Returns: code, count, error, details, +8 more

check_entry_stalenessCheck Entry StalenessB
Idempotent
Inspect

Check if a journal entry's anchors have been modified or deleted in git since the entry was created.

Inputs: entryId, entry_id, use_test_db, workspaceId, +3 more. Returns: code, error, details, results, +5 more

cleanup_backupsCleanup Old BackupsAInspect

Delete old backup files, keeping only the most recent N backups. Use list_backups to preview before cleanup.

Inputs: keep_count, use_test_db. Returns: code, error, deleted, details, +8 more

close_github_issue_with_entryClose GitHub Issue with Resolution EntryBInspect

Close a GitHub issue AND create a journal entry documenting the resolution.

Inputs: repo, tags, owner, comment, +5 more. Returns: code, error, issue, kanban, +10 more

create_entryCreate EntryBInspect

Create a new journal entry. Content must be well-structured markdown using ## section headers. Select the most accurate entry_type (e.g., retrospective, personal_reflection, technical_note). For session summaries, use entry_type "retrospective" with tag "session-summary" and structure content as: ## Accomplished, ## Unfinished / Blocked, ## Context for Next Session. REQUIRED: You MUST include project_number. Extract this by querying memory://agent-id. REQUIRED: You MUST include impact_score, trust_score, and validation_status. REQUIRED: You MUST use related_to to anchor the entry to a session summary or nearby context.

Inputs: workspace_id (required), tags, pr_url, anchors, +20 more. Returns: id, code, entry, error, +8 more

create_github_issue_with_entryCreate GitHub Issue with Journal EntryBInspect

Create a GitHub issue AND automatically create a linked journal entry documenting the issue creation.

Inputs: body, repo, tags, owner, +8 more. Returns: code, error, issue, details, +10 more

create_github_milestoneCreate GitHub MilestoneCInspect

Create a new GitHub milestone for tracking progress toward a project goal.

Inputs: repo, owner, title, due_on, +2 more. Returns: code, error, details, message, +8 more

delete_entryDelete EntryA
Destructive
Inspect

Delete a journal entry (soft delete with timestamp). Calling with permanent: true on a previously soft-deleted entry works. Returns success: false for nonexistent entries.

Inputs: entry_id, permanent, workspace_id, project_number, +1 more. Returns: code, error, details, entryId, +7 more

delete_github_milestoneDelete GitHub MilestoneA
Destructive
Inspect

Permanently delete a GitHub milestone. Issues assigned to the milestone will be un-assigned but not deleted.

Inputs: repo, owner, confirm, use_test_db, +1 more. Returns: code, error, details, message, +8 more

delete_kanban_itemDelete Kanban ItemAInspect

Remove an item from a GitHub Kanban board cleanly. This untethers it from the project but does NOT close or delete the underlying Issue/PR.

Inputs: repo, owner, item_id, use_test_db, +1 more. Returns: code, error, itemId, details, +5 more

delete_projectDelete ProjectC
DestructiveIdempotent
Inspect

Remove a project from the global registry.

Inputs: name, use_test_db. Returns: code, data, error, items, +9 more

export_entriesExport EntriesB
Read-onlyIdempotent
Inspect

Export journal entries to JSON or Markdown format

Inputs: tags, limit, format, end_date, +4 more. Returns: code, count, error, format, +9 more

export_markdownExport to Markdown FilesA
Idempotent
Inspect

Export journal entries as individual frontmattered Markdown files (.md). Each file contains YAML frontmatter (mj_id, entry_type, tags, relationships) and the entry content. Files can be edited externally and re-imported via import_markdown.

Inputs: tags, limit, end_date, output_dir, +4 more. Returns: code, error, files, details, +8 more

get_commit_historyGet Commit HistoryB
Read-onlyIdempotent
Inspect

Retrieve commit history for the current repository

Inputs: ref, path, scope, since, +4 more. Returns: code, error, commits, details, +6 more

get_copilot_reviewsGet Copilot Code ReviewsA
Read-onlyIdempotent
Inspect

Get Copilot's code review findings for a pull request. Returns review state (approved/changes_requested/commented/none) and file-level comments with paths and line numbers. Use to learn from Copilot's review patterns and create journal entries with tag "copilot-finding".

Inputs: repo, owner, pr_number, use_test_db. Returns: code, repo, error, owner, +13 more

get_cross_project_insightsGet Cross-Project InsightsA
Read-onlyIdempotent
Inspect

Analyze patterns across all GitHub Projects tracked in journal entries. Use for architecture planning.

Inputs: limit, query, end_date, start_date, +4 more. Returns: code, error, details, message, +11 more

get_entry_by_idGet Entry by IDC
Read-onlyIdempotent
Inspect

Retrieve a specific entry by its ID

Inputs: entry_id, use_test_db, workspace_id, project_number, +1 more. Returns: code, entry, error, details, +8 more

get_entry_historyGet Entry Revision HistoryC
Read-onlyIdempotent
Inspect

Retrieve the revision history of an entry (last 10 edits).

Inputs: entry_id, use_test_db, workspace_id, project_number. Returns: id, code, error, current, +7 more

get_github_contextGet GitHub Repository ContextA
Read-onlyIdempotent
Inspect

Get current repository context including branch, open issues, and open PRs. IMPORTANT: Leave owner/repo empty to auto-detect from git, OR specify the repository name if working in a multi-project registry.

Inputs: repo, owner, use_test_db. Returns: code, error, branch, commit, +11 more

get_github_issueGet GitHub Issue DetailsA
Read-onlyIdempotent
Inspect

Get detailed information about a specific GitHub issue. IMPORTANT: Do NOT guess owner/repo values - leave them empty to auto-detect from the current git repository.

Inputs: repo, owner, use_test_db, issue_number, +2 more. Returns: code, repo, error, issue, +12 more

get_github_issuesGet GitHub IssuesA
Read-onlyIdempotent
Inspect

List issues from a GitHub repository. IMPORTANT: Do NOT guess owner/repo values - leave them empty to auto-detect from the current git repository.

Inputs: repo, limit, owner, state, +1 more. Returns: code, repo, count, error, +11 more

get_github_milestoneGet GitHub Milestone DetailsB
Read-onlyIdempotent
Inspect

Get detailed information about a specific GitHub milestone including progress and linked issue counts.

Inputs: repo, owner, use_test_db, milestone_number. Returns: code, repo, error, owner, +10 more

get_github_milestonesList GitHub MilestonesA
Read-onlyIdempotent
Inspect

List GitHub milestones for the repository with completion percentages and due dates.

Inputs: repo, limit, owner, state, +1 more. Returns: code, repo, count, error, +11 more

get_github_prGet GitHub PR DetailsB
Read-onlyIdempotent
Inspect

Get detailed information about a specific GitHub pull request, including live prStatus. IMPORTANT: Do NOT guess owner/repo values - leave them empty to auto-detect from the current git repository.

Inputs: repo, owner, pr_number, use_test_db, +1 more. Returns: code, repo, error, owner, +10 more

get_github_prsGet GitHub Pull RequestsB
Read-onlyIdempotent
Inspect

List pull requests from a GitHub repository. IMPORTANT: Do NOT guess owner/repo values - leave them empty to auto-detect from the current git repository.

Inputs: repo, limit, owner, state, +1 more. Returns: code, repo, count, error, +11 more

get_kanban_boardGet Kanban BoardA
Read-onlyIdempotent
Inspect

View a GitHub Project v2 as a Kanban board with items grouped by Status column. Returns all columns with their items.

Inputs: repo, owner, item_limit, use_test_db, +2 more. Returns: code, hint, error, owner, +18 more

get_projectGet ProjectB
Read-onlyIdempotent
Inspect

Get details of a specific registered project.

Inputs: name (required), project_number. Returns: code, data, error, items, +9 more

get_recent_entriesGet Recent EntriesC
Read-onlyIdempotent
Inspect

Get the most recent journal entries

Inputs: limit, cursor, offset, sort_by, +5 more. Returns: code, count, error, details, +8 more

get_release_infoGet Release InfoB
Read-onlyIdempotent
Inspect

Get latest release commits

Inputs: ref, use_test_db. Returns: code, error, commits, details, +6 more

get_repo_insightsRepository InsightsA
Read-onlyIdempotent
Inspect

Get repository insights: stars, forks, traffic (clones/views), referrers, and popular paths. Use "sections" to control token usage: stars (~50 tokens), traffic (~100), referrers (~100), paths (~100), or all (~350).

Inputs: repo, owner, sections, use_test_db. Returns: code, repo, size, error, +18 more

get_statisticsGet StatisticsC
Read-onlyIdempotent
Inspect

Get journal statistics and analytics (Phase 2: includes project breakdown)

Inputs: time, period, end_date, group_by, +6 more. Returns: code, error, details, groupBy, +15 more

get_unreleased_commitsGet Unreleased CommitsC
Read-onlyIdempotent
Inspect

Get commits since the last tag/release

Inputs: use_test_db. Returns: code, error, commits, details, +6 more

get_vector_index_statsGet Vector Index StatsC
Read-onlyIdempotent
Inspect

Get statistics about the semantic search vector index

Inputs: use_test_db. Returns: code, error, details, success, +8 more

import_externalImport from External ToolsAInspect

Import knowledge management exports (Notion, Obsidian, Logseq) into the journal. Normalizes wikilinks, YAML frontmatter, and block hierarchies automatically. Use dry_run: true to preview what would happen without writing.

Inputs: limit, dry_run, source_dir, workspace_id, +3 more. Returns: code, error, errors, created, +11 more

import_markdownImport from Markdown FilesAInspect

Import frontmattered Markdown files (.md) into the journal. If a file has an mj_id in its frontmatter and the entry exists, it is updated. Otherwise, a new entry is created. Tags and relationships are reconciled automatically. Use dry_run: true to preview what would happen without writing.

Inputs: limit, dry_run, source_dir, workspace_id, +1 more. Returns: code, error, errors, created, +11 more

list_backupsList Journal BackupsB
Read-onlyIdempotent
Inspect

List all available backup files with their sizes and creation dates

Inputs: use_test_db. Returns: code, hint, error, total, +8 more

list_deleted_entriesList Deleted EntriesC
Read-onlyIdempotent
Inspect

List recently soft-deleted entries that can be restored

Inputs: limit, offset, use_test_db, workspaceId, +3 more. Returns: code, count, error, facets, +13 more

list_projectsList ProjectsC
Read-onlyIdempotent
Inspect

List all registered projects.

Inputs: use_test_db. Returns: code, data, error, items, +9 more

list_tagsList TagsB
Read-onlyIdempotent
Inspect

List all unique tags used across all entries

Inputs: use_test_db. Returns: code, tags, count, error, +6 more

load-briefingPrompt Fallback (load-briefing)C
Read-only
Inspect

Fallback handler for load-briefing when invoked as an MCP tool instead of an MCP prompt.

Inputs: code, error, details, category, +4 more. Returns: code, error, details, category, +3 more

mark_anchors_staleMark Anchors StaleB
Idempotent
Inspect

Update the status of multiple anchors (e.g. to stale or invalidated) based on validation rules or git history checks.

Inputs: updates, use_test_db. Returns: code, error, details, success, +5 more

memory_read_resourceRead Resource (memory_read_resource)C
Read-only
Inspect

Fallback handler for memory_read_resource when invoked as an MCP tool instead of a protocol resource read.

Inputs: code, error, details, category, +4 more. Returns: code, error, details, category, +3 more

merge_tagsMerge TagsAInspect

Merge one tag into another to consolidate similar tags (e.g., merge "phase-2" into "phase2"). The source tag is deleted after merge. Only updates non-deleted entries.

Inputs: source_tag, target_tag, use_test_db. Returns: code, error, details, message, +9 more

mj_execute_codeExecute JS Code (Sandbox)AInspect

Run arbitrary JavaScript to automate tasks in a secure sandbox. IMPORTANT: You MUST use the mj object (NOT api, journal, or mcp) to access tools. DO NOT use import() or require(); the mj tools are globally available in the sandbox. Available tools are mapped directly from MCP tool names, converted to camelCase (e.g., create_entry -> mj.createEntry(), search_entries -> mj.searchEntries()). Anti-Hallucination Hint: DO NOT GUESS parameter keys (e.g., passing repo instead of repo_name will fail). ALWAYS inspect the schema first if unsure: return await mj.createEntry.schema(). Execution limit: 30s. Network access (fetch) disabled. Example: return await mj.searchEntries({ query: "PowerShell" })

Inputs: code, repo, entry, query, +11 more.

mj_read_resourceRead Resource (mj_read_resource)C
Read-only
Inspect

Fallback handler for mj_read_resource when invoked as an MCP tool instead of a protocol resource read.

Inputs: code, error, details, category, +4 more. Returns: code, error, details, category, +3 more

mj_session_summaryPrompt Fallback (mj_session_summary)C
Read-only
Inspect

Fallback handler for mj_session_summary when invoked as an MCP tool instead of an MCP prompt.

Inputs: code, error, details, category, +4 more. Returns: code, error, details, category, +3 more

move_kanban_itemMove Kanban ItemA
Idempotent
Inspect

Move a Kanban item to a different status column. Requires the project board to have a Status field.

Inputs: repo, owner, item_id, use_test_db, +2 more. Returns: code, error, itemId, details, +7 more

read_resourceRead Resource (read_resource)C
Read-only
Inspect

Fallback handler for read_resource when invoked as an MCP tool instead of a protocol resource read.

Inputs: code, error, details, category, +4 more. Returns: code, error, details, category, +3 more

rebuild_vector_indexRebuild Vector IndexBInspect

[REQUIRES ADMIN SCOPE] Rebuild the semantic search vector index from all existing entries

Inputs: use_test_db, project_number. Returns: code, error, details, partial, +7 more

register_projectRegister ProjectA
Idempotent
Inspect

Register a new project in the global registry. This is required before the agent can switch context to this repository.

Inputs: name, use_test_db, absolute_path, project_number. Returns: code, data, error, items, +9 more

restore_backupRestore Journal from BackupA
Destructive
Inspect

Restore the journal database from a backup file. WARNING: This replaces all current data. Enforce single-writer / single-instance only for restore-capable deployments. An automatic backup is created before restore.

Inputs: confirm, filename, use_test_db. Returns: code, error, details, message, +10 more

restore_entryRestore EntryCInspect

Restore a soft-deleted journal entry.

Inputs: entry_id, workspace_id, project_number. Returns: code, error, details, entryId, +5 more

run_auto_pruneRun Auto PruneA
Destructive
Inspect

Manually trigger the autonomous pruning and cleanup routines. This evaluates entry importance, archives old entries, and hard-deletes stale softly-deleted ones.

Inputs: dry_run, use_test_db, importance_threshold, prune_older_than_days, +2 more. Returns: code, error, dryRun, details, +9 more

search_audit_logSearch Audit LogB
Read-onlyIdempotent
Inspect

Search operational telemetry audit logs by tool name, user, date range, status, or category. Returns the most recent matches up to the limit.

Inputs: user, limit, status, category, +3 more. Returns: code, count, error, details, +6 more

search_by_date_rangeSearch by Date RangeC
Read-onlyIdempotent
Inspect

Search journal entries within a date range with optional filters

Inputs: tags, limit, cursor, sort_by, +11 more. Returns: code, count, error, facets, +13 more

search_commitsSearch CommitsC
Read-onlyIdempotent
Inspect

Search commit history by query

Inputs: query, scope, sortBy, maxCount, +2 more. Returns: code, error, commits, details, +6 more

search_entriesSearch EntriesA
Read-onlyIdempotent
Inspect

Search journal entries. Use sort_by: "importance" to surface structurally significant entries before major decisions. Supports modes: auto (default), fts, semantic, hybrid. Optional filters for GitHub Projects, Issues, PRs, and Actions. FTS5 syntax: "exact phrase", prefix*, OR/NOT/AND. Word-boundary matched. Automatically merges team DB results when TEAM_DB_PATH is configured.

Inputs: mode, tags, limit, query, +21 more. Returns: code, count, error, facets, +13 more

team_add_author_aliasAdd Author AliasA
Idempotent
Inspect

Map a raw author name to a canonical identity. Requires admin role. Used to consolidate attribution for team analytics when one person uses multiple usernames.

Inputs: alias (required), canonical_author (required), workspace_id. Returns: code, alias, error, details, +5 more

team_add_memberAdd Team MemberAInspect

Add a new member to the team with a specific role. Bootstraps the first user as admin if table is empty. Requires TEAM_DB_PATH.

Inputs: role, author, display_name, workspace_id. Returns: code, error, member, details, +6 more

team_add_to_vector_indexAdd Team Entry to Vector IndexB
Idempotent
Inspect

Add a specific team entry to the semantic search vector index. Requires TEAM_DB_PATH.

Inputs: entry_id, use_test_db, workspace_id, project_number. Returns: code, error, details, entryId, +5 more

team_backupBackup Team DatabaseBInspect

Create a timestamped backup of the team database. Requires TEAM_DB_PATH.

Inputs: name, use_test_db, workspace_id. Returns: code, path, error, details, +8 more

team_batch_create_entriesTeam Batch Create EntriesCInspect

Create multiple team journal entries at once. Max 50 per batch. Select the most accurate entry_type for each. REQUIRED: You MUST include project_number. REQUIRED: You MUST include impact_score, trust_score, and validation_status. REQUIRED: You MUST use related_to to anchor entries to previous context.

Inputs: entries, auto_index, use_test_db, workspace_id, +1 more. Returns: code, count, error, details, +7 more

team_batch_delete_entriesTeam Batch Delete EntriesA
Destructive
Inspect

Delete multiple existing team journal entries in a single transaction. Max 50 per batch. Can only delete entries you authored.

Inputs: entry_ids, permanent, workspace_id, project_number. Returns: code, count, error, deleted, +9 more

team_batch_update_entriesTeam Batch Update EntriesAInspect

Update multiple existing team journal entries in a single transaction. Max 50 per batch. Can only update entries you authored. Pass expected_version for optimistic locking.

Inputs: updates, auto_index, workspace_id, project_number. Returns: code, count, error, details, +8 more

team_consolidate_authorsConsolidate AuthorsA
Destructive
Inspect

Retroactively rewrite all past entries matching an author's aliases to the canonical author name. Requires admin role. This operation modifies database entries.

Inputs: canonical_author (required), workspace_id. Returns: code, error, details, success, +6 more

team_create_entryCreate Team EntryAInspect

Create an entry in the team database for sharing with collaborators. ONLY use when explicitly requested by the user. Default to personal create_entry instead. Content must be well-structured markdown using ## section headers. Select the most accurate entry_type (e.g., retrospective, technical_note). For session summaries, use entry_type "retrospective" with tag "session-summary" and structure content as: ## Accomplished, ## Unfinished / Blocked, ## Context for Next Session. REQUIRED: You MUST include project_number. REQUIRED: You MUST include impact_score, trust_score, and validation_status. REQUIRED: You MUST use related_to to anchor the entry to a session summary or nearby context. Requires TEAM_DB_PATH.

Inputs: tags, author, pr_url, content, +18 more. Returns: code, entry, error, author, +6 more

team_delete_entryDelete Team EntryA
Destructive
Inspect

Soft-delete a team entry (marks as deleted, preservable via team_restore_entry). Returns success: false for nonexistent entries. Requires TEAM_DB_PATH.

Inputs: entry_id, workspace_id, project_number, expected_version. Returns: code, error, details, message, +5 more

team_export_entriesExport Team EntriesB
Read-onlyIdempotent
Inspect

Export team entries in JSON or Markdown format with optional date range, type, and tag filters. Requires TEAM_DB_PATH.

Inputs: tags, limit, format, end_date, +3 more. Returns: code, data, count, error, +8 more

team_export_markdownTeam Export to MarkdownB
Idempotent
Inspect

Export team entries as frontmattered Markdown files

Inputs: tags, limit, end_date, output_dir, +4 more. Returns: code, error, files, details, +8 more

team_get_collaboration_matrixTeam Collaboration MatrixB
Read-onlyIdempotent
Inspect

Analyze cross-author collaboration: activity heatmap per period, cross-linking patterns between authors, and impact factor (inbound links). Requires TEAM_DB_PATH.

Inputs: limit, period, use_test_db, workspace_id. Returns: code, error, details, success, +9 more

team_get_cross_project_insightsTeam Cross-Project InsightsB
Read-onlyIdempotent
Inspect

Analyze patterns across all GitHub Projects tracked in team entries. Use for architecture planning. Requires TEAM_DB_PATH.

Inputs: limit, end_date, start_date, min_entries, +2 more. Returns: code, error, details, message, +11 more

team_get_entry_by_idGet Team Entry by IDC
Read-onlyIdempotent
Inspect

Get a specific team entry by ID with full details including relationships and importance score. Requires TEAM_DB_PATH.

Inputs: entry_id, use_test_db, workspace_id, project_number, +1 more. Returns: code, entry, error, details, +7 more

team_get_memberGet Team MemberB
Read-onlyIdempotent
Inspect

Get details about a specific team member. Requires TEAM_DB_PATH.

Inputs: author, workspace_id. Returns: code, error, member, details, +5 more

team_get_recentGet Recent Team EntriesC
Read-onlyIdempotent
Inspect

Get recent entries from the team database. Requires TEAM_DB_PATH.

Inputs: limit, cursor, sort_by, use_test_db, +3 more. Returns: code, count, error, details, +9 more

team_get_statisticsGet Team StatisticsB
Read-onlyIdempotent
Inspect

Get statistics for the team database including entry counts, types, top tags, and contributor breakdown. Requires TEAM_DB_PATH.

Inputs: group_by, use_test_db, workspace_id. Returns: code, error, authors, details, +9 more

team_get_vector_index_statsTeam Vector Index StatsB
Read-onlyIdempotent
Inspect

Get statistics about the team vector search index (item count, model, dimensions). Requires TEAM_DB_PATH.

Inputs: use_test_db. Returns: code, error, details, success, +8 more

team_import_externalTeam Import from External ToolsCInspect

Import knowledge management exports into the team journal

Inputs: limit, dry_run, source_dir, use_test_db, +4 more. Returns: code, error, errors, created, +9 more

team_import_markdownTeam Import from MarkdownCInspect

Import frontmattered Markdown files into the team journal

Inputs: limit, dry_run, source_dir, use_test_db, +2 more. Returns: code, error, errors, created, +9 more

team_list_author_aliasesList Author AliasesA
Read-onlyIdempotent
Inspect

List all registered author aliases. Requires admin role.

Inputs: workspace_id, canonical_author. Returns: code, error, aliases, details, +5 more

team_list_backupsList Team BackupsB
Read-onlyIdempotent
Inspect

List all available backup files for the team database. Requires TEAM_DB_PATH.

Inputs: use_test_db. Returns: code, hint, error, total, +8 more

team_list_deleted_entriesList Deleted Team EntriesB
Read-onlyIdempotent
Inspect

List recently soft-deleted team entries that can be restored. Requires TEAM_DB_PATH.

Inputs: limit, offset, use_test_db, workspace_id, +1 more. Returns: code, count, error, details, +9 more

team_list_membersList Team MembersB
Read-onlyIdempotent
Inspect

List all registered team members and their roles. Requires TEAM_DB_PATH.

Inputs: use_test_db, workspace_id. Returns: code, count, error, details, +6 more

team_list_tagsList Team TagsA
Read-onlyIdempotent
Inspect

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

Inputs: use_test_db. Returns: code, tags, count, error, +6 more

team_merge_tagsMerge Team TagsAInspect

Merge a source tag into a target tag in the team database. All entries with the source tag will be re-tagged with the target tag. Only updates non-deleted entries. Requires TEAM_DB_PATH.

Inputs: source_tag, target_tag, use_test_db, workspace_id. Returns: code, error, details, message, +7 more

team_rebuild_vector_indexRebuild Team Vector IndexBInspect

Rebuild the team semantic search vector index from all existing team entries. Requires TEAM_DB_PATH. [REQUIRES ADMIN SCOPE]

Inputs: use_test_db. Returns: code, error, details, partial, +7 more

team_remove_author_aliasRemove Author AliasA
Destructive
Inspect

Remove an author alias mapping. Requires admin role.

Inputs: alias (required), workspace_id. Returns: code, error, details, success, +4 more

team_remove_memberRemove Team MemberC
Destructive
Inspect

Remove a member from the team. Requires TEAM_DB_PATH.

Inputs: author, workspace_id. Returns: code, error, details, message, +5 more

team_resolve_authorResolve AuthorA
Read-onlyIdempotent
Inspect

Resolve a raw author name to its canonical identity using registered aliases. Requires admin role.

Inputs: author (required), workspace_id. Returns: code, error, details, category, +6 more

team_restore_entryRestore Team EntryBInspect

Restore a soft-deleted team entry. Requires TEAM_DB_PATH.

Inputs: entry_id, workspace_id, project_number. Returns: code, error, details, entryId, +5 more

team_search_by_date_rangeSearch Team Entries by Date RangeA
Read-onlyIdempotent
Inspect

Search team entries within a date range with optional filters for entry type and tags. Requires TEAM_DB_PATH. ๐Ÿ›‘ WARNING: Team DB is a shared multi-tenant domain. You MUST specify project_number to isolate results to the target project.

Inputs: tags, limit, cursor, sort_by, +6 more. Returns: code, count, error, details, +9 more

team_update_entryUpdate Team EntryBInspect

Update a team entry. When updating content, preserve the existing markdown structure (## section headers). Do NOT restructure or add new top-level sections unless explicitly requested. Pass expected_version for optimistic locking. Pass null to clear a metadata field. Supports content, type, tags, and 11 metadata fields. Requires TEAM_DB_PATH.

Inputs: tags, pr_url, content, entry_id, +19 more. Returns: code, entry, error, details, +5 more

team_update_member_roleUpdate Team Member RoleCInspect

Update the role of an existing team member. Requires TEAM_DB_PATH.

Inputs: role, author, workspace_id. Returns: code, error, member, details, +5 more

team_visualize_relationshipsVisualize Team RelationshipsA
Read-onlyIdempotent
Inspect

Generate a Mermaid diagram showing relationships between team entries. Filter by entry ID, tag, or traverse to a specified depth. Requires TEAM_DB_PATH.

Inputs: tag, depth, entry_id, use_test_db, +1 more. Returns: code, error, details, mermaid, +7 more

test_error_handlingTest Error HandlingB
Read-onlyIdempotent
Inspect

Throws a specific type of error to verify the server formats and returns them correctly over MCP.

Inputs: message, error_type, use_test_db. Returns: code, error, details, category, +3 more

test_simpleTest Simple EchoB
Read-onlyIdempotent
Inspect

A simple echo tool for testing connection and basic parameter parsing.

Inputs: message, use_test_db. Returns: code, error, details, message, +6 more

trigger_progressTest Progress NotificationsB
Read-onlyIdempotent
Inspect

Triggers a sequence of progress notifications to verify the transport layer supports them.

Inputs: use_test_db. Returns: code, error, details, message, +5 more

update_configurationUpdate Server ConfigurationCInspect

Dynamically update the MCP server configuration (instruction level, tool filters, briefing preferences) without restarting the server.

Inputs: tool_filter, briefing_prs, project_number, briefing_issues, +8 more. Returns: code, error, details, success, +5 more

update_entryUpdate EntryBInspect

Update an existing journal entry. When updating content, preserve the existing markdown structure (## section headers). Do NOT restructure or add new top-level sections unless explicitly requested. Pass null to clear a metadata field. Supports content, type, tags, and 11 metadata fields including significance, project, issue, PR, and workflow.

Inputs: tags, pr_url, content, entry_id, +21 more. Returns: code, entry, error, details, +6 more

update_github_milestoneUpdate GitHub MilestoneAInspect

Update a GitHub milestone (title, description, due date, or state). Use state "closed" to close a completed milestone.

Inputs: repo, owner, state, title, +4 more. Returns: code, error, details, message, +8 more

update_projectUpdate ProjectBInspect

Update the details (path, number, or name) of an existing project in the registry.

Inputs: name, new_name, use_test_db, absolute_path, +1 more. Returns: code, data, error, items, +9 more

visualize_relationshipsVisualize RelationshipsC
Read-onlyIdempotent
Inspect

Generate a Mermaid diagram visualization of entry relationships

Inputs: q, id, rel, keep, +13 more. Returns: code, depth, error, legend, +11 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    C2.8/5.0

    Scored across 113 tools

    Disambiguation2/5

    The set has many overlapping tools: search_entries overlaps with semantic_search and search_by_date_range, personal and team variants mirror each other, and read_resource/mj_read_resource/memory_read_resource are essentially fallback aliases. Team-prefixed tools are distinguishable, but an agent faces real misselection risk across search, backup, import/export, vector-index, and GitHub issue/PR/kanban operations.

    Naming Consistency3/5

    Most tools use snake_case and the team_* subset is consistently prefixed, which helps. However, personal tools are unprefixed, GitHub tools use mixed patterns (get_github_issues vs move_kanban_item vs close_github_issue_with_entry), and a few names use kebab-case or test/fallback conventions, making the overall naming only moderately predictable.

    Tool Count1/5

    With 113 tools, the surface is far beyond a reasonable scope even for a feature-rich memory journal server. The extensive mirroring between personal and team databases, plus test/fallback handlers and auxiliary GitHub/git tools, makes the set heavy and hard to navigate.

    Completeness4/5

    The memory-journal domain is covered very thoroughly: CRUD, batch operations, search modes, tagging, relationships, imports/exports, backups, restore, vector indexing, statistics, and team collaboration all exist. Minor gaps remain, such as no obvious team restore-backup counterpart and limited GitHub issue lifecycle operations beyond close-with-entry.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers