writenotenow/memory-journal-mcp repository overview

⁠Memory Journal MCP Server

🎯 Persistent AI project memory. Bridge disconnected sessions and auto-resume context seamlessly.

GitHub⁠ • Wiki⁠ • Changelog⁠ • Release Article⁠

⁠🧠 Stop Experiencing AI Amnesia

When managing large projects with AI assistance, you face a critical challenge:

• Thread Amnesia - Each new conversation starts from zero, unaware of previous work.
• Lost Context - Decisions, implementations, and learnings scattered across disconnected threads.
• Repeated Work - AI suggests solutions you've already tried or abandoned.

Memory Journal solves this by acting as your project's long-term memory, bridging the gap between fragmented AI sessions.

Experience true context-aware development:

• "Why did we choose SQLite over Postgres for this service last month?" (Semantic search)
• "Run the /issue-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)
• "I'm stuck on this database error. Raise a 'blocker' flag for @sarah so her agent sees it next session." (Hush Protocol)
• "Close issue #42 and log an entry explaining our architectural fix for the parsing bug." (Context lifecycles)
• "Draw a visual graph showing how my last 10 architectural decisions relate to each other." (Knowledge graph)

See complete examples & prompts →⁠

⁠🎯 What Sets Us Apart

73 MCP Tools · 19 Workflow Prompts · 46 Resources · 10 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, Hush Protocol Flags)

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

⁠Tool Filtering

Control which tools are exposed via MEMORY_JOURNAL_MCP_TOOL_FILTER (or CLI: --tool-filter):

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, backup, team, codemode

Complete tool filtering guide →⁠

⁠📋 Core Capabilities

⁠🛠️ 73 MCP Tools (10 Groups)

Complete tools reference →⁠

⁠🎯 19 Workflow Prompts

Standups, retrospectives, PR summaries, weekly digests, period analysis, milestone tracking, context bundles, session summaries, adversarial plan reviews, and flag triage dashboards. Complete prompts guide →⁠

⁠📡 46 Resources (29 Static + 17 Template)

29 static resources (memory://briefing, memory://workflows, memory://rules, memory://health, memory://help, memory://flags, memory://flags/vocabulary, memory://flags/history, GitHub status/insights, team stats, and more) plus 17 template resources for dynamic briefings (memory://briefing/{repo}), project timelines, issue/PR entries, Kanban boards, milestone details, and per-group help. Resources documentation →⁠

⁠⚡ Code Mode: Maximum Efficiency (90% Token Savings)

Code Mode (mj_execute_code) is a revolutionary approach that dramatically 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 worker_threads sandbox with multiple layers of security. All mj.* API calls execute against the journal within the sandbox, providing:

• Static code validation — blocked patterns include require(), process, eval(), and filesystem access
• Rate limiting — 60 executions per minute per client
• Hard timeouts — configurable execution limit (default 30s)
• Full API access — all 10 tool groups are available via mj.* (e.g., mj.core.createEntry(), mj.search.searchEntries(), mj.github.getGithubIssues(), mj.team.passTeamFlag())
• Strict Readonly Contract — Calling any mutation method under --tool-filter readonly safely halts the sandbox to prevent execution, returning a structured error response to the agent instead of a raw MCP protocol exception.

⁠🤫 Hush Protocol: Asynchronous Team Collaboration

The Hush Protocol reimagines team collaboration for AI-augmented workflows by replacing noisy Slack/Teams messages with structured, machine-actionable flags.

When you encounter a blocker, need a review, or want to broadcast a milestone, your AI agent can raise a flag in the shared Team Database:

• Actionable Visibility: Active flags automatically surface at the very top of the memory://briefing payload for all team members. When another developer's agent starts a session, it immediately sees your blockers and can help resolve them autonomously.
• Structured Types: Raise specific flag types (blocker, needs_review, help_requested, fyi). You can customize your team's vocabulary via the --flag-vocabulary configuration.
• Searchable History: Unlike chat messages that disappear into the void, Hush flags are permanent, query-able AI journal entries. Your agents can search past needs_review flags to understand how architectural blockers were conquered.
• Full Lifecycle Management: List and filter flags by status, type, or assignee. Update metadata (escalate severity, reassign, add links). Reopen resolved flags. Track resolution velocity and team workload with built-in analytics.
• Resolution History: Read memory://flags/history to see recently resolved flags with resolution times and details.

Complete Hush Protocol guide and Mermaid sequence diagrams →⁠

⁠🚀 Quick Start (2 Minutes)

Prerequisites: Docker installed and running · ~250MB disk space · Full Installation Guide →⁠

⁠1. Pull the Image

docker pull writenotenow/memory-journal-mcp:latest

⁠2. Create Data Directory

mkdir data

⁠3. Add to MCP Config

Add this to your ~/.cursor/mcp.json, Claude Desktop config, or equivalent:

⁠Basic Configuration

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "./data:/app/data",
        "-e",
        "GITHUB_TOKEN",
        "-e",
        "PROJECT_REGISTRY={\"my-repo\":{\"path\":\"/app/repo\",\"project_number\":1}}",
        "-v",
        "/path/to/your/repo:/app/repo:ro",
        "writenotenow/memory-journal-mcp:latest"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "ALLOWED_IO_ROOTS": "/app/repo"
      }
    }
  }
}

⁠Advanced Configuration (Recommended)

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

