memory-journal-mcp 4.3.1 → 4.4.0

package/src/constants/ServerInstructions.ts

@@ -4,7 +4,7 @@
  * These instructions are automatically sent to MCP clients during initialization,
  * providing guidance for AI agents on tool usage.
  *
- * v3.1.6: Optimized for token efficiency with tiered instruction levels.
+ * Unreleased: Optimized for token efficiency with tiered instruction levels.
  */
 
 import type { ToolGroup } from '../types/index.js'
@@ -80,6 +80,7 @@ const GITHUB_INSTRUCTIONS = `
 - After closing issue/merging PR → create summary entry with learnings
 - CI failures → \`actions-failure-digest\` prompt or \`memory://actions/recent\`
 - Kanban: \`get_kanban_board(project_number)\` → \`move_kanban_item\` → document completion
+- Milestones: \`get_github_milestones\` → track project progress, \`memory://github/milestones\`
 - GitHub tools auto-detect owner/repo from git context; specify explicitly if null
 `
 
@@ -122,10 +123,10 @@ const TOOL_PARAMETER_REFERENCE = `
 ### Entry Operations
 | Tool | Required Parameters | Optional Parameters |
 |------|---------------------|---------------------|
-| \`create_entry\` | \`content\` (string) | \`entry_type\`, \`tags\` (array), \`is_personal\` (bool) |
+| \`create_entry\` | \`content\` (string) | \`entry_type\`, \`tags\` (array), \`is_personal\`, \`significance_type\`, \`share_with_team\`, \`auto_context\`, \`issue_number\`, \`issue_url\`, \`pr_number\`, \`pr_url\`, \`pr_status\`, \`project_number\`, \`project_owner\`, \`workflow_run_id\`, \`workflow_name\`, \`workflow_status\` |
 | \`create_entry_minimal\` | \`content\` (string) | none |
-| \`get_entry_by_id\` | \`entry_id\` (number) | none |
-| \`get_recent_entries\` | none | \`limit\` (default 10), \`is_personal\` (bool) |
+| \`get_entry_by_id\` | \`entry_id\` (number) | \`include_relationships\` (bool, default true) |
+| \`get_recent_entries\` | none | \`limit\` (default 5), \`is_personal\` (bool) |
 | \`update_entry\` | \`entry_id\` (number) | \`content\`, \`tags\`, \`entry_type\`, \`is_personal\` |
 | \`delete_entry\` | \`entry_id\` (number) | \`permanent\` (bool, default false) |
 | \`list_tags\` | none | none |
@@ -133,33 +134,40 @@ const TOOL_PARAMETER_REFERENCE = `
 ### Search Tools
 | Tool | Required Parameters | Optional Parameters |
 |------|---------------------|---------------------|
