Memory Journal

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)

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

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

Complete Hush Protocol guide and Mermaid sequence diagrams →

🚀 Quick Start

Option 1: npm (Recommended)

npm install -g memory-journal-mcp

Option 2: From Source

git clone https://github.com/neverinfamous/memory-journal-mcp.git
cd memory-journal-mcp
npm install
npm run build

Add to MCP Config

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

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

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": "memory-journal-mcp",
      "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",
        "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": "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, and active Hush Protocol flags.

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",
"INSTRUCTION_LEVEL": "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",
"INSTRUCTION_LEVEL": "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!

Option 3: HTTP/SSE Transport (Remote Access)

🔒 Security Posture: Stdio vs HTTP

• 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.
• HTTP/SSE: Exposes the server over a network socket. By default, HTTP binds ONLY to localhost and blocks wildcard CORS to prevent unauthorized access and CSRF attacks. Public network binding (--server-host 0.0.0.0) requires explicit authentication (--auth-token or --oauth-enabled). The server will throw a fatal error if you attempt to expose it publicly without securing it.

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

memory-journal-mcp --transport http --port 3000

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

export MCP_AUTH_TOKEN="your_secure_random_token"
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)
• 7 Security Headers — CSP, HSTS (opt-in), X-Frame-Options, and more
• Rate Limiting — 100 req/min per 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

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

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.

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

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.

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 \
  --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 OAUTH_ENABLED=true
export OAUTH_ISSUER=https://auth.example.com/realms/mcp
export OAUTH_AUDIENCE=memory-journal-mcp
export OAUTH_CLOCK_TOLERANCE=5
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

GitHub Integration (Optional)

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

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

GitHub Management Capabilities

Memory Journal provides a hybrid approach to GitHub management:

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

• get_github_issues / get_github_issue - Query issues
• get_github_prs / get_github_pr - Query pull requests
• get_github_context - Full repository context
• get_kanban_board / add_kanban_item / move_kanban_item / delete_kanban_item - Kanban management
• get_github_milestones / get_github_milestone - Milestone tracking with completion %
• create_github_milestone / update_github_milestone / delete_github_milestone - Milestone CRUD
• get_repo_insights - Repository traffic & analytics (stars, clones, views, referrers, popular paths)
• create_github_issue_with_entry / close_github_issue_with_entry - Issue lifecycle with journal linking

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 →

GitHub Commander Workflows

The server natively bundles the github-commander agent skill (accessible via memory://skills/github-commander). This extends your AI assistant with 9 autonomous DevOps workflows for repository stewardship: Issue Triage, Milestone Sprints, PR Reviews, Copilot Audits, Security Audits, Code Quality Audits, Performance Audits, Roadmap Kickoffs, and Dependency Updates. Configure validation layers using the PROJECT_* environment overrides to enforce CI-matching execution locally during agent tasks!

🏗️ Architecture

Data Flow

flowchart TB
    AI["🤖 AI Agent<br/>(Cursor, Windsurf, Claude)"]

    subgraph MCP["Memory Journal MCP Server"]
        Tools["🛠️ 73 Tools"]
        Resources["📡 46 Resources"]
        Prompts["💬 19 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 (73)      │  │ Resources (47)  │  │ Prompts (19)│  │
│  │ with Annotations│  │ with Annotations│  │             │  │
│  └─────────────────┘  └─────────────────┘  └─────────────┘  │
├─────────────────────────────────────────────────────────────┤
│ 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 to maintain these baseline guarantees:

• Database Reads: Operations execute in fractions of a millisecond. calculateImportance is ~13-14x faster than retrieving 50 recent entries.
• Vector Search Engine: Both search (~140-220 ops/sec) and indexing (~1600-1900+ ops/sec) are high-throughput via sqlite-vec with SQL-native KNN queries.
• Core MCP Routines: getTools uses cached O(1) dispatch (~4800-7000x faster than get_recent_entries). create_entry and search_entries execute through the full MCP layer with sub-millisecond overhead.

To run the benchmarking suite locally:

npm run bench

Testing

Extensively tested across two frameworks:

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

Security

• 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
• Path traversal protection - Backup filenames validated
• MCP 2025-03-26 annotations - Behavioral hints (readOnlyHint, destructiveHint, etc.)
• HTTP transport hardening - 7 security headers, configurable multi-origin CORS, 1MB body limit, built-in rate limiting (100 req/min), server timeouts, HSTS (opt-in), 30-min session timeout, 404 handler, cross-protocol guard
• Token scrubbing - GitHub tokens and credentials automatically redacted from error 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

• GitHub Wiki - Complete documentation
• Copilot Setup Guide - Cross-agent memory bridge between IDE agents and GitHub Copilot
• Deployment Guide - CI/CD pipeline, environments, and version bump checklist
• Docker Hub - Container images
• npm Package - Node.js distribution
• Issues - Bug reports & feature requests

📄 License

MIT License - See LICENSE file for details.

🤝 Contributing

Built by developers, for developers. PRs welcome! See CONTRIBUTING.md for guidelines.