Memory Journal MCP Server

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

🎯 AI Context + Project Intelligence: Bridge disconnected AI sessions with persistent project memory and automatic session handoff — with full GitHub workflow integration.

🚀 Quick Deploy:

• npm Package - npm install -g memory-journal-mcp
• Docker Hub - Alpine-based with full semantic search

🧠 Stop Experiencing AI Amnesia

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

• Thread Amnesia - Each new AI 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.
• Context Overload - Manually copying project history into every new conversation.

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)

Feature	Description
Session Intelligence	Agents auto-query project history, create entries at checkpoints, and hand off context between sessions via /session-summary and team-session-summary
GitHub Integration	18 tools for Issues, PRs, Actions, Kanban, Milestones (%), Copilot Reviews, and 14-day Insights
Dynamic Project Routing	Seamlessly switch contexts and access CI/Issue tracking across multiple repositories using a single server instance via PROJECT_REGISTRY
Knowledge Graphs	8 relationship types linking specs → implementations → tests → PRs with Mermaid visualization
Hybrid Search	Reciprocal Rank Fusion combining FTS5 keywords, semantic vector similarity, auto-heuristics, and date-range filters
Code Mode	Execute multi-step operations in a trusted-admin execution environment — up to 90% token savings via mj.* API
Adaptive Session Briefing	memory://briefing dynamically adapts to deliver real-time workspace context — including live CI health, local Git status, dynamic path routing, and unreleased changes — in ~350 optimized tokens
Reports & Analytics	Standups, retrospectives, PR summaries, digests, period analyses, and milestone tracking
Hush Protocol (Flags)	Replace Slack/Teams noise with structured, actionable, and searchable AI flags (blockers, reviews) that automatically surface in session briefings
Team Collaboration	28 tools with full parity — CRUD, vector search, relationship graphs, cross-project insights, author attribution, Hush Protocol flags (list, update, reopen, analytics)
Data Interoperability	Bidirectional Markdown roundtripping, unified IO namespace, and schema-safe JSON exports with hard bounds-checked path traversal defenses
Backup & Restore	One-command backup/restore with automated scheduling, retention policies, and safety-net auto-backups
Auto-Pruning	Smart garbage collection based on significance scores to soft-delete low-value entries and maintain vector relevance over long-running projects
Security & Transport	OAuth 2.1 (RFC 9728/8414, JWT/JWKS, scopes), Streamable HTTP + SSE, rate limiting, CORS, SQL injection prevention, non-root Docker
Structured Error Handling	Every tool returns {success, error, code, category, suggestion, recoverable} — agents get classification, remediation hints, and recoverability signals
Agent Collaboration	IDE agents and Copilot share context; review findings become searchable knowledge; agents suggest reusable rules and skills (setup)
Native Agent Skills	Bundled foundational coding paradigms (autonomous-dev, python, docker, tailwind-css, golang, playwright-standard, etc.) establishing permanent AI behavior and architecture rules
GitHub Commander	Pipeline skills for issue triage, PR reviews, sprint milestones, and security/quality/performance audits with journal trails (docs)

---

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

🛑 MANDATORY SESSION START ROUTINE

Before addressing the user's first request in a session/thread, complete these steps:

1. Read the briefing using the read_resource tool: memory://briefing/{repo_name}.

   • Infer repo_name from context of user's prompt. Use memory://briefing as fallback only if necessary.

