Memory Journal Server

GitHub npm Docker Pulls License: MIT MCP Registry Security GitHub Stars TypeScript Benchmarks CI

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

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.

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

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)

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 \
  --allowed-io-roots /path/to/projects \
  --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 ALLOWED_IO_ROOTS="/path/to/projects"
export OAUTH_ENABLED=true
export OAUTH_ISSUER=https://auth.example.com/realms/mcp
export OAUTH_AUDIENCE=memory-journal-mcp
export OAUTH_JWKS_URI=https://auth.example.com/realms/mcp/protocol/openid-connect/certs
export OAUTH_CLOCK_TOLERANCE=60
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

Environment Variables

GitHub Integration (Optional)

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

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

Manage GitHub Seamlessly

Memory Journal provides a hybrid approach to GitHub management:

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

See the Complete tools reference for all supported GitHub integration capabilities, including query commands, Kanban management, milestone tracking, analytics, and issue lifecycle events.

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 →

Automate with GitHub Commander Workflows

The server natively bundles the memory-journal-mcp agent skill (served via SEP-2640 and memory://skills). It also provides built-in issue-commander, pr-commander, and cms-rem-supervisor MCP workflow prompts for autonomous DevOps stewardship: Issue Triage, Milestone Sprints, PR Reviews, Copilot Audits, Security Audits, Code Quality Audits, Performance Audits, Roadmap Kickoffs, and Dependency Updates. These workflows enforce multi-gate validation (lint, typecheck, test, and security checks) locally during agent tasks.

🏗️ Architecture

Data Flow

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

    subgraph MCP["MCP Server Capabilities"]
        direction LR
        Tools["🛠️ MCP Tools"]
        Resources["📡 Resources"]
        Prompts["💬 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           │  │ Resources       │  │ Prompts     │  │
│  └─────────────────┘  └─────────────────┘  └─────────────┘  │
├─────────────────────────────────────────────────────────────┤
│ 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 across database, vector search, and MCP server routines to maintain these baseline guarantees:

• Database Operations (sqlite-adapter.bench.ts): calculateImportance runs at ~51,600 ops/sec (~0.03ms mean, ~27x faster than retrieving 50 recent entries) via a 256-entry LRU prepared statement cache. getRecentEntries (limit 50) executes at ~1,870 ops/sec (~0.63ms mean), updateEntry at ~2,380 ops/sec (~0.79ms mean), createEntry at ~1,060 ops/sec (~1.69ms mean), and searchEntries (FTS5 BM25 + batch importance hydration) at ~176 ops/sec (~6.2ms mean).
• Vector Search Engine (vector-search.bench.ts): Both k-NN similarity search (~1,050 ops/sec, ~1.8ms mean with batch entry hydration) and vector indexing (~4,220 ops/sec, ~0.41ms mean) are high-throughput via sqlite-vec (vec0 with chunk_size=256).
• Core MCP Routines (mcp-server.bench.ts): getTools uses cached O(1) dispatch (~7.2M–9.4M ops/sec, ~0.0001ms). Full end-to-end callTool invocations (including interceptor, token estimation, and project registry resolution) run at ~1,775 ops/sec (~0.65ms) for get_recent_entries, ~205 ops/sec (~5.4ms) for search_entries, and ~800 ops/sec (~2.4ms) for create_entry.

To run the benchmarking suite locally:

pnpm run bench

Testing

Extensively tested across two frameworks:

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

Security

Note: When updating schemas or validation logic, please refer to the /zod skill for best practices on Standard Schema and Safe Parsing.

• 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, and <untrusted_remote_content> prompt-injection boundary tagging
• Path traversal & SSRF protection - ALLOWED_IO_ROOTS sandbox containment with URL-decode/symlink verification, backup path validation, and outbound webhook DNS/IP SSRF blocking
• Multi-tenant & filter enforcement - End-to-end workspace_id isolation across SQLite and Vector search, plus execution-layer --tool-filter enforcement across tools/call, Code Mode (mj.*), and fallback handlers
• MCP 2025-11-25 annotations & icons - Behavioral hints (readOnlyHint, destructiveHint, etc.) and capability icons
• HTTP transport hardening - OAuth 2.1 tokenClaims propagation, principal-bound stateful sessions (100 max active sessions), comprehensive security headers, configurable multi-origin CORS, 1MB body/stream limit, built-in per-subject/IP rate limiting (100 req/min), server timeouts, HSTS (opt-in), 30-min session timeout, and localhost-bound metrics (METRICS_EXPORT=prometheus automatically starts the standalone metrics server on 127.0.0.1:9465, customizable via MJ_METRICS_PORT and MJ_METRICS_HOST, in addition to mounting /metrics on the HTTP transport)
• Token scrubbing - GitHub tokens and credentials automatically redacted from error and audit 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! Ensure all unit and E2E tests, linting, and typechecks pass. See CONTRIBUTING.md for guidelines.

Upgrading from an earlier version? Your existing SQLite database is automatically migrated on startup.