memory-journal-mcp 5.1.0 → 6.0.0

package/.dockerignore

@@ -43,6 +43,7 @@ eslint.config.js
 vitest.config.ts
 tests/
 coverage/
+.test-output/
 dist/
 
 # -----------------------------------------------------------------------------
@@ -87,6 +88,7 @@ data/
 *.db-wal
 *.sqlite
 *.sqlite3
+# Legacy vector index files (before sqlite-vec migration)
 .vectra_index/
 *.vectra/
 
@@ -97,7 +99,7 @@ temp/
 tmp/
 *.tmp
 *.temp
-backups/
+
 
 # -----------------------------------------------------------------------------
 # Logs
@@ -129,3 +131,9 @@ env/
 ENV/
 *.egg-info/
 *.egg
+
+# -----------------------------------------------------------------------------
+# Assets
+# -----------------------------------------------------------------------------
+social-preview.png
+

package/.gitattributes

@@ -1,25 +1,14 @@
-# Auto-detect text files and normalize line endings
-* text=auto
+# Enforce LF line endings for all text files
+* text=auto eol=lf
 
-# Force LF for source files
-*.ts text eol=lf
-*.js text eol=lf
-*.json text eol=lf
-*.md text eol=lf
-*.yml text eol=lf
-*.yaml text eol=lf
-*.css text eol=lf
-*.html text eol=lf
+# Windows-specific scripts that require CRLF
+*.bat text eol=crlf
+*.cmd text eol=crlf
 
 # Docker
 Dockerfile text eol=lf
 .dockerignore text eol=lf
 
-# Config
-.prettierrc text eol=lf
-.prettierignore text eol=lf
-.eslintrc* text eol=lf
-.gitignore text eol=lf
 
 # Explicitly binary
 *.db binary
@@ -27,3 +16,5 @@ Dockerfile text eol=lf
 *.png binary
 *.jpg binary
 *.ico binary