-| \`search_entries\` | \`query\` (string) | \`limit\`, \`entry_type\`, \`tags\` |
-| \`search_by_date_range\` | \`start_date\`, \`end_date\` (YYYY-MM-DD) | \`tags\`, \`entry_type\` |
-| \`semantic_search\` | \`query\` (string) | \`limit\`, \`similarity_threshold\` (default 0.3) |
+| \`search_entries\` | none | \`query\`, \`limit\`, \`is_personal\`, \`issue_number\`, \`pr_number\`, \`pr_status\`, \`project_number\`, \`workflow_run_id\` |
+| \`search_by_date_range\` | \`start_date\`, \`end_date\` (YYYY-MM-DD) | \`tags\`, \`entry_type\`, \`is_personal\`, \`issue_number\`, \`pr_number\`, \`project_number\`, \`workflow_run_id\` |
+| \`semantic_search\` | \`query\` (string) | \`limit\`, \`similarity_threshold\` (default 0.25), \`is_personal\`, \`hint_on_empty\` (bool, default true) |
 | \`get_vector_index_stats\` | none | none |
 
 ### Relationship Tools
 | Tool | Required Parameters | Notes |
 |------|---------------------|-------|
-| \`link_entries\` | \`from_entry_id\`, \`to_entry_id\` (numbers) | Types: \`evolves_from\`, \`references\`, \`implements\`, \`clarifies\`, \`response_to\`, \`blocked_by\`, \`resolved\`, \`caused\` |
-| \`visualize_relationships\` | \`entry_id\` (number) | Optional \`depth\` (default 2). Returns Mermaid diagram. |
+| \`link_entries\` | \`from_entry_id\`, \`to_entry_id\` (numbers) | Types: \`evolves_from\`, \`references\`, \`implements\`, \`clarifies\`, \`response_to\`, \`blocked_by\`, \`resolved\`, \`caused\`. Optional \`description\`. |
+| \`visualize_relationships\` | none | Optional \`entry_id\`, \`tags\` (array), \`depth\` (1-3, default 2), \`limit\` (default 20). Returns Mermaid diagram. |
 
 ### GitHub Tools
 | Tool | Required Parameters | Notes |
 |------|---------------------|-------|
-| \`get_github_context\` | none | Returns repo info, open issues/PRs |
-| \`get_github_issues\` | none | Optional \`state\` (open/closed/all), \`limit\` |
-| \`get_github_prs\` | none | Optional \`state\`, \`limit\` |
-| \`get_github_issue\` | \`issue_number\` (number) | Fetches single issue details |
-| \`get_github_pr\` | \`pr_number\` (number) | Fetches single PR details |
+| \`get_github_context\` | none | Returns repo info, open issues/PRs. Only counts OPEN items. |
+| \`get_github_issues\` | none | Optional \`state\` (open/closed/all), \`limit\`, \`owner\`, \`repo\` |
+| \`get_github_prs\` | none | Optional \`state\`, \`limit\`, \`owner\`, \`repo\` |
+| \`get_github_issue\` | \`issue_number\` (number) | Optional \`owner\`, \`repo\`. Fetches single issue details. |
+| \`get_github_pr\` | \`pr_number\` (number) | Optional \`owner\`, \`repo\`. Fetches single PR details. |
+| \`get_repo_insights\` | none | Optional \`sections\` (stars/traffic/referrers/paths/all, default "stars"), \`owner\`, \`repo\`. Requires push access for traffic. |
 
 GitHub tools auto-detect owner/repo from GITHUB_REPO_PATH. If \`detectedOwner\`/\`detectedRepo\` are null in response, specify \`owner\` and \`repo\` parameters explicitly.
 
+### Issue Lifecycle Tools
+| Tool | Required Parameters | Notes |
+|------|---------------------|-------|
+| \`create_github_issue_with_entry\` | \`title\` (string) | Optional \`body\`, \`labels\` (array), \`assignees\` (array), \`project_number\`, \`initial_status\`, \`milestone_number\`, \`entry_content\`, \`tags\`, \`owner\`, \`repo\` |
+| \`close_github_issue_with_entry\` | \`issue_number\` (number) | Optional \`comment\`, \`resolution_notes\`, \`tags\`, \`move_to_done\` (bool), \`project_number\`, \`owner\`, \`repo\` |
+
 ### Kanban Tools (GitHub Projects v2)
 | Tool | Required Parameters | Notes |
 |------|---------------------|-------|
-| \`get_kanban_board\` | \`project_number\` (number) | Returns columns with items grouped by Status |
-| \`move_kanban_item\` | \`project_number\`, \`item_id\` (string), \`target_status\` (string) | \`item_id\` is the GraphQL node ID from board items |
+| \`get_kanban_board\` | \`project_number\` (number) | Optional \`owner\`. Returns columns with items grouped by Status |
+| \`move_kanban_item\` | \`project_number\`, \`item_id\` (string), \`target_status\` (string) | Optional \`owner\`. \`item_id\` is the GraphQL node ID from board items. Status matching is case-insensitive. |
 
 **Finding the right project**: User may have multiple projects. Use \`get_kanban_board\` with different project numbers (1, 2, 3...) to find the correct one by checking \`projectTitle\`.
 
@@ -176,33 +184,53 @@ Kanban resources:
 - \`memory://kanban/{project_number}\` - JSON board data
 - \`memory://kanban/{project_number}/diagram\` - Mermaid visualization
 
+### Milestone Tools
+| Tool | Required Parameters | Notes |
+|------|---------------------|-------|
+| \`get_github_milestones\` | none | Optional \`state\` (open/closed/all), \`limit\`, \`owner\`, \`repo\` |
+| \`get_github_milestone\` | \`milestone_number\` (number) | Optional \`owner\`, \`repo\`. Single milestone with completion %. |
+| \`create_github_milestone\` | \`title\` (string) | Optional \`description\`, \`due_on\` (YYYY-MM-DD), \`owner\`, \`repo\` |
+| \`update_github_milestone\` | \`milestone_number\` (number) | Optional \`title\`, \`description\`, \`due_on\`, \`state\` (open/closed), \`owner\`, \`repo\` |
+| \`delete_github_milestone\` | \`milestone_number\`, \`confirm: true\` | Optional \`owner\`, \`repo\`. Permanent deletion. |
+
+Milestone resources:
+- \`memory://github/milestones\` - Open milestones with completion %
+- \`memory://milestones/{number}\` - Single milestone detail
+
 ### Admin Tools
 | Tool | Required Parameters | Notes |
 |------|---------------------|-------|
-| \`backup_journal\` | none | Optional \`backup_name\` |
+| \`backup_journal\` | none | Optional \`name\` (custom backup name) |
 | \`list_backups\` | none | Returns available backup files |
-| \`restore_backup\` | \`backup_filename\`, \`confirm: true\` | Creates auto-backup before restore |
+| \`cleanup_backups\` | none | Optional \`keep_count\` (default 5). Deletes old backups, keeps N most recent. |
+| \`restore_backup\` | \`filename\`, \`confirm: true\` | Creates auto-backup before restore |
 | \`add_to_vector_index\` | \`entry_id\` (single number) | Indexes one entry for semantic search |
 | \`rebuild_vector_index\` | none | Re-indexes all entries |
 
 ### Export Tools
 | Tool | Required Parameters | Notes |
 |------|---------------------|-------|
-| \`export_entries\` | none | Optional \`format\` (json/markdown), \`limit\`, \`tags\` |
+| \`export_entries\` | none | Optional \`format\` (json/markdown), \`limit\` (default 100), \`tags\`, \`start_date\`, \`end_date\`, \`entry_types\` |
 
 ## Entry Types
 Valid values for \`entry_type\` parameter:
 - \`personal_reflection\` (default) - Personal thoughts and notes
-- \`technical_note\` - Technical documentation
+- \`project_decision\` - Architectural and team decisions
+- \`technical_achievement\` - Milestones and breakthroughs
 - \`bug_fix\` - Bug fixes and resolutions
-- \`progress_update\` - Project progress updates
+- \`feature_implementation\` - Feature builds and rollouts
 - \`code_review\` - Code review notes
-- \`deployment\` - Deployment records
-- \`technical_achievement\` - Milestones and breakthroughs
+- \`meeting_notes\` - Meeting summaries
+- \`learning\` - Learning and research insights
+- \`research\` - Research and exploration
+- \`planning\` - Planning sessions and roadmaps (\`create_github_issue_with_entry\` uses this type)
+- \`retrospective\` - Sprint and project retrospectives
+- \`standup\` - Daily standup notes
+- \`other\` - Miscellaneous
 
 ## Field Notes
 - **\`autoContext\`**: Reserved for future automatic context capture. Currently always \`null\`.
-- **\`memory://tags\` vs \`list_tags\`**: Resource includes \`id\`, \`name\`, \`count\`; tool returns only \`name\`, \`count\`.
+- **\`memory://tags\` vs \`list_tags\`**: Resource includes \`id\`, \`name\`, \`count\`; tool returns only \`name\`, \`count\`. Neither returns orphan tags with zero usage.
 - **Tag naming**: Use lowercase with dashes (e.g., \`bug-fix\`, \`phase-2\`). Use \`merge_tags\` to consolidate duplicates (e.g., merge \`phase2\` into \`phase-2\`).
 - **\`merge_tags\` behavior**: Only updates non-deleted entries. Deleted entries retain their original tags.
 - **\`prStatus\` in entries**: Reflects PR state at entry creation time, not current state. Use \`get_github_pr\` for live status.
@@ -211,19 +239,35 @@ Valid values for \`entry_type\` parameter:
 - **\`semantic_search\` thresholds**: Default similarity threshold is 0.25. For broader matches, try 0.15-0.2. Higher values (0.4+) return only very close semantic matches.
 - **Causal relationship types**: Use \`blocked_by\` (A was blocked by B), \`resolved\` (A resolved B), \`caused\` (A caused B) for decision tracing and failure analysis. Visualizations use distinct arrow styles for causal types.
 - **Enhanced analytics**: \`get_statistics\` returns \`decisionDensity\` (significant entries per period), \`relationshipComplexity\` (avg relationships per entry), \`activityTrend\` (period-over-period growth %), and \`causalMetrics\` (counts for blocked_by/resolved/caused).
-- **Importance scores**: \`get_entry_by_id\` returns an \`importance\` score (0.0-1.0) based on: significance type (30%), relationship count (35%), causal relationships (20%), and recency (15%). \`memory://significant\` sorts entries by importance.
+- **Importance scores**: \`get_entry_by_id\` returns \`importance\` (0.0-1.0) and \`importanceBreakdown\` showing weighted components: significance (30%), relationships (35%), causal (20%), recency (15%). \`memory://significant\` sorts entries by importance.
+- **\`inactiveThresholdDays\`**: \`get_cross_project_insights\` includes \`inactiveThresholdDays: 7\` in output, documenting the inactive project classification cutoff.
+- **GitHub metadata in entries**: Entry output includes 10 GitHub fields (\`issueNumber\`, \`issueUrl\`, \`prNumber\`, \`prUrl\`, \`prStatus\`, \`projectNumber\`, \`projectOwner\`, \`workflowRunId\`, \`workflowName\`, \`workflowStatus\`) in all tool responses.
+- **\`delete_entry\` on soft-deleted**: \`delete_entry(id, permanent: true)\` works on previously soft-deleted entries. Returns \`success: false\` for nonexistent entries.
 
 ## Key Resources
 | URI | Description |
 |-----|-------------|
 | \`memory://health\` | Server health, DB stats, tool filter status |
 | \`memory://briefing\` | Session context with userMessage to show user |
+| \`memory://instructions\` | Full server instructions and tool reference |
 | \`memory://statistics\` | Entry counts by type and period |
 | \`memory://recent\` | 10 most recent entries |
 | \`memory://tags\` | All tags with usage counts |
-| \`memory://significant\` | Entries marked as milestones/breakthroughs |
+| \`memory://significant\` | Entries sorted by importance score |
 | \`memory://graph/recent\` | Mermaid diagram of recent relationships |
+| \`memory://graph/actions\` | CI/CD narrative graph |
+| \`memory://actions/recent\` | Recent workflow runs |
+| \`memory://team/recent\` | Team-shared entries |
+| \`memory://github/status\` | GitHub repo overview (CI, issues, PRs, milestones) |
+| \`memory://github/milestones\` | Open milestones with completion % |
+| \`memory://github/insights\` | Stars, forks, and 14-day traffic summary |
 | \`memory://kanban/{n}\` | Kanban board for project number n |
+| \`memory://kanban/{n}/diagram\` | Mermaid Kanban visualization |
+| \`memory://milestones/{n}\` | Single milestone detail + progress |
+| \`memory://projects/{n}/timeline\` | Project entries timeline |
+| \`memory://issues/{n}/entries\` | Entries linked to issue n |
+| \`memory://prs/{n}/entries\` | Entries linked to PR n |
+| \`memory://prs/{n}/timeline\` | PR lifecycle and linked entries |
 `
 
 /**

package/src/constants/icons.ts

@@ -143,6 +143,13 @@ export const ICON_PR: McpIcon = {
     sizes: ['24x24'],
 }
 
+/** Flag for milestone tracking */
+export const ICON_MILESTONE: McpIcon = {
+    src: 'data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"%3E%3Cpath d="M4 15s1-1 4-1 5 2 8 2 4-1 4-1V3s-1 1-4 1-5-2-8-2-4 1-4 1z"/%3E%3Cline x1="4" y1="22" x2="4" y2="15"/%3E%3C/svg%3E',
+    mimeType: 'image/svg+xml',
+    sizes: ['24x24'],
+}
+
 /** Message bubble for prompts */
 export const ICON_PROMPT: McpIcon = {
     src: 'data:image/svg+xml,%3Csvg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"%3E%3Cpath d="M21 15a2 2 0 01-2 2H7l-4 4V5a2 2 0 012-2h14a2 2 0 012 2z"/%3E%3C/svg%3E',

package/src/database/SqliteAdapter.ts

@@ -17,6 +17,8 @@ import type {
     EntryType,
     SignificanceType,
     RelationshipType,
+    ImportanceBreakdown,
+    ImportanceResult,
 } from '../types/index.js'
 
 // Schema SQL for initialization
@@ -125,6 +127,12 @@ export class SqliteAdapter {
     private readonly dbPath: string
     private initialized = false
 
+    /** Timer handle for debounced save */
+    private saveTimer: ReturnType<typeof setTimeout> | null = null
+
+    /** Debounce interval for batching disk writes (ms) */
+    private static readonly SAVE_DEBOUNCE_MS = 500
+
     constructor(dbPath: string) {
         this.dbPath = dbPath
     }
@@ -164,14 +172,34 @@ export class SqliteAdapter {
 
         logger.info('Database opened', { module: 'SqliteAdapter', dbPath: this.dbPath })
 
-        // Save after initialization
-        this.save()
+        // Immediate flush after initialization to persist schema
+        this.flushSave()
+    }
+
+    /**
+     * Schedule a debounced save to disk.
+     * Batches rapid mutations into a single write after SAVE_DEBOUNCE_MS.
+     * Used by all mutation methods (createEntry, updateEntry, etc.).
+     */
+    private scheduleSave(): void {
+        if (this.saveTimer !== null) {
+            clearTimeout(this.saveTimer)
+        }
+        this.saveTimer = setTimeout(() => {
+            this.flushSave()
+        }, SqliteAdapter.SAVE_DEBOUNCE_MS)
     }
 
     /**
-     * Save database to disk
+     * Immediately flush the database to disk (synchronous).
+     * Cancels any pending debounced save.
+     * Used by close() and initialize() for guaranteed persistence.
      */
-    private save(): void {
+    flushSave(): void {
+        if (this.saveTimer !== null) {
+            clearTimeout(this.saveTimer)
+            this.saveTimer = null
+        }
         if (!this.db) return
         const data = this.db.export()
         const buffer = Buffer.from(data)
@@ -179,11 +207,12 @@ export class SqliteAdapter {
     }
 
     /**
-     * Close database connection
+     * Close database connection.
+     * Flushes any pending writes immediately before closing.
      */
     close(): void {
         if (this.db) {
-            this.save()
+            this.flushSave()
             this.db.close()
             this.db = null
         }
@@ -264,7 +293,7 @@ export class SqliteAdapter {
             this.linkTagsToEntry(entryId, tags)
         }
 
-        this.save()
+        this.scheduleSave()
 
         logger.info('Entry created', {
             module: 'SqliteAdapter',
@@ -297,30 +326,65 @@ export class SqliteAdapter {
         return this.rowToEntry(row)
     }
 
+    /**
+     * Get entry by ID, including soft-deleted entries.
+     * Used for permanent deletion of previously soft-deleted entries.
+     */
+    getEntryByIdIncludeDeleted(id: number): JournalEntry | null {
+        const db = this.ensureDb()
+        const result = db.exec(`SELECT * FROM memory_journal WHERE id = ?`, [id])
+
+        if (result.length === 0 || result[0]?.values.length === 0) return null
+
+        const columns = result[0]?.columns ?? []
+        const values = result[0]?.values[0] ?? []
+        const row = this.rowToObject(columns, values)
+
+        return this.rowToEntry(row)
+    }
+
+    /**
+     * Importance score result with scoring breakdown
+     */
+    static readonly IMPORTANCE_WEIGHTS = {
+        significance: 0.3,
+        relationships: 0.35,
+        causal: 0.2,
+        recency: 0.15,
+    } as const
+
     /**
      * Calculate importance score for an entry (0.0-1.0)
      *
      * Formula:
-     * - significanceWeight (0.30): 1.0 if significanceType set, else 0.0
-     * - relationshipWeight (0.35): min(relCount / 5, 1.0)
-     * - causalWeight (0.20): min(causalCount / 3, 1.0)
-     * - recencyWeight (0.15): max(0, 1 - daysSince / 90)
+     * - significance (0.30): 1.0 if significanceType set, else 0.0
+     * - relationships (0.35): min(relCount / 5, 1.0)
+     * - causal (0.20): min(causalCount / 3, 1.0)
+     * - recency (0.15): max(0, 1 - daysSince / 90)
+     *
+     * Returns ImportanceResult with score and component breakdown.
      */
-    calculateImportance(entryId: number): number {
+    calculateImportance(entryId: number): ImportanceResult {
         const db = this.ensureDb()
+        const round2 = (n: number): number => Math.round(n * 100) / 100
 
         // Get entry data
         const entryResult = db.exec(
             `SELECT significance_type, timestamp FROM memory_journal WHERE id = ? AND deleted_at IS NULL`,
             [entryId]
         )
-        if (entryResult.length === 0 || entryResult[0]?.values.length === 0) return 0
+        if (entryResult.length === 0 || entryResult[0]?.values.length === 0) {
+            return {
+                score: 0,
+                breakdown: { significance: 0, relationships: 0, causal: 0, recency: 0 },
+            }
+        }
 
         const significanceType = entryResult[0]?.values[0]?.[0] as string | null
         const timestamp = entryResult[0]?.values[0]?.[1] as string
 
         // Significance weight: 1.0 if set, else 0.0
-        const significanceWeight = significanceType ? 1.0 : 0.0
+        const significanceRaw = significanceType ? 1.0 : 0.0
 
         // Relationship count (total relationships involving this entry)
         const relResult = db.exec(
@@ -328,7 +392,7 @@ export class SqliteAdapter {
             [entryId, entryId]
         )
         const relCount = (relResult[0]?.values[0]?.[0] as number) ?? 0
-        const relationshipWeight = Math.min(relCount / 5, 1.0)
+        const relationshipsRaw = Math.min(relCount / 5, 1.0)
 
         // Causal relationships count
         const causalResult = db.exec(
@@ -338,23 +402,33 @@ export class SqliteAdapter {
             [entryId, entryId]
         )
         const causalCount = (causalResult[0]?.values[0]?.[0] as number) ?? 0
-        const causalWeight = Math.min(causalCount / 3, 1.0)
+        const causalRaw = Math.min(causalCount / 3, 1.0)
 
         // Recency weight: decays over 90 days
         const entryDate = new Date(timestamp)
         const now = new Date()
         const daysSince = Math.floor((now.getTime() - entryDate.getTime()) / (1000 * 60 * 60 * 24))
-        const recencyWeight = Math.max(0, 1 - daysSince / 90)
+        const recencyRaw = Math.max(0, 1 - daysSince / 90)
+
+        const w = SqliteAdapter.IMPORTANCE_WEIGHTS
 
-        // Weighted sum
-        const importance =
-            significanceWeight * 0.3 +
-            relationshipWeight * 0.35 +
-            causalWeight * 0.2 +
-            recencyWeight * 0.15
+        // Weighted contributions
+        const breakdown: ImportanceBreakdown = {
+            significance: round2(significanceRaw * w.significance),
+            relationships: round2(relationshipsRaw * w.relationships),
+            causal: round2(causalRaw * w.causal),
+            recency: round2(recencyRaw * w.recency),
+        }
 
-        // Round to 2 decimal places
-        return Math.round(importance * 100) / 100
+        // Total score
+        const score = round2(
+            significanceRaw * w.significance +
+                relationshipsRaw * w.relationships +
+                causalRaw * w.causal +
+                recencyRaw * w.recency
+        )
+
+        return { score, breakdown }
     }
 
     /**
@@ -382,6 +456,34 @@ export class SqliteAdapter {
         )
     }
 
+    /**
+     * Get a page of active entries for batch processing (e.g., vector index rebuild).
+     * Returns entries ordered by ID ascending for deterministic pagination.
+     */
+    getEntriesPage(offset: number, limit: number): JournalEntry[] {
+        const db = this.ensureDb()
+        const result = db.exec(
+            `SELECT * FROM memory_journal WHERE deleted_at IS NULL ORDER BY id ASC LIMIT ? OFFSET ?`,
+            [limit, offset]
+        )
+        if (result.length === 0) return []
+
+        const columns = result[0]?.columns ?? []
+        return (result[0]?.values ?? []).map((values) =>
+            this.rowToEntry(this.rowToObject(columns, values))
+        )
+    }
+
+    /**
+     * Get total count of active (non-deleted) entries.
+     * Used for progress reporting and pagination bounds.
+     */
+    getActiveEntryCount(): number {
+        const db = this.ensureDb()
+        const result = db.exec(`SELECT COUNT(*) FROM memory_journal WHERE deleted_at IS NULL`)
+        return (result[0]?.values[0]?.[0] as number) ?? 0
+    }
+
     /**
      * Update an entry
      */
@@ -425,7 +527,7 @@ export class SqliteAdapter {
             this.linkTagsToEntry(id, updates.tags)
         }
 
-        this.save()
+        this.scheduleSave()
 
         logger.info('Entry updated', {
             module: 'SqliteAdapter',
@@ -438,17 +540,23 @@ export class SqliteAdapter {
 
     /**
      * Soft delete an entry
+     * Returns false if entry does not exist (P154: Proactive Object Existence Verification)
      */
     deleteEntry(id: number, permanent = false): boolean {
         const db = this.ensureDb()
 
+        // P154: Pre-check entry existence before mutation
+        // For permanent deletion, also look through soft-deleted entries
+        const entry = permanent ? this.getEntryByIdIncludeDeleted(id) : this.getEntryById(id)
+        if (!entry) return false
+
         if (permanent) {
             db.run('DELETE FROM memory_journal WHERE id = ?', [id])
         } else {
             db.run(`UPDATE memory_journal SET deleted_at = datetime('now') WHERE id = ?`, [id])
         }
 
-        this.save()
+        this.scheduleSave()
         return true
     }
 
@@ -610,11 +718,11 @@ export class SqliteAdapter {
     }
 
     /**
-     * List all tags
+     * List all tags with at least one usage
      */
     listTags(): Tag[] {
         const db = this.ensureDb()
-        const result = db.exec('SELECT * FROM tags ORDER BY usage_count DESC')
+        const result = db.exec('SELECT * FROM tags WHERE usage_count > 0 ORDER BY usage_count DESC')
 
         if (result.length === 0) return []
 
@@ -691,7 +799,7 @@ export class SqliteAdapter {
         db.run('DELETE FROM entry_tags WHERE tag_id = ?', [sourceTagId])
         db.run('DELETE FROM tags WHERE id = ?', [sourceTagId])
 
-        this.save()
+        this.scheduleSave()
 
         logger.info('Tags merged', {
             module: 'SqliteAdapter',
@@ -708,6 +816,7 @@ export class SqliteAdapter {
 
     /**
      * Link two entries
+     * Throws if either entry does not exist (P154: Proactive Object Existence Verification)
      */
     linkEntries(
         fromEntryId: number,
@@ -717,6 +826,16 @@ export class SqliteAdapter {
     ): Relationship {
         const db = this.ensureDb()
 
+        // P154: Pre-check both entries exist before creating relationship
+        const fromEntry = this.getEntryById(fromEntryId)
+        if (!fromEntry) {
+            throw new Error(`Source entry ${String(fromEntryId)} not found`)
+        }
+        const toEntry = this.getEntryById(toEntryId)
+        if (!toEntry) {
+            throw new Error(`Target entry ${String(toEntryId)} not found`)
+        }
+
         db.run(
             `
             INSERT INTO relationships (from_entry_id, to_entry_id, relationship_type, description)
@@ -728,7 +847,7 @@ export class SqliteAdapter {
         const result = db.exec('SELECT last_insert_rowid() as id')
         const id = result[0]?.values[0]?.[0] as number
 
-        this.save()
+        this.scheduleSave()
 
         return {
             id,
@@ -1077,7 +1196,7 @@ export class SqliteAdapter {
         const newEntryCount = (newCountResult[0]?.values[0]?.[0] as number) ?? 0
 
         // Save to main database path
-        this.save()
+        this.flushSave()
 
         logger.info('Database restored from backup', {
             module: 'SqliteAdapter',
@@ -1195,6 +1314,17 @@ export class SqliteAdapter {
             autoContext: row['auto_context'] as string | null,
             deletedAt: row['deleted_at'] as string | null,
             tags: this.getTagsForEntry(id),
+            // GitHub integration fields
+            projectNumber: (row['project_number'] as number | null) ?? null,
+            projectOwner: (row['project_owner'] as string | null) ?? null,
+            issueNumber: (row['issue_number'] as number | null) ?? null,
+            issueUrl: (row['issue_url'] as string | null) ?? null,
+            prNumber: (row['pr_number'] as number | null) ?? null,
+            prUrl: (row['pr_url'] as string | null) ?? null,
+            prStatus: (row['pr_status'] as string | null) ?? null,
+            workflowRunId: (row['workflow_run_id'] as number | null) ?? null,
+            workflowName: (row['workflow_name'] as string | null) ?? null,
+            workflowStatus: (row['workflow_status'] as string | null) ?? null,
         }
     }
 

package/src/filtering/ToolFilter.ts

@@ -13,7 +13,7 @@ export type { ToolFilterConfig } from '../types/index.js'
 /**
  * Tool group definitions mapping group names to tool names
  *
- * All 33 tools are categorized here for filtering support.
+ * All 39 tools are categorized here for filtering support.
  */
 export const TOOL_GROUPS: Record<ToolGroup, string[]> = {
     core: [
@@ -45,6 +45,12 @@ export const TOOL_GROUPS: Record<ToolGroup, string[]> = {
         'move_kanban_item',
         'create_github_issue_with_entry',
         'close_github_issue_with_entry',
+        'get_github_milestones',
+        'get_github_milestone',
+        'create_github_milestone',
+        'update_github_milestone',
+        'delete_github_milestone',
+        'get_repo_insights',
     ],
     backup: ['backup_journal', 'list_backups', 'restore_backup', 'cleanup_backups'],
 }