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

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

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

"BRIEFING_ENTRY_COUNT": "1",
"BRIEFING_SUMMARY_COUNT": "0",
"INSTRUCTION_LEVEL": "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",
"INSTRUCTION_LEVEL": "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!

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.