Memory Journal MCP Server

📚 Full Documentation (Wiki) • Changelog • Security • Release Article

🚀 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 →

🎯 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)

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.)

Control Access with Tool Filtering

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 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

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:

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.

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

"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"

"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):

Restart your MCP client and start journaling!

Connect Remotely with HTTP/SSE Transport

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:

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

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

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:

Supported Scopes:

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