Documentation
¶
Overview ¶
Package mcp implements the Model Context Protocol server for Engram.
This exposes memory tools via MCP stdio transport so ANY agent (OpenCode, Claude Code, Cursor, Windsurf, etc.) can use Engram's persistent memory just by adding it as an MCP server.
Tool profiles allow agents to load only the tools they need:
engram mcp → all 22 tools (default) engram mcp --tools=agent → 18 tools agents actually use (per skill files) engram mcp --tools=admin → 4 tools for TUI/CLI (delete, stats, timeline, merge) engram mcp --tools=agent,admin → combine profiles engram mcp --tools=mem_save,mem_search → individual tool names
Index ¶
- Variables
- func DoctorToolHandler(s *store.Store) server.ToolHandlerFunc
- func NewServer(s *store.Store) *server.MCPServer
- func NewServerWithConfig(s *store.Store, cfg MCPConfig, allowlist map[string]bool) *server.MCPServer
- func NewServerWithTools(s *store.Store, allowlist map[string]bool) *server.MCPServer
- func ResolveTools(input string) map[string]bool
- type MCPConfig
- type SessionActivity
- func (a *SessionActivity) ActivityScore(sessionID string) string
- func (a *SessionActivity) ClearSession(sessionID string)
- func (a *SessionActivity) CurrentPrompt(sessionID, project string) (string, bool)
- func (a *SessionActivity) IssueAmbiguousProjectRecoveryToken(sessionID string, availableProjects []string, contextPath string) string
- func (a *SessionActivity) NudgeIfNeeded(sessionID string) string
- func (a *SessionActivity) NudgeIfNeededForProject(sessionID, project string) string
- func (a *SessionActivity) RecordProjectSave(project string)
- func (a *SessionActivity) RecordPrompt(sessionID, project, content string)
- func (a *SessionActivity) RecordSave(sessionID string)
- func (a *SessionActivity) RecordSaveForProject(sessionID, project string)
- func (a *SessionActivity) RecordToolCall(sessionID string)
- func (a *SessionActivity) ValidateAmbiguousProjectRecoveryToken(sessionID, token, selectedProject string, availableProjects []string, ...) bool
Constants ¶
This section is empty.
Variables ¶
var ProfileAdmin = map[string]bool{ "mem_delete": true, "mem_stats": true, "mem_timeline": true, "mem_merge_projects": true, }
ProfileAdmin contains tools for TUI, dashboards, and manual curation that are NOT referenced in any agent skill or memory protocol.
var ProfileAgent = map[string]bool{ "mem_save": true, "mem_search": true, "mem_context": true, "mem_session_summary": true, "mem_session_start": true, "mem_session_end": true, "mem_get_observation": true, "mem_suggest_topic_key": true, "mem_capture_passive": true, "mem_save_prompt": true, "mem_update": true, "mem_current_project": true, "mem_judge": true, "mem_compare": true, "mem_doctor": true, "mem_review": true, "mem_pin": true, "mem_unpin": true, }
ProfileAgent contains the tool names that AI agents need. Sourced from actual skill files and memory protocol instructions across all 4 supported agents (Claude Code, OpenCode, Gemini CLI, Codex).
var Profiles = map[string]map[string]bool{ "agent": ProfileAgent, "admin": ProfileAdmin, }
Profiles maps profile names to their tool sets.
Functions ¶
func DoctorToolHandler ¶
func DoctorToolHandler(s *store.Store) server.ToolHandlerFunc
DoctorToolHandler returns a tool handler function for mem_doctor.
func NewServerWithConfig ¶
func NewServerWithConfig(s *store.Store, cfg MCPConfig, allowlist map[string]bool) *server.MCPServer
NewServerWithConfig creates an MCP server with full configuration including default project detection and optional tool allowlist.
func NewServerWithTools ¶
NewServerWithTools creates an MCP server registering only the tools in the allowlist. If allowlist is nil, all tools are registered.
func ResolveTools ¶
ResolveTools takes a comma-separated string of profile names and/or individual tool names and returns the set of tool names to register. An empty input means "all" — every tool is registered.
Types ¶
type MCPConfig ¶
type MCPConfig struct {
// DefaultProject is a trusted process-level project override supplied by
// long-lived MCP hosts (for example, `engram mcp --project NAME` or
// ENGRAM_PROJECT). When set, it is used before cwd detection for MCP
// auto-resolution; per-call project arguments remain separately validated.
DefaultProject string
// BM25Floor overrides the default BM25 score floor used by FindCandidates
// during conflict candidate detection (REQ-001). The floor is the minimum
// acceptable BM25 rank (negative; closer to 0 = better match). Candidates
// whose score falls below this threshold are excluded.
//
// nil means "use the store default" (-2.0). An explicit pointer value
// (including 0.0) is forwarded directly. Using a pointer avoids the
// zero-value ambiguity where 0.0 would otherwise be indistinguishable
// from "not set".
BM25Floor *float64
// Limit overrides the maximum number of conflict candidates returned per
// mem_save call (REQ-001). nil means "use the store default" (3).
// An explicit pointer value (including 0) is forwarded directly.
Limit *int
}
MCPConfig holds configuration for the MCP server.
type SessionActivity ¶
type SessionActivity struct {
// contains filtered or unexported fields
}
SessionActivity tracks tool call activity for save reminders and activity scores.
func NewSessionActivity ¶
func NewSessionActivity(nudgeAfter time.Duration) *SessionActivity
NewSessionActivity creates a new activity tracker with the given nudge threshold.
func (*SessionActivity) ActivityScore ¶
func (a *SessionActivity) ActivityScore(sessionID string) string
ActivityScore returns a formatted activity score string for the session.
func (*SessionActivity) ClearSession ¶
func (a *SessionActivity) ClearSession(sessionID string)
ClearSession removes the session entry, freeing memory.
func (*SessionActivity) CurrentPrompt ¶
func (a *SessionActivity) CurrentPrompt(sessionID, project string) (string, bool)
CurrentPrompt returns the latest prompt for the session when it belongs to the same project as the save operation.
func (*SessionActivity) IssueAmbiguousProjectRecoveryToken ¶
func (a *SessionActivity) IssueAmbiguousProjectRecoveryToken(sessionID string, availableProjects []string, contextPath string) string
IssueAmbiguousProjectRecoveryToken generates and registers a new short-lived recovery token for resolving ambiguous projects.
func (*SessionActivity) NudgeIfNeeded ¶
func (a *SessionActivity) NudgeIfNeeded(sessionID string) string
NudgeIfNeeded returns a reminder string if too much time has passed since the last save in this session. Returns empty string if no nudge needed.
func (*SessionActivity) NudgeIfNeededForProject ¶
func (a *SessionActivity) NudgeIfNeededForProject(sessionID, project string) string
NudgeIfNeededForProject returns a nudge using session activity unless a recent successful save exists for the project.
func (*SessionActivity) RecordProjectSave ¶
func (a *SessionActivity) RecordProjectSave(project string)
RecordProjectSave records a successful save for project-level nudge freshness. It does not affect per-session activity scores.
func (*SessionActivity) RecordPrompt ¶
func (a *SessionActivity) RecordPrompt(sessionID, project, content string)
RecordPrompt stores the latest user prompt observed for a session. MCP does not currently receive user prompts on every tool call, so callers must feed this explicitly when prompt text is available.
func (*SessionActivity) RecordSave ¶
func (a *SessionActivity) RecordSave(sessionID string)
RecordSave increments the save counter and updates lastSaveAt.
func (*SessionActivity) RecordSaveForProject ¶
func (a *SessionActivity) RecordSaveForProject(sessionID, project string)
RecordSaveForProject records a save in its session and for project-level nudge freshness.
func (*SessionActivity) RecordToolCall ¶
func (a *SessionActivity) RecordToolCall(sessionID string)
RecordToolCall increments the tool call counter for a session.
func (*SessionActivity) ValidateAmbiguousProjectRecoveryToken ¶
func (a *SessionActivity) ValidateAmbiguousProjectRecoveryToken(sessionID, token, selectedProject string, availableProjects []string, contextPath string) bool
ValidateAmbiguousProjectRecoveryToken verifies that a recovery token is valid, has not expired, and matches the expected session, project choices, and path.