memory-journal-mcp 6.3.0 → 7.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +91 -74
- package/dist/{chunk-VH4SRTLB.js → chunk-2BJHLTYP.js} +1237 -97
- package/dist/{chunk-K2SCUSN4.js → chunk-ARLH46WS.js} +34 -3
- package/dist/{chunk-QQ2ZY3CH.js → chunk-SBNQ7MXZ.js} +412 -365
- package/dist/cli.js +26 -4
- package/dist/github-integration-PDRLXKGM.js +1 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.js +3 -3
- package/dist/tools-FFFGXIKN.js +3 -0
- package/package.json +14 -13
- package/dist/github-integration-DTNYAKVJ.js +0 -1
- package/dist/tools-P4XXHO3Z.js +0 -3
package/README.md
CHANGED
|
@@ -10,9 +10,9 @@
|
|
|
10
10
|
[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.neverinfamous/memory-journal-mcp)
|
|
11
11
|
[](SECURITY.md)
|
|
12
12
|
[](https://github.com/neverinfamous/memory-journal-mcp)
|
|
13
|
-
|
|
14
14
|
|
|
15
|
-
|
|
16
16
|
[](https://github.com/neverinfamous/memory-journal-mcp/actions/workflows/gatekeeper.yml)
|
|
17
17
|
|
|
18
18
|
🎯 **AI Context + Project Intelligence:** Bridge disconnected AI sessions with persistent project memory and **automatic session handoff** — with full GitHub workflow integration.
|
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
|
|
29
29
|
### What Sets Us Apart
|
|
30
30
|
|
|
31
|
-
**61 MCP Tools** · **17 Workflow Prompts** · **
|
|
31
|
+
**61 MCP Tools** · **17 Workflow Prompts** · **38 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)
|
|
32
32
|
|
|
33
33
|
| Feature | Description |
|
|
34
34
|
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -36,7 +36,7 @@
|
|
|
36
36
|
| **GitHub Integration** | 16 tools for Issues, PRs, Actions, Kanban, Milestones (%), Copilot Reviews, and 14-day Insights |
|
|
37
37
|
| **Dynamic Project Routing** | Seamlessly switch contexts and access CI/Issue tracking across multiple repositories using a single server instance via `PROJECT_REGISTRY` |
|
|
38
38
|
| **Knowledge Graphs** | 8 relationship types linking specs → implementations → tests → PRs with Mermaid visualization |
|
|
39
|
-
| **
|
|
39
|
+
| **Hybrid Search** | Reciprocal Rank Fusion combining FTS5 keywords, semantic vector similarity, auto-heuristics, and date-range filters |
|
|
40
40
|
| **Code Mode** | Execute multi-step operations in a secure sandbox — up to 90% token savings via `mj.*` API |
|
|
41
41
|
| **Configurable Briefing** | 12 env vars / CLI flags control `memory://briefing` content — entries, team, GitHub detail, skills awareness |
|
|
42
42
|
| **Reports & Analytics** | Standups, retrospectives, PR summaries, digests, period analyses, and milestone tracking |
|
|
@@ -85,10 +85,11 @@ flowchart TB
|
|
|
85
85
|
Link["Link Entries"]
|
|
86
86
|
end
|
|
87
87
|
|
|
88
|
-
subgraph Search["🔍
|
|
89
|
-
FTS["
|
|
88
|
+
subgraph Search["🔍 Hybrid Search"]
|
|
89
|
+
FTS["Keyword (FTS5)"]
|
|
90
90
|
Semantic["Semantic (Vector)"]
|
|
91
91
|
DateRange["Date Range"]
|
|
92
|
+
RRF["Reciprocal Rank Fusion"]
|
|
92
93
|
end
|
|
93
94
|
|
|
94
95
|
subgraph GitHub["🐙 GitHub Integration"]
|
|
@@ -114,23 +115,28 @@ flowchart TB
|
|
|
114
115
|
|
|
115
116
|
---
|
|
116
117
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
**
|
|
129
|
-
|
|
130
|
-
-
|
|
131
|
-
-
|
|
132
|
-
|
|
133
|
-
|
|
118
|
+
Suggested Rule (Add to AGENTS.md, GEMINI.md, etc):
|
|
119
|
+
|
|
120
|
+
🛑 MANDATORY SESSION START ROUTINE
|
|
121
|
+
|
|
122
|
+
Execute BEFORE fulfilling any user request in a new session:
|
|
123
|
+
|
|
124
|
+
1. **TARGET**: Infer `repo_name` from the active workspace context or user prompt. If the task is not associated with a specific project, fallback to using the generic resource without a repo name (which defaults to the first registered workspace).
|
|
125
|
+
2. **FETCH**: Use the MCP `read_resource` tool (Server: `memory-journal-mcp`) to read `memory://briefing/{repo_name}` (or `memory://briefing` if falling back).
|
|
126
|
+
- **RESTRICTION**: Do NOT use `execute_code` for this step.
|
|
127
|
+
3. **RENDER TABLE**: Extract `userMessage` and output it EXCLUSIVELY as a vertical Markdown Table (2 columns: Field and Value).
|
|
128
|
+
- **RESTRICTION**: NO bulleted lists. NO truncation of arrays or lists.
|
|
129
|
+
- **REQUIRED MAP**: Output all data comprehensively. Map these fields to the "Field" column:
|
|
130
|
+
- Application / Project
|
|
131
|
+
- Journal Entries
|
|
132
|
+
- Team DB Entries
|
|
133
|
+
- Latest Entry (Journal)
|
|
134
|
+
- Latest Entry (Team)
|
|
135
|
+
- GitHub (Include Repo, Branch, CI Status, Issues, PRs, Insights on separate lines in the Value column)
|
|
136
|
+
- Milestone Progress
|
|
137
|
+
- Template Resources (Output count only, not URLs)
|
|
138
|
+
- Registered Workspaces (Output FULL list of project names)
|
|
139
|
+
- Available Extensions (Rules, Skills, Workflows)
|
|
134
140
|
|
|
135
141
|
---
|
|
136
142
|
|
|
@@ -201,7 +207,7 @@ Control which tools are exposed via `MEMORY_JOURNAL_MCP_TOOL_FILTER` (or CLI: `-
|
|
|
201
207
|
|
|
202
208
|
**[Complete prompts guide →](https://github.com/neverinfamous/memory-journal-mcp/wiki/Prompts)**
|
|
203
209
|
|
|
204
|
-
### 📡 **
|
|
210
|
+
### 📡 **38 Resources** (25 Static + 13 Template)
|
|
205
211
|
|
|
206
212
|
**Static Resources** (appear in resource lists):
|
|
207
213
|
|
|
@@ -225,6 +231,11 @@ Control which tools are exposed via `MEMORY_JOURNAL_MCP_TOOL_FILTER` (or CLI: `-
|
|
|
225
231
|
- `memory://team/statistics` - Team entry counts, types, and author breakdown
|
|
226
232
|
- `memory://help` - Tool group index with descriptions and tool counts
|
|
227
233
|
- `memory://help/gotchas` - Field notes, edge cases, and critical usage patterns
|
|
234
|
+
- `memory://metrics/summary` - Aggregate tool call metrics since server start (calls, errors, token estimates, duration) — HIGH priority
|
|
235
|
+
- `memory://metrics/tokens` - Per-tool token usage breakdown sorted by output token cost — MEDIUM priority
|
|
236
|
+
- `memory://metrics/system` - Process-level metrics: memory (MB), uptime (s), Node.js version, platform — MEDIUM priority
|
|
237
|
+
- `memory://metrics/users` - Per-user call counts (populated when OAuth user identifiers are present) — LOW priority
|
|
238
|
+
- `memory://audit` - Last 50 write/admin tool call entries from the JSONL audit log (requires `AUDIT_LOG_PATH`)
|
|
228
239
|
|
|
229
240
|
**Template Resources** (require parameters, fetch directly by URI):
|
|
230
241
|
|
|
@@ -460,52 +471,58 @@ Each job is error-isolated — a failure in one job won't affect the others. Sch
|
|
|
460
471
|
|
|
461
472
|
### GitHub Integration Configuration
|
|
462
473
|
|
|
463
|
-
The GitHub tools (`get_github_issues`, `get_github_prs`, etc.) auto-detect the repository from your git context when `
|
|
464
|
-
|
|
465
|
-
| Environment Variable
|
|
466
|
-
|
|
|
467
|
-
| `DB_PATH`
|
|
468
|
-
| `TEAM_DB_PATH`
|
|
469
|
-
| `TEAM_AUTHOR`
|
|
470
|
-
| `GITHUB_TOKEN`
|
|
471
|
-
|
|
472
|
-
| `DEFAULT_PROJECT_NUMBER`
|
|
473
|
-
| `
|
|
474
|
-
| `
|
|
475
|
-
| `
|
|
476
|
-
| `
|
|
477
|
-
| `
|
|
478
|
-
| `
|
|
479
|
-
| `
|
|
480
|
-
| `
|
|
481
|
-
| `
|
|
482
|
-
| `
|
|
483
|
-
| `
|
|
484
|
-
| `
|
|
485
|
-
| `
|
|
486
|
-
| `
|
|
487
|
-
| `
|
|
488
|
-
| `
|
|
489
|
-
| `
|
|
490
|
-
| `
|
|
491
|
-
| `
|
|
492
|
-
| `
|
|
493
|
-
| `
|
|
494
|
-
| `
|
|
495
|
-
| `
|
|
496
|
-
| `
|
|
497
|
-
| `
|
|
498
|
-
| `
|
|
499
|
-
| `
|
|
500
|
-
| `
|
|
501
|
-
| `
|
|
502
|
-
| `
|
|
503
|
-
| `
|
|
504
|
-
| `
|
|
505
|
-
| `
|
|
506
|
-
| `
|
|
507
|
-
|
|
508
|
-
|
|
474
|
+
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.
|
|
475
|
+
|
|
476
|
+
| Environment Variable | Description |
|
|
477
|
+
| -------------------- | ----------------------------------------------------------------------- |
|
|
478
|
+
| `DB_PATH` | Database file location (CLI: `--db`; default: `./memory_journal.db`) |
|
|
479
|
+
| `TEAM_DB_PATH` | Team database file location (CLI: `--team-db`) |
|
|
480
|
+
| `TEAM_AUTHOR` | Override author name for team entries (default: `git config user.name`) |
|
|
481
|
+
| `GITHUB_TOKEN` | GitHub personal access token for API access |
|
|
482
|
+
|
|
483
|
+
| `DEFAULT_PROJECT_NUMBER` | Default GitHub Project number for auto-assignment when creating issues |
|
|
484
|
+
| `GITHUB_REPO_PATH` | Path to a git repository for auto-detecting owner/repo |
|
|
485
|
+
| `PROJECT_REGISTRY` | JSON map of repos to `{ path, project_number }` for multi-project auto-detection and routing |
|
|
486
|
+
| `AUTO_REBUILD_INDEX` | Set to `true` to rebuild vector index on server startup |
|
|
487
|
+
| `MCP_HOST` | Server bind host (`0.0.0.0` for containers, default: `localhost`) |
|
|
488
|
+
| `MCP_AUTH_TOKEN` | Bearer token for HTTP transport authentication (CLI: `--auth-token`) |
|
|
489
|
+
| `MCP_CORS_ORIGIN` | Allowed CORS origins for HTTP transport, comma-separated (default: `*`) |
|
|
490
|
+
| `MCP_RATE_LIMIT_MAX` | Max requests per minute per client IP, HTTP only (default: `100`) |
|
|
491
|
+
| `LOG_LEVEL` | Log verbosity: `error`, `warn`, `info`, `debug` (default: `info`; CLI: `--log-level`) |
|
|
492
|
+
| `MCP_ENABLE_HSTS` | Enable HSTS security header on HTTP responses (CLI: `--enable-hsts`; default: `false`) |
|
|
493
|
+
| `OAUTH_ENABLED` | Set to `true` to enable OAuth 2.1 authentication (HTTP only) |
|
|
494
|
+
| `OAUTH_ISSUER` | OAuth issuer URL (e.g., `https://auth.example.com/realms/mcp`) |
|
|
495
|
+
| `OAUTH_AUDIENCE` | Expected JWT audience claim |
|
|
496
|
+
| `OAUTH_JWKS_URI` | JWKS endpoint for token signature verification |
|
|
497
|
+
| `BRIEFING_ENTRY_COUNT` | Journal entries in briefing (CLI: `--briefing-entries`; default: `3`) |
|
|
498
|
+
| `BRIEFING_INCLUDE_TEAM` | Include team DB entries in briefing (`true`/`false`; default: `false`) |
|
|
499
|
+
| `BRIEFING_ISSUE_COUNT` | Issues to list in briefing; `0` = count only (default: `0`) |
|
|
500
|
+
| `BRIEFING_PR_COUNT` | PRs to list in briefing; `0` = count only (default: `0`) |
|
|
501
|
+
| `BRIEFING_PR_STATUS` | Show PR status breakdown (open/merged/closed; default: `false`) |
|
|
502
|
+
| `BRIEFING_WORKFLOW_COUNT` | Workflow runs to list in briefing; `0` = status only (default: `0`) |
|
|
503
|
+
| `BRIEFING_WORKFLOW_STATUS` | Show workflow status breakdown in briefing (default: `false`) |
|
|
504
|
+
| `BRIEFING_COPILOT_REVIEWS` | Aggregate Copilot review state in briefing (default: `false`) |
|
|
505
|
+
| `RULES_FILE_PATH` | Path to user rules file for agent awareness (CLI: `--rules-file`) |
|
|
506
|
+
| `SKILLS_DIR_PATH` | Path to skills directory for agent awareness (CLI: `--skills-dir`) |
|
|
507
|
+
| `MEMORY_JOURNAL_WORKFLOW_SUMMARY` | Free-text workflow summary for `memory://workflows` (CLI: `--workflow-summary`) |
|
|
508
|
+
| `INSTRUCTION_LEVEL` | Briefing depth: `essential`, `standard`, `full` (CLI: `--instruction-level`; default: `standard`) |
|
|
509
|
+
| `PROJECT_LINT_CMD` | Project lint command for GitHub Commander validation gates (default: `npm run lint`) |
|
|
510
|
+
| `PROJECT_TYPECHECK_CMD` | Project typecheck command (default: `npm run typecheck`; empty = skip) |
|
|
511
|
+
| `PROJECT_BUILD_CMD` | Project build command (default: `npm run build`; empty = skip) |
|
|
512
|
+
| `PROJECT_TEST_CMD` | Project test command (default: `npm run test`) |
|
|
513
|
+
| `PROJECT_E2E_CMD` | Project E2E test command (default: empty = skip) |
|
|
514
|
+
| `PROJECT_PACKAGE_MANAGER` | Package manager override: `npm`, `yarn`, `pnpm`, `bun` (default: auto-detect from lockfile) |
|
|
515
|
+
| `PROJECT_HAS_DOCKERFILE` | Enable Docker audit steps (default: auto-detect) |
|
|
516
|
+
| `COMMANDER_HITL_FILE_THRESHOLD` | Human-in-the-loop checkpoint if changes touch > N files (default: `10`) |
|
|
517
|
+
| `COMMANDER_SECURITY_TOOLS` | Override security tool auto-detection (comma-separated; default: auto-detect) |
|
|
518
|
+
| `COMMANDER_BRANCH_PREFIX` | Branch naming prefix for PRs (default: `fix`) |
|
|
519
|
+
| `AUDIT_LOG_PATH` | Path for the JSONL audit log of write/admin tool calls. Rotates at 10 MB (keeps 5 archives). Omit to disable audit logging. |
|
|
520
|
+
| `AUDIT_REDACT` | Set to `true` to omit tool arguments from audit log entries for privacy (default: `false`) |
|
|
521
|
+
| `AUDIT_READS` | Log read-scoped tool calls in addition to write/admin (CLI: `--audit-reads`; default: `false`) |
|
|
522
|
+
| `AUDIT_LOG_MAX_SIZE` | Maximum audit log file size in bytes before rotation (CLI: `--audit-log-max-size`; default: `10485760`) |
|
|
523
|
+
| `MCP_METRICS_ENABLED` | Set to `false` to disable in-memory tool call metrics accumulation (default: `true`) |
|
|
524
|
+
|
|
525
|
+
**Multi-Project Workflows**: For agents to seamlessly support multiple projects, provide **`PROJECT_REGISTRY`**.
|
|
509
526
|
|
|
510
527
|
#### Dynamic Context Resolution & Auto-Detection
|
|
511
528
|
|
|
@@ -642,7 +659,7 @@ flowchart TB
|
|
|
642
659
|
┌─────────────────────────────────────────────────────────────┐
|
|
643
660
|
│ MCP Server Layer (TypeScript) │
|
|
644
661
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │
|
|
645
|
-
│ │ Tools (61) │ │ Resources (
|
|
662
|
+
│ │ Tools (61) │ │ Resources (38) │ │ Prompts (17)│ │
|
|
646
663
|
│ │ with Annotations│ │ with Annotations│ │ │ │
|
|
647
664
|
│ └─────────────────┘ └─────────────────┘ └─────────────┘ │
|
|
648
665
|
├─────────────────────────────────────────────────────────────┤
|
|
@@ -674,9 +691,9 @@ flowchart TB
|
|
|
674
691
|
|
|
675
692
|
Memory Journal is designed for extremely low overhead during AI task execution. We include a `vitest bench` suite to maintain these baseline guarantees:
|
|
676
693
|
|
|
677
|
-
- **Database Reads**: Operations execute in fractions of a millisecond. `calculateImportance` is ~
|
|
678
|
-
- **Vector Search Engine**: Both search (~220 ops/sec) and indexing (~1600+ ops/sec) are high-throughput via `sqlite-vec` with SQL-native KNN queries.
|
|
679
|
-
- **Core MCP Routines**: `getTools` uses cached O(1) dispatch (~
|
|
694
|
+
- **Database Reads**: Operations execute in fractions of a millisecond. `calculateImportance` is ~13-14x faster than retrieving 50 recent entries.
|
|
695
|
+
- **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.
|
|
696
|
+
- **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.
|
|
680
697
|
|
|
681
698
|
To run the benchmarking suite locally:
|
|
682
699
|
|