2. Your first response MUST begin with the entire briefing content. Use this format:

   📋 Briefing loaded — {repo_name}

   {paste ENTIRE briefing here} (It isn't always easy for users to access in IDEs)

3. Then address the user's request below the briefing.

4. Do NOT autonomously resume work on issues mentioned in the briefing.

---

Tool Filtering

[!IMPORTANT] All shortcuts and tool groups include Code Mode (mj_execute_code) by default for token-efficient operations. To exclude it, add -codemode to your filter: --tool-filter starter,-codemode

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

Filter	Tools	Use Case
full	73	All tools (default)
starter	~11	Core + search + codemode
essential	~7	Minimal footprint
readonly	17	Disable all mutations
-github	52	Exclude a group
-github,-analytics	50	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, backup, team, codemode

Complete tool filtering guide →

---

📋 Core Capabilities

🛠️ 73 MCP Tools (10 Groups)

Group	Tools	Description
codemode	1	Code Mode (sandboxed code execution) 🌟 Recommended
core	6	Entry CRUD, tags, test
search	4	Text search, date range, semantic, vector stats
analytics	2	Statistics, cross-project insights
relationships	2	Link entries, visualize graphs
io	3	JSON/Markdown export and File-level Markdown Data Integration Interoperability (Import/Export)
admin	5	Update, delete, rebuild/add to vector index, merge tags
github	18	Issues, PRs, context, Kanban, Milestones, Insights, issue lifecycle, Copilot Reviews
backup	4	Backup, list, restore, cleanup
team	28	CRUD, search, stats, relationships, IO (Markdown import/export), backup, vector search, cross-project insights, matrix, Hush Protocol flags (requires TEAM_DB_PATH)

Complete tools reference →

🎯 19 Workflow Prompts

• find-related - Discover connected entries via semantic similarity
• prepare-standup - Daily standup summaries
• prepare-retro - Sprint retrospectives
• weekly-digest - Day-by-day weekly summaries
• analyze-period - Deep period analysis with insights
• goal-tracker - Milestone and achievement tracking
• get-context-bundle - Project context with Git/GitHub/Kanban
• get-recent-entries - Formatted recent entries
• project-status-summary - GitHub Project status reports
• pr-summary - Pull request journal activity summary
• code-review-prep - Comprehensive PR review preparation
• pr-retrospective - Completed PR analysis with learnings
• actions-failure-digest - CI/CD failure analysis
• project-milestone-tracker - Milestone progress tracking
• confirm-briefing - Acknowledge session context to user
• session-summary - Create a session summary entry with accomplishments, pending items, and next-session context
• team-session-summary - Create a retrospective team session summary entry securely isolated to the team database
• adversarial-plan-review - Multi-pass adversarial plan review with structured dimensions, scoring rubric, and prior plan context
• flag-dashboard - Triage active flags with priority assessment and resolution guidance

Complete prompts guide →

📡 46 Resources (29 Static + 17 Template)

29 Static Resources (appear in resource lists):

• memory://briefing - Session initialization: compact context for AI agents (~350 tokens) — includes server version, surface area (tools/resources/prompts), test health, unreleased changes, analytics, localTime, and optional activeFlags
• memory://instructions - Behavioral guidance: complete server instructions for AI agents
• memory://recent - 10 most recent entries
• memory://significant - Significant milestones and breakthroughs
• memory://graph/recent - Live Mermaid diagram of recent relationships
• memory://health - Server health & diagnostics
• memory://graph/actions - CI/CD narrative graph
• memory://actions/recent - Recent workflow runs
• memory://tags - All tags with usage counts
• memory://statistics - Journal statistics
• memory://rules - User rules file content for agent awareness
• memory://workflows - Available agent workflows summary
• memory://skills - Agent skills index (names, paths, excerpts)
• memory://github/status - GitHub repository status overview
• memory://github/insights - Repository stars, forks, and 14-day traffic summary
• memory://github/milestones - Open milestones with completion percentages
• memory://team/recent - Recent team entries with author attribution
• memory://team/statistics - Team entry counts, types, and author breakdown
• memory://help - Tool group index with descriptions and tool counts
• memory://metrics/summary - Aggregate tool call metrics since server start (calls, errors, token estimates, duration) — HIGH priority
• memory://metrics/tokens - Per-tool token usage breakdown sorted by output token cost — MEDIUM priority
• memory://metrics/system - Process-level metrics: memory (MB), uptime (s), Node.js version, platform — MEDIUM priority
• memory://metrics/users - Per-user call counts (populated when OAuth user identifiers are present) — LOW priority
• memory://audit - Last 50 write/admin tool call entries from the JSONL operational telemetry log (requires AUDIT_LOG_PATH)
• memory://flags - Active (unresolved) team flags dashboard (requires TEAM_DB_PATH)
• memory://flags/vocabulary - Configured flag vocabulary terms
• memory://flags/history - Recently resolved flags with resolution details and avg time-to-resolution (last 7 days)

17 Template Resources (9 base templates + 8 dynamic {repo} variants):

• memory://projects/{number}/timeline - Project activity timeline
• memory://issues/{issue_number}/entries - Entries linked to issue
• memory://prs/{pr_number}/entries - Entries linked to PR
• memory://prs/{pr_number}/timeline - Combined PR + journal timeline
• memory://kanban/{project_number} - GitHub Project Kanban board
• memory://kanban/{project_number}/diagram - Kanban Mermaid visualization
• memory://milestones/{number} - Milestone detail with completion progress
• memory://help/{group} - Per-group tool reference with parameters and annotations
• memory://briefing/{repo} - Context targeted to a specific repository

Note: The memory://github/status, memory://github/insights, memory://github/milestones, and memory://milestones/{number} resources also accept an optional /{repo} path suffix for cross-repo targeting.

---

⚡ 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 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 — all built-in prototypes (Object, Function, Array, Error, etc.) frozen inside the vm context to prevent dynamic constructor chain escapes
• Static code validation — 18 regex rules blocking require(), process, eval(), Reflect.*, Symbol.*, new Proxy(), and filesystem/network access
• Proxy constructor nullified — Proxy: undefined in the sandbox prevents meta-object protocol abuse
• RPC allowlist — host-side validation prevents workers from invoking unauthorized API methods
• Rate limiting — 60 executions per minute per client
• Hard timeouts — configurable execution limit (default 30s)
• Egress boundary enforcement — result serialization capped to prevent OOM via oversized payloads
• 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 { success: false, error: "..." } response to the agent instead of a raw MCP protocol exception.

⚡ Code Mode Only (Maximum Token Savings)

Run with only Code Mode enabled — a single tool that provides access to all 69 tools' worth of capability through the mj.* API:

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

This exposes just mj_execute_code. The agent writes JavaScript against the typed mj.* SDK — composing operations across all 10 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.

Disabling Code Mode

If you prefer individual tool calls, exclude codemode:

{
  "args": ["--tool-filter", "starter,-codemode"]
}

---

🤫 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.
• Integrated Standup & Retro Signals: Active flags automatically appear as contextual signals in the prepare-standup and prepare-retro prompts, so your daily standups and sprint retrospectives always surface outstanding blockers.
• Full Lifecycle Management: List and filter flags by status, type, or assignee via team_list_flags. Update metadata (escalate severity, reassign, add links) or reopen resolved flags via team_update_flag. Track resolution velocity, per-user workload, and trends with team_get_flag_analytics.

Dashboard & Operations: Read memory://flags for an active dashboard, memory://flags/history for recently resolved flags, use the /flag-dashboard prompt for guided triage with severity grouping and staleness detection, and use mj.team.passTeamFlag() / mj.team.resolveTeamFlag() / mj.team.teamListFlags() / mj.team.teamUpdateFlag() / mj.team.teamGetFlagAnalytics() to manage flags programmatically in Code Mode.