View Mandatory Session Start Routine

\n\n🛑 MANDATORY SESSION START ROUTINE\n\nBefore addressing the user's first request in a session/thread, complete these steps:\n\n1. Read the briefing using the `read_resource` tool: `memory://briefing/{repo_name}`.\n - Infer `repo_name` from context of user's prompt. Use `memory://briefing` as fallback only if necessary.\n2. Your first response MUST begin with the entire briefing content. Use this format:\n\n > **📋 Briefing loaded** — `{repo_name}`\n >\n > _{paste **ENTIRE** briefing here}_ (It isn't always easy for users to access in IDEs)\n\n3. Then address the user's request below the briefing.\n4. Do NOT autonomously resume work on issues mentioned in the briefing.\n

\n\n---\n\n### Tool Filtering\n\n> [!IMPORTANT]\n> 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`\n\nControl which tools are exposed via `MEMORY_JOURNAL_MCP_TOOL_FILTER` (or CLI: `--tool-filter`):\n\n| Filter | Tools | Use Case |\n| -------------------- | ----- | ------------------------ |\n| `full` | 73 | All tools (default) |\n| `starter` | ~11 | Core + search + codemode |\n| `essential` | ~7 | Minimal footprint |\n| `readonly` | 17 | Disable all mutations |\n| `-github` | 52 | Exclude a group |\n| `-github,-analytics` | 50 | Exclude multiple groups |\n\n**Filter Syntax:** `shortcut` or `group` or `tool_name` (whitelist mode) · `-group` (disable group) · `-tool` (disable tool) · `+tool` (re-enable after group disable)\n\n**Custom Selection:** List individual tool names to create your own whitelist: `--tool-filter \"create_entry,search_entries,semantic_search\"`\n\n**Groups:** `core`, `search`, `analytics`, `relationships`, `io`, `admin`, `github`, `backup`, `team`, `codemode`\n\n**[Complete tool filtering guide →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Tool-Filtering)**\n\n---\n\n## 📋 Core Capabilities\n\n### 🛠️ **73 MCP Tools** (10 Groups)\n\n| Group | Tools | Description |\n| --------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `codemode` | 1 | Code Mode (sandboxed code execution) 🌟 **Recommended** |\n| `core` | 6 | Entry CRUD, tags, test |\n| `search` | 4 | Text search, date range, semantic, vector stats |\n| `analytics` | 2 | Statistics, cross-project insights |\n| `relationships` | 2 | Link entries, visualize graphs |\n| `io` | 3 | JSON/Markdown export and File-level Markdown Data Integration Interoperability (Import/Export) |\n| `admin` | 5 | Update, delete, rebuild/add to vector index, merge tags |\n| `github` | 18 | Issues, PRs, context, Kanban, **Milestones**, **Insights**, **issue lifecycle**, **Copilot Reviews** |\n| `backup` | 4 | Backup, list, restore, cleanup |\n| `team` | 28 | CRUD, search, stats, relationships, IO (Markdown import/export), backup, vector search, cross-project insights, matrix, **Hush Protocol flags** (requires `TEAM_DB_PATH`) |\n\n**[Complete tools reference →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Tools)**\n\n### 🎯 **19 Workflow Prompts**\n\n- `find-related` - Discover connected entries via semantic similarity\n- `prepare-standup` - Daily standup summaries\n- `prepare-retro` - Sprint retrospectives\n- `weekly-digest` - Day-by-day weekly summaries\n- `analyze-period` - Deep period analysis with insights\n- `goal-tracker` - Milestone and achievement tracking\n- `get-context-bundle` - Project context with Git/GitHub/Kanban\n- `get-recent-entries` - Formatted recent entries\n- `project-status-summary` - GitHub Project status reports\n- `pr-summary` - Pull request journal activity summary\n- `code-review-prep` - Comprehensive PR review preparation\n- `pr-retrospective` - Completed PR analysis with learnings\n- `actions-failure-digest` - CI/CD failure analysis\n- `project-milestone-tracker` - Milestone progress tracking\n- `confirm-briefing` - Acknowledge session context to user\n- `session-summary` - Create a session summary entry with accomplishments, pending items, and next-session context\n- `team-session-summary` - Create a retrospective team session summary entry securely isolated to the team database\n- `adversarial-plan-review` - Multi-pass adversarial plan review with structured dimensions, scoring rubric, and prior plan context\n- `flag-dashboard` - Triage active flags with priority assessment and resolution guidance\n\n**[Complete prompts guide →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Prompts)**\n\n### 📡 **46 Resources** (29 Static + 17 Template)\n\n**29 Static Resources** (appear in resource lists):\n\n- `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`\n- `memory://instructions` - **Behavioral guidance**: complete server instructions for AI agents\n- `memory://recent` - 10 most recent entries\n- `memory://significant` - Significant milestones and breakthroughs\n- `memory://graph/recent` - Live Mermaid diagram of recent relationships\n- `memory://health` - Server health & diagnostics\n- `memory://graph/actions` - CI/CD narrative graph\n- `memory://actions/recent` - Recent workflow runs\n- `memory://tags` - All tags with usage counts\n- `memory://statistics` - Journal statistics\n- `memory://rules` - User rules file content for agent awareness\n- `memory://workflows` - Available agent workflows summary\n- `memory://skills` - Agent skills index (names, paths, excerpts)\n- `memory://github/status` - GitHub repository status overview\n- `memory://github/insights` - Repository stars, forks, and 14-day traffic summary\n- `memory://github/milestones` - Open milestones with completion percentages\n- `memory://team/recent` - Recent team entries with author attribution\n- `memory://team/statistics` - Team entry counts, types, and author breakdown\n- `memory://help` - Tool group index with descriptions and tool counts\n- `memory://metrics/summary` - Aggregate tool call metrics since server start (calls, errors, token estimates, duration) — HIGH priority\n- `memory://metrics/tokens` - Per-tool token usage breakdown sorted by output token cost — MEDIUM priority\n- `memory://metrics/system` - Process-level metrics: memory (MB), uptime (s), Node.js version, platform — MEDIUM priority\n- `memory://metrics/users` - Per-user call counts (populated when OAuth user identifiers are present) — LOW priority\n- `memory://audit` - Last 50 write/admin tool call entries from the JSONL operational telemetry log (requires `AUDIT_LOG_PATH`)\n- `memory://flags` - Active (unresolved) team flags dashboard (requires `TEAM_DB_PATH`)\n- `memory://flags/vocabulary` - Configured flag vocabulary terms\n- `memory://flags/history` - Recently resolved flags with resolution details and avg time-to-resolution (last 7 days)\n\n**17 Template Resources** (9 base templates + 8 dynamic `{repo}` variants):\n\n- `memory://projects/{number}/timeline` - Project activity timeline\n- `memory://issues/{issue_number}/entries` - Entries linked to issue\n- `memory://prs/{pr_number}/entries` - Entries linked to PR\n- `memory://prs/{pr_number}/timeline` - Combined PR + journal timeline\n- `memory://kanban/{project_number}` - GitHub Project Kanban board\n- `memory://kanban/{project_number}/diagram` - Kanban Mermaid visualization\n- `memory://milestones/{number}` - Milestone detail with completion progress\n- `memory://help/{group}` - Per-group tool reference with parameters and annotations\n- `memory://briefing/{repo}` - Context targeted to a specific repository\n\n_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._\n\n---\n\n## ⚡ Code Mode: Maximum Efficiency (90% Token Savings)\n\nCode 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.\n\nCode 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:\n\n- **V8 code generation restrictions** — `eval()` and `Function()` construction from strings disabled at the V8 engine level via `codeGeneration: { strings: false, wasm: false }`\n- **Frozen prototypes** — all built-in prototypes (Object, Function, Array, Error, etc.) frozen inside the vm context to prevent dynamic constructor chain escapes\n- **Static code validation** — 18 regex rules blocking `require()`, `process`, `eval()`, `Reflect.*`, `Symbol.*`, `new Proxy()`, and filesystem/network access\n- **Proxy constructor nullified** — `Proxy: undefined` in the sandbox prevents meta-object protocol abuse\n- **RPC allowlist** — host-side validation prevents workers from invoking unauthorized API methods\n- **Rate limiting** — 60 executions per minute per client\n- **Hard timeouts** — configurable execution limit (default 30s)\n- **Egress boundary enforcement** — result serialization capped to prevent OOM via oversized payloads\n- **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()`)\n- **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.\n\n### ⚡ Code Mode Only (Maximum Token Savings)\n\nRun with **only Code Mode enabled** — a single tool that provides access to all 69 tools' worth of capability through the `mj.*` API:\n\n```json\n{\n \"mcpServers\": {\n \"memory-journal-mcp\": {\n \"command\": \"memory-journal-mcp\",\n \"args\": [\"--tool-filter\", \"codemode\"]\n }\n }\n}\n```\n\nThis 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](https://blog.cloudflare.com/code-mode-mcp/) pioneered by Cloudflare for their entire API: fixed token cost regardless of how many capabilities exist.\n\n#### Disabling Code Mode\n\nIf you prefer individual tool calls, exclude codemode:\n\n```json\n{\n \"args\": [\"--tool-filter\", \"starter,-codemode\"]\n}\n```\n\n---\n\n## 🤫 Hush Protocol: Asynchronous Team Collaboration\n\nThe **Hush Protocol** reimagines team collaboration for AI-augmented workflows by replacing noisy Slack/Teams messages with structured, machine-actionable flags.\n\nWhen 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:\n\n- **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.\n- **Structured Types**: Raise specific flag types (`blocker`, `needs_review`, `help_requested`, `fyi`). You can customize your team's vocabulary via the `--flag-vocabulary` configuration.\n- **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.\n- **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.\n- **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`.\n\n**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.\n\n**[Complete Hush Protocol guide and Mermaid sequence diagrams →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Hush-Protocol)**\n\n---\n\n## 🚀 Quick Start\n\n### Option 1: npm (Recommended)\n\n```bash\nnpm install -g memory-journal-mcp\n```\n\n### Option 2: From Source\n\n```bash\ngit clone https://github.com/neverinfamous/memory-journal-mcp.git\ncd memory-journal-mcp\nnpm install\nnpm run build\n```\n\n### Add to MCP Config\n\nAdd this to your `~/.cursor/mcp.json`, Claude Desktop config, or equivalent:\n\n### Basic Configuration\n\n```json\n{\n \"mcpServers\": {\n \"memory-journal-mcp\": {\n \"command\": \"memory-journal-mcp\",\n \"env\": {\n \"GITHUB_TOKEN\": \"ghp_your_token_here\",\n \"PROJECT_REGISTRY\": \"{\\\"my-repo\\\":{\\\"path\\\":\\\"/path/to/your/git/repo\\\",\\\"project_number\\\":1}}\",\n \"ALLOWED_IO_ROOTS\": \"/path/to/your/git/repo\"\n }\n }\n }\n}\n```\n\n### Advanced Configuration (Recommended)\n\nShowcasing the full power of the server, including Multi-Project Routing, Team Collaboration, Copilot awareness, and Context Injections.\n\n```json\n{\n \"mcpServers\": {\n \"memory-journal-mcp\": {\n \"command\": \"memory-journal-mcp\",\n \"env\": {\n \"DB_PATH\": \"/path/to/your/memory_journal.db\",\n \"TEAM_DB_PATH\": \"/path/to/shared/team.db\",\n \"GITHUB_TOKEN\": \"ghp_your_token_here\",\n \"PROJECT_REGISTRY\": \"{\\\"my-repo\\\":{\\\"path\\\":\\\"/path/to/repo\\\",\\\"project_number\\\":1},\\\"other-repo\\\":{\\\"path\\\":\\\"/path/to/other\\\",\\\"project_number\\\":5}}\",\n \"ALLOWED_IO_ROOTS\": \"/path/to/repo,/path/to/other,/path/to/your/skills\",\n \"AUTO_REBUILD_INDEX\": \"true\",\n \"MEMORY_JOURNAL_MCP_TOOL_FILTER\": \"codemode\",\n \"CODEMODE_INTERNAL_FULL_ACCESS\": \"true\",\n \"BRIEFING_ENTRY_COUNT\": \"3\",\n \"BRIEFING_SUMMARY_COUNT\": \"1\",\n \"BRIEFING_INCLUDE_TEAM\": \"true\",\n \"BRIEFING_ISSUE_COUNT\": \"3\",\n \"BRIEFING_PR_COUNT\": \"3\",\n \"BRIEFING_PR_STATUS\": \"true\",\n \"BRIEFING_WORKFLOW_COUNT\": \"3\",\n \"BRIEFING_WORKFLOW_STATUS\": \"true\",\n \"BRIEFING_COPILOT_REVIEWS\": \"true\",\n \"RULES_FILE_PATH\": \"/path/to/your/RULES.md\",\n \"SKILLS_DIR_PATH\": \"/path/to/your/skills\",\n \"MEMORY_JOURNAL_WORKFLOW_SUMMARY\": \"/deploy: prod deployment | /audit: security scan\",\n \"AUDIT_LOG_PATH\": \"/path/to/your/mcp-audit.jsonl\",\n \"TEAM_AUTHOR\": \"your_username\"\n }\n }\n }\n}\n```\n\n> 💡 **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!\n\n### 📋 Customizing the Session Briefing\n\nThe `memory://briefing` resource is **dynamically assembled** at each session start to provide rich, token-efficient ambient context. By default, it automatically surfaces:\n\n- **System State:** Server version, capability statuses, resource/tool counts, test health, and `memory://metrics/summary` breadcrumbs.\n- **Repository Context:** Git working tree status, unreleased changes, exact code-map paths, and prioritized gatekeeper CI workflows.\n- **Ambient Context:** Active workspace paths, local time, analytics, and active Hush Protocol flags.\n\nYou control exactly what additional content your agent sees across three dimensions:\n\n| Dimension | Variables | What It Controls |\n| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |\n| **Depth** | `INSTRUCTION_LEVEL` | Behavioral guidance verbosity: `essential`, `standard` (default), `full` |\n| **Journal Content** | `BRIEFING_ENTRY_COUNT`, `BRIEFING_SUMMARY_COUNT`, `BRIEFING_INCLUDE_TEAM` | How many recent entries, session summaries, and whether team entries appear |\n| **GitHub Enrichment** | `BRIEFING_ISSUE_COUNT`, `BRIEFING_PR_COUNT`, `BRIEFING_PR_STATUS`, `BRIEFING_MILESTONE_COUNT`, `BRIEFING_WORKFLOW_COUNT`, `BRIEFING_WORKFLOW_STATUS`, `BRIEFING_COPILOT_REVIEWS` | Issues, PRs, milestones, CI runs, and Copilot review state surfaced in the briefing |\n\n**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.\n\n**Repo Targeting:** In multi-repo setups, agents read `memory://briefing/{repo}` to get a briefing scoped to a specific repository registered in `PROJECT_REGISTRY`.\n\n

Briefing Presets (click to expand)

\n\n**Minimal (fast sessions)** — Reduce briefing to bare essentials for quick interactions:\n\n```json\n\"BRIEFING_ENTRY_COUNT\": \"1\",\n\"BRIEFING_SUMMARY_COUNT\": \"0\",\n\"INSTRUCTION_LEVEL\": \"essential\"\n```\n\n**Full Context (onboarding agents)** — Maximize context for agents unfamiliar with the project:\n\n```json\n\"BRIEFING_ENTRY_COUNT\": \"5\",\n\"BRIEFING_SUMMARY_COUNT\": \"3\",\n\"BRIEFING_INCLUDE_TEAM\": \"true\",\n\"BRIEFING_ISSUE_COUNT\": \"5\",\n\"BRIEFING_PR_COUNT\": \"3\",\n\"BRIEFING_PR_STATUS\": \"true\",\n\"BRIEFING_COPILOT_REVIEWS\": \"true\",\n\"INSTRUCTION_LEVEL\": \"full\"\n```\n\n**DevOps-Heavy** — Emphasize CI/CD and GitHub state for infrastructure workflows:\n\n```json\n\"BRIEFING_WORKFLOW_COUNT\": \"5\",\n\"BRIEFING_WORKFLOW_STATUS\": \"true\",\n\"BRIEFING_ISSUE_COUNT\": \"3\",\n\"BRIEFING_PR_COUNT\": \"3\",\n\"BRIEFING_PR_STATUS\": \"true\",\n\"BRIEFING_COPILOT_REVIEWS\": \"true\"\n```\n\n

\n\n**[Full briefing customization guide →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Configuration#session-briefing-customization)**\n\n**Variants** (modify the config above):\n\n| Variant | Change |\n| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| **Minimal (no GitHub)** | Remove the `env` block entirely |\n| **npx (no install)** | Replace `\"command\"` with `\"npx\"` and add `\"args\": [\"-y\", \"memory-journal-mcp\"]` |\n| **From source** | Replace `\"command\"` with `\"node\"` and add `\"args\": [\"dist/cli.js\"]` |\n| **Code Mode only** | Add `\"args\": [\"--tool-filter\", \"codemode\"]` (single tool, all capabilities) |\n| **Docker** | Replace `\"command\"` with `\"docker\"` and use `run -i --rm -v ./data:/app/data writenotenow/memory-journal-mcp:latest` as args |\n| **Team collaboration** | Add `\"TEAM_DB_PATH\": \"./team.db\"` to `env` |\n\nRestart your MCP client and start journaling!\n\n### Option 3: HTTP/SSE Transport (Remote Access)\n\n> 🔒 **Security Posture: Stdio vs HTTP**\n>\n> - **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.\n> - **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.\n\nFor remote access or web-based clients, run the server in HTTP mode:\n\n```bash\nmemory-journal-mcp --transport http --port 3000\n```\n\nTo bind to all interfaces (required for containers) and enable the automated proactive analytics scheduler (e.g. daily digest), you MUST provide an authentication token:\n\n```bash\nexport MCP_AUTH_TOKEN=\"your_secure_random_token\"\nmemory-journal-mcp --transport http --port 3000 --server-host 0.0.0.0 --digest-interval 1440\n```\n\n**Endpoints:**\n\n| Endpoint | Description | Mode |\n| ------------------------------------------- | ------------------------------------------------ | -------- |\n| `GET /` | Server info and available endpoints | Both |\n| `POST /mcp` | JSON-RPC requests (initialize, tools/call, etc.) | Both |\n| `GET /mcp` | SSE stream for server-to-client notifications | Stateful |\n| `DELETE /mcp` | Session termination | Stateful |\n| `GET /sse` | Legacy SSE connection (MCP 2024-11-05) | Stateful |\n| `POST /messages` | Legacy SSE message endpoint | Stateful |\n| `GET /health` | Health check (`{ status, timestamp }`) | Both |\n| `GET /.well-known/oauth-protected-resource` | RFC 9728 Protected Resource Metadata | Both |\n\n**Session Management:** The server uses stateful sessions by default. Include the `mcp-session-id` header (returned from initialization) in subsequent requests.\n\n- **OAuth 2.1** — RFC 9728/8414, JWT/JWKS, granular scopes (opt-in via `--oauth-enabled`)\n- **7 Security Headers** — CSP, HSTS (opt-in), X-Frame-Options, and more\n- **Rate Limiting** — 100 req/min per IP · **CORS** — configurable multi-origin (exact-match) · **1MB body limit**\n- **Server Timeouts** — Request (120s), keep-alive (65s), headers (66s) · **404 handler** · **Cross-protocol guard**\n- **Build Provenance** · **SBOM** · **Supply Chain Attestations** · **Non-root execution**\n\n**Example with curl:**\n\nInitialize session (returns `mcp-session-id` header):\n\n```bash\ncurl -X POST http://localhost:3000/mcp \\\n -H \"Content-Type: application/json\" \\\n -H \"Accept: application/json, text/event-stream\" \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-03-26\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}'\n```\n\nList tools (with session):\n\n```bash\ncurl -X POST http://localhost:3000/mcp \\\n -H \"Content-Type: application/json\" \\\n -H \"Accept: application/json, text/event-stream\" \\\n -H \"mcp-session-id: YOUR_SESSION_ID\" \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}'\n```\n\n#### Stateless Mode (Serverless)\n\nFor serverless deployments (Lambda, Workers, Vercel), use stateless mode:\n\n```bash\nmemory-journal-mcp --transport http --port 3000 --stateless\n```\n\n| Mode | Progress Notifications | Legacy SSE | Serverless |\n| ------------------------- | ---------------------- | ---------- | ---------- |\n| Stateful (default) | ✅ Yes | ✅ Yes | ⚠️ Complex |\n| Stateless (`--stateless`) | ❌ No | ❌ No | ✅ Native |\n\n#### Automated Scheduling (HTTP Only)\n\nWhen running in HTTP/SSE mode, enable periodic maintenance jobs with CLI flags. These jobs run in-process on `setInterval` — no external cron needed.\n\n> **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.\n\n```bash\nmemory-journal-mcp --transport http --port 3000 \\\n --backup-interval 60 --keep-backups 10 \\\n --vacuum-interval 1440 \\\n --rebuild-index-interval 720\n```\n\n| Flag | Default | Description |\n| -------------------------------- | ------- | -------------------------------------------------------------------- |\n| `--backup-interval ` | 0 (off) | Create timestamped database backups and prune old ones automatically |\n| `--keep-backups ` | 5 | Max backups retained during automated cleanup |\n| `--vacuum-interval ` | 0 (off) | Run `PRAGMA optimize` and flush database to disk |\n| `--rebuild-index-interval ` | 0 (off) | Full vector index rebuild to maintain semantic search quality |\n\nEach 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`.\n\n### GitHub Integration Configuration\n\nThe 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.\n\n| Environment Variable | Description |\n| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `DB_PATH` | Database file location (CLI: `--db`; default: `./memory_journal.db`) |\n| `TEAM_DB_PATH` | Team database file location (CLI: `--team-db`) |\n| `TEAM_AUTHOR` | Override author name for team entries (default: `git config user.name`) |\n| `GITHUB_TOKEN` | GitHub personal access token for API access |\n| `DEFAULT_PROJECT_NUMBER` | Default GitHub Project number for auto-assignment when creating issues |\n| `PROJECT_REGISTRY` | JSON map of repos to `{ path, project_number }` for multi-project auto-detection and routing |\n| `AUTO_REBUILD_INDEX` | Set to `true` to rebuild vector index on server startup |\n| `MCP_HOST` | Server bind host (`0.0.0.0` for containers, default: `localhost`) |\n| `MCP_AUTH_TOKEN` | Bearer token for HTTP transport authentication (CLI: `--auth-token`). Must NOT be the default placeholder token. |\n| `ALLOWED_IO_ROOTS` | **Critical Security Boundary**: Comma-separated absolute paths granting filesystem access to Code Mode and export tools (default: none / fail-closed) |\n| `MCP_CORS_ORIGIN` | Allowed CORS origins for HTTP transport, comma-separated (default: blank, strict opt-in) |\n| `TRUST_PROXY` | Trust proxy headers for rate limiting and origin checks (CLI: `--trust-proxy`; default: `false`) |\n| `PUBLIC_ORIGIN` | Public origin URL for OAuth redirect URIs (CLI: `--public-origin`) |\n| `MCP_RATE_LIMIT_MAX` | Max requests per minute per client IP, HTTP only (default: `100`) |\n| `LOG_LEVEL` | Log verbosity: `error`, `warn`, `info`, `debug` (default: `info`; CLI: `--log-level`) |\n| `MCP_ENABLE_HSTS` | Enable HSTS security header on HTTP responses (CLI: `--enable-hsts`; default: `false`) |\n| `OAUTH_ENABLED` | Set to `true` to enable OAuth 2.1 authentication (HTTP only) |\n| `OAUTH_ISSUER` | OAuth issuer URL (e.g., `https://auth.example.com/realms/mcp`) |\n| `OAUTH_AUDIENCE` | Expected JWT audience claim |\n| `OAUTH_JWKS_URI` | JWKS endpoint for token signature verification |\n| `OAUTH_ALLOW_PLAINTEXT_LOOPBACK` | Allow plaintext HTTP loopback redirect URIs for local OAuth clients (CLI: `--oauth-allow-plaintext-loopback`; default: `false`) |\n| `OAUTH_CLOCK_TOLERANCE` | Allowed clock skew tolerance in seconds for JWT verification (default: `5`) |\n| `CODE_MODE_MAX_RESULT_SIZE` | Maximum size in bytes for mj_execute_code result payload (CLI: `--codemode-max-result-size`; default: `102400`) |\n| `CODEMODE_INTERNAL_FULL_ACCESS` | Bypass tool filter constraints within the Code Mode sandbox (CLI: `--codemode-internal-full-access`; default: `false`) |\n| `BRIEFING_ENTRY_COUNT` | Journal entries in briefing (CLI: `--briefing-entries`; default: `3`) |\n| `BRIEFING_SUMMARY_COUNT` | Session summaries to list in briefing (CLI: `--briefing-summaries`; default: `1`) |\n| `BRIEFING_INCLUDE_TEAM` | Include team DB entries in briefing (`true`/`false`; default: `false`) |\n| `BRIEFING_ISSUE_COUNT` | Issues to list in briefing; `0` = count only (default: `0`) |\n| `BRIEFING_PR_COUNT` | PRs to list in briefing; `0` = count only (default: `0`) |\n| `BRIEFING_PR_STATUS` | Show PR status breakdown (open/merged/closed; default: `false`) |\n| `BRIEFING_MILESTONE_COUNT` | Milestones to list in briefing; `0` = hide entirely (CLI: `--briefing-milestones`; default: `3`) |\n| `BRIEFING_WORKFLOW_COUNT` | Workflow runs to list in briefing; `0` = status only (default: `0`) |\n| `BRIEFING_WORKFLOW_STATUS` | Show workflow status breakdown in briefing (default: `false`) |\n| `BRIEFING_COPILOT_REVIEWS` | Aggregate Copilot review state in briefing (default: `false`) |\n| `RULES_FILE_PATH` | Path to user rules file for agent awareness (CLI: `--rules-file`) |\n| `SKILLS_DIR_PATH` | Path to skills directory for agent awareness (CLI: `--skills-dir`) |\n| `MEMORY_JOURNAL_WORKFLOW_SUMMARY` | Free-text workflow summary for `memory://workflows` (CLI: `--workflow-summary`) |\n| `INSTRUCTION_LEVEL` | Briefing depth: `essential`, `standard`, `full` (CLI: `--instruction-level`; default: `standard`) |\n| `PROJECT_LINT_CMD` | Project lint command for GitHub Commander validation gates (default: `npm run lint`) |\n| `PROJECT_TYPECHECK_CMD` | Project typecheck command (default: `npm run typecheck`; empty = skip) |\n| `PROJECT_BUILD_CMD` | Project build command (default: `npm run build`; empty = skip) |\n| `PROJECT_TEST_CMD` | Project test command (default: `npm run test`) |\n| `PROJECT_E2E_CMD` | Project E2E test command (default: empty = skip) |\n| `PROJECT_PACKAGE_MANAGER` | Package manager override: `npm`, `yarn`, `pnpm`, `bun` (default: auto-detect from lockfile) |\n| `PROJECT_HAS_DOCKERFILE` | Enable Docker audit steps (default: auto-detect) |\n| `COMMANDER_HITL_FILE_THRESHOLD` | Human-in-the-loop checkpoint if changes touch > N files (default: `10`) |\n| `COMMANDER_SECURITY_TOOLS` | Override security tool auto-detection (comma-separated; default: auto-detect) |\n| `COMMANDER_BRANCH_PREFIX` | Branch naming prefix for PRs (default: `fix`) |\n| `AUDIT_LOG_PATH` | Path for the JSONL operational telemetry log of write/admin tool calls. Rotates at 10 MB (keeps 5 archives). Omit to disable telemetry logging. |\n| `AUDIT_REDACT` | Set to `false` to include tool arguments in telemetry log entries (default: `true`) |\n| `AUDIT_READS` | Log read-scoped tool calls in addition to write/admin (CLI: `--audit-reads`; default: `false`) |\n| `AUDIT_LOG_MAX_SIZE` | Maximum operational telemetry file size in bytes before rotation (CLI: `--audit-log-max-size`; default: `10485760`) |\n| `MCP_METRICS_ENABLED` | Set to `false` to disable in-memory tool call metrics accumulation (default: `true`) |\n| `FLAG_VOCABULARY` | Comma-separated flag types for Hush Protocol (CLI: `--flag-vocabulary`; default: `blocker,needs_review,help_requested,fyi`) |\n| `PRUNE_OLDER_THAN_DAYS` | Soft-delete entries older than N days with importance below threshold on startup; `0` = disabled (CLI: `--prune-older-than-days`; default: `0`) |\n| `PRUNE_IMPORTANCE_THRESHOLD` | Importance score threshold (0.0–1.0) — entries scoring below this are pruned (CLI: `--prune-importance-threshold`; default: `0.15`) |\n\n**Multi-Project Workflows**: For agents to seamlessly support multiple projects, provide **`PROJECT_REGISTRY`**.\n\n#### Dynamic Context Resolution & Auto-Detection\n\nWhen executing GitHub tools (issues, PRs, context, etc.), the server resolves repository context in this order:\n\n1. **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`.\n2. **Explicit Override**: If the agent provides both `owner` and `repo` explicitly, those values override auto-detection for API calls.\n3. **Missing Context**: Without `PROJECT_REGISTRY` or explicit parameters, the server blocks execution and returns `{requiresUserInput: true}` to prompt the agent.\n\n#### Automatic Project Routing (Kanban / Issues)\n\nWhen opening an issue or viewing/moving a Kanban card, the server needs a GitHub Project number. It determines this via:\n\n1. Exploring the raw `project_number` argument passed by the agent.\n2. Checking if the `repo` string precisely matches an entry in your **`PROJECT_REGISTRY`**, seamlessly mapping it to its pre-configured `project_number`.\n3. Falling back to the globally defined `DEFAULT_PROJECT_NUMBER` if set.\n\n### 🔐 OAuth 2.1 Authentication\n\nFor production deployments, enable OAuth 2.1 authentication on the HTTP transport:\n\n| Component | Status | Description |\n| --------------------------- | ------ | ------------------------------------------------ |\n| Protected Resource Metadata | ✅ | RFC 9728 `/.well-known/oauth-protected-resource` |\n| Auth Server Discovery | ✅ | RFC 8414 metadata discovery with caching |\n| Token Validation | ✅ | JWT validation with JWKS support |\n| Scope Enforcement | ✅ | Granular `read`, `write`, `admin` scopes |\n| HTTP Transport | ✅ | Streamable HTTP with OAuth middleware |\n\n**Supported Scopes:**\n\n| Scope | Tool Groups |\n| ------- | ------------------------------------------------- |\n| `read` | core, search, analytics, relationships, io |\n| `write` | github, team (+ all read groups) |\n| `admin` | admin, backup, codemode (+ all write/read groups) |\n\n**Quick Start:**\n\n```bash\nmemory-journal-mcp --transport http --port 3000 \\\n --oauth-enabled \\\n --oauth-issuer https://auth.example.com/realms/mcp \\\n --oauth-audience memory-journal-mcp \\\n --oauth-jwks-uri https://auth.example.com/realms/mcp/protocol/openid-connect/certs\n```\n\nOr via environment variables:\n\n```bash\nexport OAUTH_ENABLED=true\nexport OAUTH_ISSUER=https://auth.example.com/realms/mcp\nexport OAUTH_AUDIENCE=memory-journal-mcp\nexport OAUTH_CLOCK_TOLERANCE=5\nmemory-journal-mcp --transport http --port 3000\n```\n\n> **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.\n\n### 🔄 Session Management\n\n1. **Session start** → agent reads `memory://briefing` (or `memory://briefing/{repo}`) and shows project context\n2. **Session summary** → use `/session-summary` to capture progress and next-session context\n3. Next session's briefing includes the previous summary — context flows seamlessly\n\n## 🔧 Configuration\n\n### GitHub Integration (Optional)\n\n```bash\nexport GITHUB_TOKEN=\"your_token\" # For Projects/Issues/PRs\n```\n\n**Scopes:** `repo`, `project`, `read:org` (org-level project discovery only)\n\n### GitHub Management Capabilities\n\nMemory Journal provides a **hybrid approach** to GitHub management:\n\n| Capability Source | Purpose |\n| ------------------ | ------------------------------------------------------------------------------------------ |\n| **MCP Server** | Specialized features: Kanban visualization, Milestones, journal linking, project timelines |\n| **Agent (gh CLI)** | Full GitHub mutations: create/close issues, create/merge PRs, manage releases |\n\n**MCP Server Tools (Read + Kanban + Milestones + Issue Lifecycle):**\n\n- `get_github_issues` / `get_github_issue` - Query issues\n- `get_github_prs` / `get_github_pr` - Query pull requests\n- `get_github_context` - Full repository context\n- `get_kanban_board` / `add_kanban_item` / `move_kanban_item` / `delete_kanban_item` - **Kanban management**\n- `get_github_milestones` / `get_github_milestone` - **Milestone tracking with completion %**\n- `create_github_milestone` / `update_github_milestone` / `delete_github_milestone` - **Milestone CRUD**\n- `get_repo_insights` - **Repository traffic & analytics** (stars, clones, views, referrers, popular paths)\n- `create_github_issue_with_entry` / `close_github_issue_with_entry` - **Issue lifecycle with journal linking**\n\n> **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.\n\n**[Complete GitHub integration guide →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Git-Integration)**\n\n### GitHub Commander Workflows\n\nThe 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!\n\n## 🏗️ Architecture\n\n### Data Flow\n\n```mermaid\nflowchart TB\n AI[\"🤖 AI Agent
(Cursor, Windsurf, Claude)\"]\n\n subgraph MCP[\"Memory Journal MCP Server\"]\n Tools[\"🛠️ 73 Tools\"]\n Resources[\"📡 46 Resources\"]\n Prompts[\"💬 19 Prompts\"]\n end\n\n subgraph Storage[\"Persistence Layer\"]\n SQLite[(\"💾 SQLite
Entries, Tags, Relationships\")]\n Vector[(\"🔍 Vector Index
Semantic Embeddings\")]\n Backups[\"📦 Backups\"]\n end\n\n subgraph External[\"External Integrations\"]\n GitHub[\"🐙 GitHub API
Issues, PRs, Actions\"]\n Kanban[\"📋 Projects v2
Kanban Boards\"]\n end\n\n AI <-->|\"MCP Protocol\"| MCP\n Tools --> Storage\n Tools --> External\n Resources --> Storage\n Resources --> External\n```\n\n### Stack\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ MCP Server Layer (TypeScript) │\n│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │\n│ │ Tools (73) │ │ Resources (47) │ │ Prompts (19)│ │\n│ │ with Annotations│ │ with Annotations│ │ │ │\n│ └─────────────────┘ └─────────────────┘ └─────────────┘ │\n├─────────────────────────────────────────────────────────────┤\n│ Native SQLite Engine │\n│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │\n│ │ better-sqlite3 │ │ sqlite-vec │ │ transformers│ │\n│ │ (High-Perf I/O) │ │ (Vector Index) │ │ (Embeddings)│ │\n│ └─────────────────┘ └─────────────────┘ └─────────────┘ │\n├─────────────────────────────────────────────────────────────┤\n│ SQLite Database with Hybrid Search │\n│ ┌─────────────────────────────────────────────────────────┐│\n│ │ entries + tags + relationships + embeddings + backups ││\n│ └─────────────────────────────────────────────────────────┘│\n└─────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## 🔧 Technical Highlights\n\n### Performance & Portability\n\n- **TypeScript + Native SQLite** - High-performance `better-sqlite3` with synchronous I/O\n- **sqlite-vec** - Vector similarity search via SQLite extension\n- **@huggingface/transformers** - Local ML embedding models in JavaScript\n- **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.\n\n### Performance Benchmarks\n\nMemory Journal is designed for extremely low overhead during AI task execution. We include a `vitest bench` suite to maintain these baseline guarantees:\n\n- **Database Reads**: Operations execute in fractions of a millisecond. `calculateImportance` is ~13-14x faster than retrieving 50 recent entries.\n- **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.\n- **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.\n\nTo run the benchmarking suite locally:\n\n```bash\nnpm run bench\n```\n\n### Testing\n\nExtensively tested across two frameworks:\n\n| Suite | Command | Covers |\n| ------------------------- | ------------------ | ------------------------------------------------------------------------------- |\n| Vitest (unit/integration) | `npm test` | Database, tools, resources, handlers, security, GitHub, vector search, codemode |\n| Playwright (e2e) | `npm run test:e2e` | HTTP/SSE transport, auth, sessions, CORS, security headers, scheduler |\n\n```bash\nnpm test # Unit + integration tests\nnpm run test:e2e # End-to-end HTTP/SSE transport tests\n```\n\n### Security\n\n- **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\n- **Local-first** - All data stored locally, no external API calls (except optional GitHub)\n- **Input validation** - Zod schemas, content size limits, SQL injection prevention\n- **Path traversal protection** - Backup filenames validated\n- **MCP 2025-03-26 annotations** - Behavioral hints (`readOnlyHint`, `destructiveHint`, etc.)\n- **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\n- **Token scrubbing** - GitHub tokens and credentials automatically redacted from error logs\n\n### Data & Privacy\n\n- **Single SQLite file** - You own your data\n- **Portable** - Move your `.db` file anywhere\n- **Soft delete** - Entries can be recovered\n- **Auto-backup on restore** - Never lose data accidentally\n\n---\n\n## 📚 Documentation & Resources\n\n- **[GitHub Wiki](https://github.com/neverinfamous/memory-journal-mcp/wiki)** - Complete documentation\n- **[Copilot Setup Guide](https://github.com/neverinfamous/memory-journal-mcp/blob/main/docs/copilot-setup.md)** - Cross-agent memory bridge between IDE agents and GitHub Copilot\n- **[Deployment Guide](https://github.com/neverinfamous/memory-journal-mcp/blob/main/docs/deployment.md)** - CI/CD pipeline, environments, and version bump checklist\n- **[Docker Hub](https://hub.docker.com/r/writenotenow/memory-journal-mcp)** - Container images\n- **[npm Package](https://www.npmjs.com/package/memory-journal-mcp)** - Node.js distribution\n- **[Issues](https://github.com/neverinfamous/memory-journal-mcp/issues)** - Bug reports & feature requests\n\n---\n\n## 📄 License\n\nMIT License - See [LICENSE](https://github.com/neverinfamous/memory-journal-mcp/blob/main/LICENSE) file for details.\n\n## 🤝 Contributing\n\nBuilt by developers, for developers. PRs welcome! See [CONTRIBUTING.md](https://github.com/neverinfamous/memory-journal-mcp/blob/main/CONTRIBUTING.md) for guidelines.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"categoryDisplayName","Data & Analytics","upstream",{"_95":96,"_97":98,"_99":100,"_101":102,"_103":104},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_93":80,"_94":80},"ratingAvg","reviewCount","topics",[105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124],"license","MIT","language","TypeScript","registryName","ai.smithery/neverinfamous-memory-journal-mcp","homepage","https://adamic.tech/articles/memory-journal-mcp-server","ai-agent","ai-context","code-mode","context-engineering","context-management","developer-productivity","developer-tools","github-integration","knowledge-graph","mcp-server","mcp-tools","model-context-protocol","oauth2","project-journal","semantic-search","session-continuity","sqlite","team-collaboration","typescript","vector-search","ENV",{"_127":128,"_129":130,"_131":132},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]

memory journal mcp