{
  "mcpServers": {
    "memory-journal-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "./data:/app/data",
        "-e",
        "GITHUB_TOKEN",
        "-v",
        "/path/to/shared/team.db:/app/data/team.db:rw",
        "-v",
        "/path/to/your/projects:/app/projects:ro",
        "-v",
        "/path/to/rules.md:/app/rules.md:ro",
        "-v",
        "/path/to/skills:/app/skills:ro",
        "writenotenow/memory-journal-mcp:latest"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "TEAM_DB_PATH": "/app/data/team.db",
        "PROJECT_REGISTRY": "{\"my-repo\":{\"path\":\"/app/projects/repo1\",\"project_number\":1},\"other-repo\":{\"path\":\"/app/projects/repo2\",\"project_number\":5}}",
        "ALLOWED_IO_ROOTS": "/app/projects,/app/data,/app/skills",
        "AUTO_REBUILD_INDEX": "true",
        "MEMORY_JOURNAL_MCP_TOOL_FILTER": "codemode",
        "CODEMODE_INTERNAL_FULL_ACCESS": "true",
        "BRIEFING_ENTRY_COUNT": "3",
        "BRIEFING_SUMMARY_COUNT": "1",
        "BRIEFING_INCLUDE_TEAM": "true",
        "BRIEFING_ISSUE_COUNT": "1",
        "BRIEFING_PR_COUNT": "1",
        "BRIEFING_PR_STATUS": "true",
        "BRIEFING_WORKFLOW_COUNT": "1",
        "BRIEFING_WORKFLOW_STATUS": "true",
        "BRIEFING_COPILOT_REVIEWS": "true",
        "RULES_FILE_PATH": "/app/rules.md",
        "SKILLS_DIR_PATH": "/app/skills",
        "MEMORY_JOURNAL_WORKFLOW_SUMMARY": "/deploy: prod deployment | /audit: security scan",
        "AUDIT_LOG_PATH": "/app/data/mcp-audit.jsonl",
        "TEAM_AUTHOR": "your_username"
      }
    }
  }
}

⁠📋 Customizing the Session Briefing

The memory://briefing resource is dynamically assembled at each session start, automatically providing ambient context like test health, workspace paths, unreleased changes, and git status. Control what your agent sees by tuning three dimensions via environment variables:

• Depth — INSTRUCTION_LEVEL: essential, standard (default), or full
• Journal Content — BRIEFING_ENTRY_COUNT, BRIEFING_SUMMARY_COUNT, BRIEFING_INCLUDE_TEAM
• GitHub Enrichment — BRIEFING_ISSUE_COUNT, BRIEFING_PR_COUNT, BRIEFING_PR_STATUS, BRIEFING_MILESTONE_COUNT, BRIEFING_WORKFLOW_COUNT, BRIEFING_WORKFLOW_STATUS, BRIEFING_COPILOT_REVIEWS

Set RULES_FILE_PATH and SKILLS_DIR_PATH to surface agent rules and skills as companion resources. In multi-repo setups, agents read memory://briefing/{repo} for repo-scoped context.

Full briefing customization guide with presets →⁠

Variants (modify the config array above):

• Minimal: Remove -e GITHUB_TOKEN, repo mount, and env block.
• Team: Add -e "TEAM_DB_PATH=/app/data/team.db".
• Code Mode: Add "--tool-filter", "codemode".
• Briefing: Add -e "BRIEFING_ENTRY_COUNT=5".

⁠4. Restart & Journal!

Restart Cursor or your MCP client and start journaling!

⁠GitHub Integration Configuration

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.

For a complete list of all 30+ environment variables (including remote HTTP scheduling, payload truncations, context injection parameters, flag vocabulary, and audit logging), please refer to the Official Configuration Resource⁠ in our Wiki.

Multi-Project Workflows: For agents to seamlessly support multiple projects, provide PROJECT_REGISTRY.

⁠Context Resolution & Project Routing

Context resolution order: Dynamic PROJECT_REGISTRY routing → explicit owner/repo → blocks with {requiresUserInput: true}. Kanban/issue project numbers resolve via passed argument → PROJECT_REGISTRY lookup → global DEFAULT_PROJECT_NUMBER.

Full routing & auto-detection docs →⁠

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

⁠HTTP/SSE Transport (Remote Access)

For remote access, web-based clients, or HTTP-compatible MCP hosts. The server supports both stateful (SSE) and stateless (serverless) modes.

docker run --rm -p 3000:3000 \
  -v ./data:/app/data \
  writenotenow/memory-journal-mcp:latest \
  --transport http --port 3000 --server-host 0.0.0.0

• Features: OAuth 2.1, 7 Security Headers, Rate Limiting, CORS, and more.
• Stateless Mode: Add --stateless to the command above.

See the full HTTP/SSE Transport & Endpoints documentation in the Wiki →⁠

⁠Automated Scheduling (HTTP Only)

Enable periodic maintenance jobs (--backup-interval, --vacuum-interval, --rebuild-index-interval, --digest-interval) for long-running HTTP containers. See the full scheduling documentation in the Wiki →⁠

⁠🔐 OAuth 2.1 Authentication

For production deployments, enable full OAuth 2.1 support on the HTTP transport (opt-in via --oauth-enabled). Features include RFC 9728/8414 discovery, JWKS token validation, and granular scopes.

See the OAuth 2.1 Setup Guide in the Wiki →⁠

⁠🔧 Configuration

All detailed setup and configuration guides are available in our Wiki.

Complete Configuration Documentation →⁠

⁠📄 License

MIT License - See LICENSE⁠

Migrating from v2.x? Your existing database is fully compatible.