+
+.github/workflows/*.lock.yml linguist-generated=true merge=ours

package/.github/aw/actions-lock.json

@@ -0,0 +1,14 @@
+{
+    "entries": {
+        "actions/github-script@v8": {
+            "repo": "actions/github-script",
+            "version": "v8",
+            "sha": "ed597411d8f924073f98dfc5c65a23a2325f34cd"
+        },
+        "github/gh-aw/actions/setup@v0.57.2": {
+            "repo": "github/gh-aw/actions/setup",
+            "version": "v0.57.2",
+            "sha": "32b3a711a9ee97d38e3989c90af0385aff0066a7"
+        }
+    }
+}

package/.github/copilot-instructions.md

@@ -0,0 +1,122 @@
+# Memory Journal MCP — Copilot Code Review Context
+
+## Project Overview
+
+Memory Journal MCP is a TypeScript MCP (Model Context Protocol) server providing persistent memory for AI agents. It has **44 tools** across **10 groups** (core, search, analytics, relationships, export, admin, github, backup, team, codemode), **22 resources**, and **15 prompts**.
+
+**Stack**: TypeScript, Vitest, Zod schemas, better-sqlite3 (SQLite), sqlite-vec (vector search), @huggingface/transformers (embeddings), @octokit/rest (GitHub API).
+
+## Session Context
+
+Before starting work on this project, read `memory://briefing` from the `memory-journal-mcp` server for real-time context:
+
+- **Recent journal entries** — what was just worked on by the development agent
+- **GitHub status** — open issues, PRs, CI status, milestones
+- **Workflow runs** — recent CI/CD results
+- **Copilot review summaries** — your own recent review findings
+
+For detailed session handoff context, search for entries tagged `session-summary` — these contain end-of-session notes from the development agent.
+
+If you find issues during code review, use `create_entry` with tag `copilot-finding` to record them for the development agent to see in their next session briefing.
+
+## Coding Standards
+
+### Naming
+
+- **Files and folders**: Always kebab-case (`database-adapter.ts`, `tool-filter.ts`, `copilot-tools.ts`)
+- **Never** PascalCase or camelCase for filenames
+
+### Modularity
+
+- **File size limit**: Source files stay under ~500 lines
+- **Split pattern**: `foo.ts` → `foo/` directory with sub-modules + `foo/index.ts` barrel re-export
+- **Logical grouping**: Split by functional cohesion, not arbitrary line counts
+
+### Type Safety
+
+- **Strict TypeScript** — `tsconfig.json` enforces strict mode
+- **Never use `eslint-disable`** to evade standards
+- **Zod schemas** for all tool input validation
+- **Output schemas** — All tools have Zod output schemas; error responses must pass validation
+- **Dual-schema pattern** — Relaxed schemas for SDK registration (to handle MCP client coercion), strict schemas inside handlers
+
+### Error Handling
+
+All tool handlers return structured error responses — never raw exceptions:
+
+```typescript
+{
+  success: false,
+  error: string,        // Human-readable message
+  code: string,         // Module-prefixed code (e.g., "ENTRY_NOT_FOUND")
+  category: string,     // ErrorCategory enum (validation, connection, query, etc.)
+  suggestion: string,   // Actionable fix for the agent
+  recoverable: boolean  // true = user can fix, false = server error
+}
+```
+
+- Use `formatHandlerErrorResponse()` from `src/utils/error-helpers.ts` for enriched errors
+- Use `MemoryJournalMcpError` subclasses (`ValidationError`, `ResourceNotFoundError`, etc.) for typed errors
+- Existing `formatHandlerError()` preserved for backward compatibility
+
+### Database
+
+- Schema migrations in `src/database/schema.ts` via `migrateSchema()`
+- Backward compatible — never break existing data
+- Consider index implications for new queries
+
+## Architecture
+
+```
+src/
+├── cli.ts                      # CLI entry point (Commander)
+├── index.ts                    # Library entry point
+├── auth/                       # OAuth 2.1 authentication
+├── codemode/                   # Sandboxed JS execution engine
+├── constants/
+│   ├── server-instructions.md  # Source for server instructions
+│   └── server-instructions.ts  # Auto-generated (npm run generate:instructions)
+├── database/
+│   ├── adapter-factory.ts      # Database adapter factory
+│   ├── core/                   # Core database types and interfaces
+│   └── sqlite-adapter/         # SQLite operations via better-sqlite3
+├── filtering/
+│   └── tool-filter.ts          # Tool filtering (groups, meta-groups)
+├── github/
+│   └── github-integration/     # GitHub API (@octokit/rest + GraphQL)
+├── handlers/
+│   ├── tools/                  # 44 tool handlers (10 groups)
+│   ├── resources/              # 22 resource handlers
+│   └── prompts/                # 15 prompt handlers
+├── server/
+│   ├── mcp-server.ts           # MCP server setup
+│   ├── registration.ts         # Tool/resource/prompt registration
+│   └── scheduler.ts            # Recurring task scheduler
+├── transports/
+│   └── http/                   # HTTP/SSE transport (modularized)
+├── types/                      # Type definitions + barrel
+├── utils/                      # Logger, error helpers, progress
+└── vector/                     # Semantic search (sqlite-vec + transformers)
+```
+
+## Key Reference Files
+
+| File                                   | Purpose                                               |
+| -------------------------------------- | ----------------------------------------------------- |
+| `src/constants/server-instructions.md` | Full tool parameter reference and behavioral guidance |
+| `docs/code-map.md`                     | File → tool/handler mapping                           |
+| `docs/tool-reference.md`               | Categorized 44-tool inventory                         |
+| `CONTRIBUTING.md`                      | Development setup and PR guidelines                   |
+
+## Review Checklist
+
+When reviewing PRs, check for:
+
+- [ ] Hardcoded tool/group counts — should be dynamic or use `getAllToolNames().length`
+- [ ] Missing barrel exports in `src/types/index.ts` when new types are added
+- [ ] `eslint-disable` usage — always forbidden
+- [ ] Raw exceptions from tool handlers — must use `formatHandlerErrorResponse()`
+- [ ] Files approaching 500 lines — flag for splitting
+- [ ] New tools missing from `src/filtering/ToolFilter.ts` TOOL_GROUPS
+- [ ] Missing Zod output schemas on new tools
+- [ ] Kebab-case violations in new filenames

package/.github/dependabot.yml

@@ -1,6 +1,5 @@
 # Dependabot configuration for Memory Journal MCP Server
-# v3.0.0+ is a TypeScript/Node.js project (npm dependencies)
-# The Python codebase is deprecated and archived in archive/python-v2
+# TypeScript/Node.js project — npm, github-actions, and docker ecosystems only
 
 version: 2
 updates:
@@ -28,14 +27,13 @@ updates:
           - 'patch'
       ml-packages:
         patterns:
-          - '@xenova/*'
-          - 'vectra*'
+          - '@huggingface/*'
+          - 'sqlite-vec*'
         update-types:
           - 'minor'
           - 'patch'
       database:
         patterns:
-          - 'sql.js*'
           - 'better-sqlite3*'
         update-types:
           - 'minor'

package/.github/workflows/README.md

@@ -0,0 +1,133 @@
+# CI/CD Workflows
+
+This directory contains all GitHub Actions workflows for the **memory-journal-mcp** project. The pipeline is organized into three layers: continuous integration, security scanning, and automated release/publishing.
+
+## Workflow Map
+
+```mermaid
+flowchart LR
+    subgraph Triggers["Triggers"]
+        Push["push to main"]
+        PR["pull_request"]
+        Tag["release published"]
+        Sched["schedule (cron)"]
+        Manual["workflow_dispatch"]
+    end
+
+    subgraph CI["CI"]
+        LT["lint-and-test"]
+    end
+
+    subgraph Security["Security"]
+        CQL["codeql"]
+        SS["secrets-scanning"]
+        SU["security-update"]
+    end
+
+    subgraph Release["Release"]
+        AR["auto-release"]
+        NPM["publish-npm"]
+        DP["docker-publish"]
+    end
+
+    subgraph Agentic["Agentic Workflows (Copilot)"]
+        DM["dependency-maintenance"]
+        CHM["ci-health-monitor"]
+        DDD["docs-drift-detector"]
+        AM["agentics-maintenance"]
+    end
+
+    Push --> LT
+    PR --> LT
+    Push --> CQL
+    Push --> SS
+    Push --> SU
+    LT -->|workflow_run success| DP
+    Push -->|commit contains '[deps]'| AR
+    AR -->|creates release| NPM
+    Tag --> NPM
+    Sched --> CQL
+    Sched --> SU
+    Sched --> DM
+    Sched --> CHM
+    Sched --> AM
+    PR --> DDD
+    Manual --> SU
+    Manual --> DM
+    Manual --> CHM
+    Manual --> AM
+```
+
+---
+
+## Workflows
+
+### CI
+
+| File                                   | Trigger             | Purpose                                                                 |
+| -------------------------------------- | ------------------- | ----------------------------------------------------------------------- |
+| [lint-and-test.yml](lint-and-test.yml) | push / PR to `main` | Lint, typecheck, build, unit tests (Node 24.x + 25.x matrix), npm audit |
+
+### Security
+
+| File                                         | Trigger                                                             | Purpose                                                                                            |
+| -------------------------------------------- | ------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| [codeql.yml](codeql.yml)                     | push / PR / weekly (Mon 02:23 UTC)                                  | CodeQL static analysis for `javascript-typescript` and `actions`                                   |
+| [secrets-scanning.yml](secrets-scanning.yml) | push / PR                                                           | TruffleHog (verified secrets) + Gitleaks scanning                                                  |
+| [security-update.yml](security-update.yml)   | push (Dockerfile/package changes) / weekly (Sun 02:00 UTC) / manual | Docker image Trivy scan (CRITICAL/HIGH/MEDIUM), SARIF upload, auto-creates GitHub issue on failure |
+
+### Release & Publishing
+
+| File                                     | Trigger                                        | Purpose                                                                                                   |
+| ---------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| [auto-release.yml](auto-release.yml)     | push to `main` with `[deps]` in commit message | Creates git tag + GitHub release for dependency-maintenance patch bumps                                   |
+| [publish-npm.yml](publish-npm.yml)       | release published / manual                     | Publishes to npm with version verification                                                                |
+| [docker-publish.yml](docker-publish.yml) | `lint-and-test` workflow_run success on `main` | Multi-arch Docker build (amd64 + arm64), Docker Scout scan, manifest merge, Docker Hub description update |
+
+### Agentic Workflows (GitHub Copilot)
+
+These are AI-powered workflows using [GitHub Copilot Coding Agent](https://docs.github.com/en/copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks/about-assigning-tasks-to-copilot). Each `.md` file contains the agent prompt; the corresponding `.lock.yml` is the auto-generated compiled workflow (**do not edit `.lock.yml` files**).
+
+| Prompt                                                 | Lock File                                                          | Schedule             | Purpose                                                                                            |
+| ------------------------------------------------------ | ------------------------------------------------------------------ | -------------------- | -------------------------------------------------------------------------------------------------- |
+| [dependency-maintenance.md](dependency-maintenance.md) | [dependency-maintenance.lock.yml](dependency-maintenance.lock.yml) | Mon 14:00 UTC        | Batch-updates npm, Dockerfile patches, Alpine packages; validates, bumps patch version, creates PR |
+| [ci-health-monitor.md](ci-health-monitor.md)           | [ci-health-monitor.lock.yml](ci-health-monitor.lock.yml)           | Wed 14:00 UTC        | Audits workflows for deprecated actions, Node.js runtime issues, stale Dependabot config           |
+| [docs-drift-detector.md](docs-drift-detector.md)       | [docs-drift-detector.lock.yml](docs-drift-detector.lock.yml)       | PR (on code changes) | Audits README, DOCKER_README, CONTRIBUTING for drift against code changes                          |
+| [agentics-maintenance.yml](agentics-maintenance.yml)   | —                                                                  | Daily 00:37 UTC      | Auto-closes expired discussions, issues, and PRs created by agentic workflows                      |
+
+---
+
+## Release Pipeline
+
+The full release flow for dependency updates:
+
+```
+dependency-maintenance (Copilot)
+  → creates PR with [deps] prefix
+    → lint-and-test runs on PR
+      → Copilot reviews + human merge
+        → auto-release (creates tag + GitHub release)
+          → publish-npm (triggered by release event)
+          → docker-publish (triggered by lint-and-test on main)
+```
+
+For manual releases (feature/breaking changes), the maintainer runs `/bump-deploy` locally which pushes a tag and creates a GitHub release, triggering npm and Docker publish.
+
+---
+
+## Secrets Required
+
+| Secret            | Used By                                             | Purpose                        |
+| ----------------- | --------------------------------------------------- | ------------------------------ |
+| `GITHUB_TOKEN`    | auto-release, security-update, agentics-maintenance | Git operations, issue creation |
+| `NPM_TOKEN`       | publish-npm                                         | npm registry authentication    |
+| `DOCKER_USERNAME` | docker-publish                                      | Docker Hub login               |
+| `DOCKER_PASSWORD` | docker-publish                                      | Docker Hub login               |
+
+---
+
+## Editing Guidelines
+
+- **YAML workflows** — edit directly, commit to `main` or via PR
+- **Agentic `.md` prompts** — edit the `.md` file, then run `gh aw compile` to regenerate the `.lock.yml`
+- **`.lock.yml` files** — **never edit manually**; always regenerate via `gh aw compile`

package/.github/workflows/agentics-maintenance.yml

@@ -0,0 +1,141 @@
+#
+#    ___                   _   _
+#   / _ \                 | | (_)
+#  | |_| | __ _  ___ _ __ | |_ _  ___
+#  |  _  |/ _` |/ _ \ '_ \| __| |/ __|
+#  | | | | (_| |  __/ | | | |_| | (__
+#  \_| |_/\__, |\___|_| |_|\__|_|\___|
+#          __/ |
+#  _    _ |___/
+# | |  | |                / _| |
+# | |  | | ___ _ __ _  __| |_| | _____      ____
+# | |/\| |/ _ \ '__| |/ /|  _| |/ _ \ \ /\ / / ___|
+# \  /\  / (_) | | | | ( | | | | (_) \ V  V /\__ \
+#  \/  \/ \___/|_| |_|\_\|_| |_|\___/ \_/\_/ |___/
+#
+# This file was automatically generated by pkg/workflow/maintenance_workflow.go (v0.57.2). DO NOT EDIT.
+#
+# To regenerate this workflow, run:
+#   gh aw compile
+# Not all edits will cause changes to this file.
+#
+# For more information: https://github.github.com/gh-aw/introduction/overview/
+#
+# Alternative regeneration methods:
+# make recompile
+#
+# Or use the gh-aw CLI directly:
+# ./gh-aw compile --validate --verbose
+#
+# The workflow is generated when any workflow uses the 'expires' field
+# in create-discussions, create-issues, or create-pull-request safe-outputs configuration.
+# Schedule frequency is automatically determined by the shortest expiration time.
+#
+name: Agentic Maintenance
+
+on:
+  schedule:
+    - cron: '37 0 * * *' # Daily (based on minimum expires: 14 days)
+  workflow_dispatch:
+    inputs:
+      operation:
+        description: 'Optional maintenance operation to run'
+        required: false
+        type: choice
+        default: ''
+        options:
+          - ''
+          - 'disable'
+          - 'enable'
+          - 'update'
+          - 'upgrade'
+
+permissions: {}
+
+jobs:
+  close-expired-entities:
+    if: ${{ !github.event.repository.fork && (github.event_name != 'workflow_dispatch' || github.event.inputs.operation == '') }}
+    runs-on: ubuntu-slim
+    permissions:
+      discussions: write
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Setup Scripts
+        uses: github/gh-aw/actions/setup@32b3a711a9ee97d38e3989c90af0385aff0066a7 # v0.57.2
+        with:
+          destination: /opt/gh-aw/actions
+
+      - name: Close expired discussions
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          script: |
+            const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io);
+            const { main } = require('/opt/gh-aw/actions/close_expired_discussions.cjs');
+            await main();
+
+      - name: Close expired issues
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          script: |
+            const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io);
+            const { main } = require('/opt/gh-aw/actions/close_expired_issues.cjs');
+            await main();
+
+      - name: Close expired pull requests
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          script: |
+            const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io);
+            const { main } = require('/opt/gh-aw/actions/close_expired_pull_requests.cjs');
+            await main();
+
+  run_operation:
+    if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.operation != '' && !github.event.repository.fork }}
+    runs-on: ubuntu-slim
+    permissions:
+      actions: write
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Setup Scripts
+        uses: github/gh-aw/actions/setup@32b3a711a9ee97d38e3989c90af0385aff0066a7 # v0.57.2
+        with:
+          destination: /opt/gh-aw/actions
+
+      - name: Check admin/maintainer permissions
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io);
+            const { main } = require('/opt/gh-aw/actions/check_team_member.cjs');
+            await main();
+
+      - name: Install gh-aw
+        uses: github/gh-aw/actions/setup-cli@v0.57.2
+        with:
+          version: v0.57.2
+
+      - name: Run operation
+        uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_AW_OPERATION: ${{ github.event.inputs.operation }}
+          GH_AW_CMD_PREFIX: gh aw
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const { setupGlobals } = require('/opt/gh-aw/actions/setup_globals.cjs');
+            setupGlobals(core, github, context, exec, io);
+            const { main } = require('/opt/gh-aw/actions/run_operation_update_upgrade.cjs');
+            await main();

package/.github/workflows/auto-release.yml

@@ -0,0 +1,68 @@
+name: Auto Release on Merge
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  auto-release:
+    # Only run for dependency maintenance merges (patch bumps)
+    if: contains(github.event.head_commit.message, '[deps]') || contains(github.event.head_commit.message, 'Dependency updates and security patches')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+
+      - name: Extract version from package.json
+        id: version
+        run: |
+          VERSION=$(jq -r '.version' package.json)
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "tag=v$VERSION" >> $GITHUB_OUTPUT
+          echo "Detected version: $VERSION"
+
+      - name: Check if tag already exists
+        id: check-tag
+        run: |
+          if git rev-parse "v${{ steps.version.outputs.version }}" >/dev/null 2>&1; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+            echo "Tag v${{ steps.version.outputs.version }} already exists, skipping"
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+            echo "Tag v${{ steps.version.outputs.version }} does not exist, will create"
+          fi
+
+      - name: Create git tag
+        if: steps.check-tag.outputs.exists == 'false'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "v${{ steps.version.outputs.version }}" -m "Release v${{ steps.version.outputs.version }} - Dependency updates and security patches"
+          git push origin "v${{ steps.version.outputs.version }}"
+
+      - name: Create GitHub release
+        if: steps.check-tag.outputs.exists == 'false'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          RELEASE_FILE="releases/v${VERSION}.md"
+
+          if [ -f "$RELEASE_FILE" ]; then
+            gh release create "v${VERSION}" \
+              --title "v${VERSION} - Dependency updates and security patches" \
+              --notes-file "$RELEASE_FILE"
+          else
+            gh release create "v${VERSION}" \
+              --title "v${VERSION} - Dependency updates and security patches" \
+              --generate-notes
+          fi
+
+          echo "✅ Release v${VERSION} created"
+          echo "📦 npm publish will be triggered by the release event"
+          echo "🐳 Docker publish will be triggered by lint-and-test on main"