Memory Journal MCP Server

Memory Journal MCP Server

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

---

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

🛑 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 include Code 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 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.

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

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:

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)

Documentation truncated — see the full README on GitHub.