1.8.0npm · gitmem-mcp · latest release
Observed 2026-08-17T13:40:50.841Z using mcpSecurity-inventory. Protocol 2025-06-18.
| Tool | Category | Risk |
|---|---|---|
absorb_observationsCapture observations from sub-agents and teammates. The lead agent parses findings from sub-agent responses, then calls this to persist and analyze them. Identifies scar candidates.Input schema{
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "Linear issue or task identifier (optional)"
},
"observations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"source": {
"type": "string",
"description": "Who made this observation (e.g., \"Sub-Agent: code review\")"
},
"text": {
"type": "string",
"description": "What was observed"
},
"severity": {
"type": "string",
"enum": [
"info",
"warning",
"scar_candidate"
],
"description": "Observation severity"
},
"context": {
"type": "string",
"description": "File, function, or area (optional)"
}
},
"required": [
"source",
"text",
"severity"
]
},
"description": "Array of observations from sub-agents/teammates"
}
},
"required": [
"observations"
]
} | — | — |
archive_learningArchives a learning (scar/win/pattern) by setting is_active=false and recording archived_at timestamp. Archived learnings are excluded from recall and search results but preserved for audit trail.Input schema{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "UUID or short ID prefix of the learning to archive (e.g., the 8-char prefix shown by recall/search)"
},
"reason": {
"type": "string",
"description": "Optional reason for archiving (e.g., 'superseded by PROJ-123', 'no longer relevant')"
}
},
"required": [
"id"
]
} | — | — |
cleanup_threadsTriage open threads by lifecycle health. Groups threads as active/cooling/dormant with vitality scores. Use auto_archive=true to archive threads dormant 30+ days. Review and resolve stale threads to keep your thread list healthy.Input schema{
"type": "object",
"properties": {
"project": {
"type": "string",
"description": "Project namespace (e.g., 'my-project'). Scopes sessions and searches."
},
"auto_archive": {
"type": "boolean",
"description": "If true, auto-archive threads that have been dormant for 30+ days"
}
}
} | — | — |
confirm_scarsConfirm surfaced scars with APPLYING/N_A/REFUTED decisions and evidence. REQUIRED after recall() before consequential actions. Each recalled scar must be addressed. APPLYING: past-tense evidence of compliance. N_A: explain why scar doesn't apply. REFUTED: acknowledge risk of overriding.Input schema{
"type": "object",
"properties": {
"confirmations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scar_id": {
"type": "string",
"description": "UUID of the surfaced scar (from recall result)"
},
"decision": {
"type": "string",
"enum": [
"APPLYING",
"N_A",
"REFUTED"
],
"description": "APPLYING: scar is relevant, evidence of compliance. N_A: scar doesn't apply, explain why. REFUTED: overriding scar, acknowledge risk."
},
"evidence": {
"type": "string",
"description": "Past-tense evidence (APPLYING), scenario comparison (N_A), or risk acknowledgment (REFUTED). Minimum 50 characters."
},
"relevance": {
"type": "string",
"enum": [
"high",
"low",
"noise"
],
"description": "How relevant was this scar to your plan? high=directly applicable, low=tangentially related, noise=not relevant to this context. Helps improve future recall quality."
}
},
"required": [
"scar_id",
"decision",
"evidence"
]
},
"description": "One confirmation per recalled scar. All recalled scars must be addressed."
}
},
"required": [
"confirmations"
]
} | — | — |
contribute_feedbackSubmit feedback about gitmem — feature requests, bug reports, friction points, or suggestions. Always saved locally to .gitmem/feedback/. If opted in, sent anonymously to improve gitmem. 10/session limit.Input schema{
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"feature_request",
"bug_report",
"friction",
"suggestion"
],
"description": "Feedback type"
},
"tool": {
"type": "string",
"description": "Which gitmem tool this relates to (e.g., 'recall', 'session_close')"
},
"description": {
"type": "string",
"description": "Detailed, actionable feedback. Min 20 chars."
},
"severity": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Impact: low=nice-to-have, medium=notable friction, high=blocking/broken"
},
"suggested_fix": {
"type": "string",
"description": "How this could be improved"
},
"context": {
"type": "string",
"description": "When/how this came up"
}
},
"required": [
"type",
"tool",
"description",
"severity"
]
} | — | — |
create_decisionLog architectural/operational decision to institutional memoryInput schema{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "Decision title"
},
"decision": {
"type": "string",
"description": "What was decided"
},
"rationale": {
"type": "string",
"description": "Why this decision was made"
},
"alternatives_considered": {
"type": "array",
"items": {
"type": "string"
},
"description": "Alternatives that were rejected"
},
"personas_involved": {
"type": "array",
"items": {
"type": "string"
},
"description": "Personas involved in decision"
},
"docs_affected": {
"type": "array",
"items": {
"type": "string"
},
"description": "Docs/files affected by this decision (relative paths from repo root)"
},
"linear_issue": {
"type": "string",
"description": "Associated Linear issue"
},
"session_id": {
"type": "string",
"description": "Current session ID"
},
"project": {
"type": "string",
"description": "Project namespace (e.g., 'my-project'). Scopes sessions and searches."
}
},
"required": [
"title",
"decision",
"rationale"
]
} | — | — |
create_learningCreate scar, win, or pattern entry in institutional memory. Frame as 'what we now know' — lead with the factual/architectural discovery, not what went wrong. Good: 'Fine-grained PATs are scoped to one resource owner'. Bad: 'Should have checked PAT type first'.Input schema{
"type": "object",
"properties": {
"learning_type": {
"type": "string",
"enum": [
"scar",
"win",
"pattern",
"anti_pattern"
],
"description": "Type of learning"
},
"title": {
"type": "string",
"description": "Frame as a knowledge discovery — what we now know. Lead with the factual insight, not self-criticism."
},
"description": {
"type": "string",
"description": "Detailed description. Include the architectural/behavioral fact that makes this retrievable by domain."
},
"severity": {
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low"
],
"description": "Severity level (required for scars)"
},
"scar_type": {
"type": "string",
"enum": [
"process",
"incident",
"context"
],
"description": "Scar type (process, incident, or context). Defaults to 'process'."
},
"counter_arguments": {
"type": "array",
"items": {
"type": "string"
},
"description": "Counter-arguments for scars (min 2 required)"
},
"problem_context": {
"type": "string",
"description": "Problem context (for wins)"
},
"solution_approach": {
"type": "string",
"description": "Solution approach (for wins)"
},
"applies_when": {
"type": "array",
"items": {
"type": "string"
},
"description": "When this pattern applies"
},
"domain": {
"type": "array",
"items": {
"type": "string"
},
"description": "Domain tags"
},
"keywords": {
"type": "array",
"items": {
"type": "string"
},
"description": "Search keywords"
},
"source_linear_issue": {
"type": "string",
"description": "Source Linear issue"
},
"project": {
"type": "string",
"description": "Project namespace (e.g., 'my-project'). Scopes sessions and searches."
}
},
"required": [
"learning_type",
"title",
"description"
]
} | — | — |
create_threadCreate an open thread to track unresolved work across sessions. Includes semantic dedup: if a similar open thread exists (cosine similarity > 0.85), returns the existing thread instead. Check the 'deduplicated' field in the response.Input schema{
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Thread description — what needs to be tracked or resolved"
},
"linear_issue": {
"type": "string",
"description": "Associated Linear issue (e.g., PROJ-123)"
}
},
"required": [
"text"
]
} | — | — |
dismiss_suggestionDismiss a suggested thread. Incremented dismiss count — suggestions dismissed 3+ times are permanently suppressed.Input schema{
"type": "object",
"properties": {
"suggestion_id": {
"type": "string",
"description": "Suggestion ID (e.g., \"ts-a1b2c3d4\") from suggested_threads list"
}
},
"required": [
"suggestion_id"
]
} | — | — |
gitmem-helpgitmem-help - Show available commands with ASCII art headerInput schema{
"type": "object",
"properties": {}
} | — | — |
healthShow write health for the current session. Reports success/failure rates for all tracked fire-and-forget operations (metrics, cache, triple writes, embeddings, scar usage). Use this to diagnose silent failures.Input schema{
"type": "object",
"properties": {
"failure_limit": {
"type": "number",
"description": "Max number of recent failures to return (default: 10)"
}
}
} | — | — |
index_docsScan a directory of markdown files, chunk them, embed them, and store them in a local doc index for semantic search. Supports incremental indexing: only re-processes changed files. Use search_docs to query the indexed docs.Input schema{
"type": "object",
"properties": {
"directory": {
"type": "string",
"description": "Absolute path to directory containing .md files to index"
},
"project": {
"type": "string",
"description": "Project namespace (e.g., 'my-project'). Scopes sessions and searches."
},
"exclude": {
"type": "array",
"items": {
"type": "string"
},
"description": "Directory names to exclude (default: ['_archive', 'node_modules', '.git'])"
},
"force": {
"type": "boolean",
"description": "Force re-index all files even if unchanged (default: false)"
},
"clear": {
"type": "boolean",
"description": "Clear the doc index for this project before indexing (default: false)"
}
},
"required": [
"directory"
]
} | — | — |
list_threadsList open threads across recent sessions. Shows unresolved work items that carry over between sessions. Use resolve_thread to mark threads as done.Input schema{
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"open",
"resolved"
],
"description": "Filter by status (default: open)"
},
"include_resolved": {
"type": "boolean",
"description": "Include recently resolved threads (default: false)"
},
"project": {
"type": "string",
"description": "Project namespace (e.g., 'my-project'). Scopes sessions and searches."
}
}
} | — | — |
logList recent learnings chronologically (like git log). Shows scars, wins, and patterns ordered by creation date.Input schema{
"type": "object",
"properties": {
"limit": {
"type": "number",
"description": "Number of entries to return (default: 10)"
},
"project": {
"type": "string",
"description": "Project namespace (e.g., 'my-project'). Scopes sessions and searches."
},
"learning_type": {
"type": "string",
"enum": [
"scar",
"win",
"pattern",
"anti_pattern"
],
"description": "Filter by learning type"
},
"severity": {
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low"
],
"description": "Filter by severity level"
},
"since": {
"type": "number",
"description": "Days to look back (e.g., 7 = last week)"
}
}
} | — | — |
prepare_contextGenerate portable memory payload for sub-agent injection. Formats institutional memory into compact or gate payloads that fit in Task tool prompts.Input schema{
"type": "object",
"properties": {
"plan": {
"type": "string",
"description": "What the team is about to do (e.g., 'review auth middleware', 'deploy edge function')"
},
"format": {
"type": "string",
"enum": [
"full",
"compact",
"gate"
],
"description": "Output format: full (rich markdown), compact (~500 tokens, one-line per scar), gate (~100 tokens, blocking scars only)"
},
"max_tokens": {
"type": "number",
"description": "Token budget for payload (default: 500 for compact, 100 for gate, unlimited for full)"
},
"agent_role": {
"type": "string",
"description": "Sub-agent role for relevance filtering (e.g., 'reviewer', 'deployer') — reserved for Phase 3"
},
"project": {
"type": "string",
"description": "Project namespace (e.g., 'my-project'). Scopes sessions and searches."
}
},
"required": [
"plan",
"format"
]
} | — | — |
promote_suggestionPromote a suggested thread to an open thread. Takes a suggestion_id from session_start's suggested_threads list and creates a real thread from it.Input schema{
"type": "object",
"properties": {
"suggestion_id": {
"type": "string",
"description": "Suggestion ID (e.g., \"ts-a1b2c3d4\") from suggested_threads list"
},
"project": {
"type": "string",
"description": "Project namespace (e.g., 'my-project'). Scopes sessions and searches."
}
},
"required": [
"suggestion_id"
]
} | — | — |
recallCheck institutional memory for relevant scars before taking action. Returns matching scars and their lessons. Integrates variant assignment when issue_id provided.Input schema{
"type": "object",
"properties": {
"plan": {
"type": "string",
"description": "What you're about to do (e.g., 'implement auth layer', 'deploy to production')"
},
"project": {
"type": "string",
"description": "Project namespace (e.g., 'my-project'). Scopes sessions and searches."
},
"match_count": {
"type": "number",
"description": "Number of scars to return (default: 3)"
},
"issue_id": {
"type": "string",
"description": "Linear issue identifier for variant assignment (e.g., 'PROJ-123'). When provided, scars with variants will be randomly assigned and formatted accordingly."
},
"similarity_threshold": {
"type": "number",
"description": "Minimum similarity score (0-1) to include results. Weak matches below threshold are suppressed. Default: 0.4 (free tier BM25), 0.35 (pro tier embeddings)."
}
},
"required": [
"plan"
]
} | — | — |
record_scar_usageTrack scar application for effectiveness measurementInput schema{
"type": "object",
"properties": {
"scar_id": {
"type": "string",
"description": "UUID of the scar"
},
"issue_id": {
"type": "string",
"description": "Linear issue UUID"
},
"issue_identifier": {
"type": "string",
"description": "Linear issue identifier (e.g., PROJ-123)"
},
"surfaced_at": {
"type": "string",
"description": "ISO timestamp when scar was retrieved"
},
"acknowledged_at": {
"type": "string",
"description": "ISO timestamp when scar was acknowledged"
},
"reference_type": {
"type": "string",
"enum": [
"explicit",
"implicit",
"acknowledged",
"refuted",
"none"
],
"description": "How the scar was referenced"
},
"reference_context": {
"type": "string",
"description": "How the scar was applied (1-2 sentences)"
},
"execution_successful": {
"type": "boolean",
"description": "Whether the task succeeded after applying scar"
},
"session_id": {
"type": "string",
"description": "GitMem session UUID (for non-issue session tracking)"
},
"agent": {
"type": "string",
"description": "Agent identity (e.g., cli, desktop, autonomous)"
},
"variant_id": {
"type": "string",
"description": "UUID of the assigned variant from scar_enforcement_variants (for A/B testing)"
}
},
"required": [
"scar_id",
"surfaced_at",
"reference_type",
"reference_context"
]
} | — | — |
reflect_scarsEnd-of-session scar reflection — the closing counterpart to confirm_scars. Mirrors CODA-1's [Scar Reflection] protocol. Call BEFORE session_close to provide evidence of how each surfaced scar was handled. OBEYED: concrete evidence of compliance (min 15 chars). REFUTED: why it didn't apply + what was done instead (min 30 chars). Session close uses reflections to set execution_successful accurately.Input schema{
"type": "object",
"properties": {
"reflections": {
"type": "array",
"items": {
"type": "object",
"properties": {
"scar_id": {
"type": "string",
"description": "UUID of the surfaced scar (from recall or session_start)"
},
"outcome": {
"type": "string",
"enum": [
"OBEYED",
"REFUTED"
],
"description": "OBEYED: followed the scar with evidence. REFUTED: scar didn't apply, explain why."
},
"evidence": {
"type": "string",
"description": "Concrete evidence of compliance (OBEYED, min 15 chars) or explanation of why scar didn't apply (REFUTED, min 30 chars)."
}
},
"required": [
"scar_id",
"outcome",
"evidence"
]
},
"description": "One reflection per surfaced scar."
}
},
"required": [
"reflections"
]
} | — | — |
resolve_threadMark an open thread as resolved. Use thread_id for exact match or text_match for fuzzy matching. Updates session state and .gitmem/threads.json.Input schema{
"type": "object",
"properties": {
"thread_id": {
"type": "string",
"description": "Thread ID (e.g., \"t-a1b2c3d4\") for exact resolution"
},
"text_match": {
"type": "string",
"description": "Fuzzy text match against thread descriptions (fallback if no thread_id)"
},
"resolution_note": {
"type": "string",
"description": "Brief note explaining how/why thread was resolved"
}
}
} | — | — |
searchSearch institutional memory by query. Unlike recall (which is action-oriented), search is exploration-oriented — returns matching scars/wins/patterns without side effects.Input schema{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Natural language search query (e.g., 'deployment failures', 'Supabase RLS')"
},
"match_count": {
"type": "number",
"description": "Number of results to return (default: 5)"
},
"project": {
"type": "string",
"description": "Project namespace (e.g., 'my-project'). Scopes sessions and searches."
},
"severity": {
"type": "string",
"enum": [
"critical",
"high",
"medium",
"low"
],
"description": "Filter by severity level"
},
"learning_type": {
"type": "string",
"enum": [
"scar",
"win",
"pattern",
"anti_pattern"
],
"description": "Filter by learning type"
}
},
"required": [
"query"
]
} | — | — |
search_docsSearch indexed repository documentation using semantic similarity (pro/dev tier) or BM25 keyword search (free tier). Returns relevant chunks with file paths for targeted reading. Index docs first with index_docs.Input schema{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Natural language search query (e.g., 'how does authentication work', 'database schema')"
},
"project": {
"type": "string",
"description": "Project namespace (e.g., 'my-project'). Scopes sessions and searches."
},
"category": {
"type": "string",
"description": "Filter results to a specific category (directory name, e.g., 'architecture', 'research')"
},
"match_count": {
"type": "number",
"description": "Maximum number of results to return (default: 5)"
}
},
"required": [
"query"
]
} | — | — |
session_closePersist session with compliance validation. Two modes: (1) Write closing_reflection and other payload to {gitmem_dir}/closing-payload.json, then call with session_id + close_type. (2) Pass closing_reflection directly as a parameter (simpler). Both work — inline params override file payload. task_completion is auto-generated. DISPLAY: Output the display field verbatim.Input schema{
"type": "object",
"properties": {
"session_id": {
"type": "string",
"description": "Session ID from session_start"
},
"close_type": {
"type": "string",
"enum": [
"standard",
"quick",
"autonomous"
],
"description": "Type of close (standard requires full reflection)"
},
"closing_reflection": {
"type": "object",
"description": "Session reflection (alternative to writing closing-payload.json). Keys: what_broke, what_took_longer, do_differently, what_worked, wrong_assumption, scars_applied, institutional_memory_items, collaborative_dynamic, rapport_notes"
},
"human_corrections": {
"type": "string",
"description": "Human corrections or 'none'"
},
"linear_issue": {
"type": "string",
"description": "Associated Linear issue"
},
"ceremony_duration_ms": {
"type": "number",
"description": "End-to-end ceremony duration from agent perspective (in milliseconds)"
}
},
"required": [
"session_id",
"close_type"
]
} | — | — |
session_refreshRe-surface institutional context (threads, decisions) for the current active session without creating a new session. Use mid-session when you need to remember where you left off, after context compaction, or after a long gap. DISPLAY: The result includes a pre-formatted 'display' field visible in the tool result. Output the display field verbatim as your response — tool results are collapsed in the CLI.Input schema{
"type": "object",
"properties": {
"project": {
"type": "string",
"description": "Project namespace (default: from active session). Free-form string (e.g., 'my-project')."
}
}
} | — | — |
session_startInitialize session, detect agent, load institutional context (last session, recent decisions, open threads). Scars surface on-demand via recall(). DISPLAY: The result includes a pre-formatted 'display' field visible in the tool result. Output the display field verbatim as your response — tool results are collapsed in the CLI.Input schema{
"type": "object",
"properties": {
"agent_identity": {
"type": "string",
"enum": [
"cli",
"desktop",
"autonomous",
"local",
"cloud"
],
"description": "Override agent identity (auto-detects if not provided)"
},
"linear_issue": {
"type": "string",
"description": "Current Linear issue identifier (e.g., PROJ-123)"
},
"issue_title": {
"type": "string",
"description": "Issue title for scar context"
},
"issue_description": {
"type": "string",
"description": "Issue description for scar context"
},
"issue_labels": {
"type": "array",
"items": {
"type": "string"
},
"description": "Issue labels for scar context"
},
"project": {
"type": "string",
"description": "Project namespace (e.g., 'my-project'). Scopes sessions and searches."
},
"force": {
"type": "boolean",
"description": "Force create new session even if one already exists"
}
}
} | — | — |
Compared with initial baseline using full_baseline.
| Risk | Change | Subject |
|---|---|---|
| No material changes recorded. | ||
| Severity | Finding | Advisory |
|---|---|---|
| No confirmed vulnerability is published for this version. | ||
Artifact SHA-256: 84804830a5de36918299f395f73d2b8dd0d756a290a824058fe14ba0ce95285b
Scanner: mcp-proof-engine 0.1.0.