Documentation
¶
Overview ¶
Package mcp implements the stdio MCP server that exposes the agent-facing tools (memory.fetch_context in M2; memory.propose_update and memory.status in M3).
The server reuses the same loading/fetch logic as the CLI (internal/cli and internal/memory) so behaviour stays in lockstep between transports.
See docs/patterns/mcp-tool-server.md and spike S2 results.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FetchContextInput ¶
type FetchContextInput struct {
Query string `json:"query,omitempty" jsonschema:"search query; empty returns the bootstrap pack"`
Scope []string `json:"scope,omitempty" jsonschema:"paths or module names to prioritize via substring match"`
Budget int `json:"budget,omitempty" jsonschema:"approximate character budget for the returned pack; 0 uses manifest default"`
Include []string `json:"include,omitempty" jsonschema:"context categories to include (advisory in M2; M3 enforces)"`
ExcludeArchive bool `json:"exclude_archive,omitempty" jsonschema:"if true, archive/ files are skipped entirely; defaults to false"`
}
FetchContextInput is the JSON schema for the memory.fetch_context tool's input. Struct tags drive both serialisation and the JSON Schema the SDK advertises to clients.
type FetchContextOutput ¶
type FetchContextOutput struct {
Context string `json:"context" jsonschema:"the Markdown context pack"`
IncludedFiles []memory.IncludedFile `json:"included_files" jsonschema:"per-file provenance for everything in the pack"`
Omitted []memory.OmittedFile `json:"omitted,omitempty" jsonschema:"candidates that were dropped (budget exhausted, parse error, etc.)"`
SuggestedNextQueries []string `json:"suggested_next_queries,omitempty"`
ContextMetadata memory.ContextMetadata `json:"context_metadata"`
}
FetchContextOutput mirrors memory.FetchResponse but lives in this package so the SDK generates a JSON schema we control. Field names match the design doc §15.1.
type ProposeUpdateInput ¶
type ProposeUpdateInput struct {
Intent string `` /* 165-byte string literal not displayed */
Rationale string `json:"rationale,omitempty" jsonschema:"short human-readable reason; shown in CLI status and used in the staging-id slug"`
Operations []memory.OperationInput `json:"operations" jsonschema:"one or more structured edits to apply"`
Sources []memory.Source `json:"sources,omitempty" jsonschema:"provenance citations (required for some categories, e.g. decisions)"`
Confidence string `json:"confidence,omitempty" jsonschema:"confirmed | inferred | user-provided | stale | unknown"`
Owner memory.OwnerInfo `json:"owner,omitempty" jsonschema:"identifier of the proposing agent; recorded in lock metadata"`
}
ProposeUpdateInput is the JSON shape callers send to memory.propose_update. Fields mirror memory.ProposeRequest 1:1 — the wrapper exists so the SDK emits jsonschema descriptions that show up in the tool catalog.
type ProposeUpdateOutput ¶
type ProposeUpdateOutput struct {
Status string `json:"status" jsonschema:"applied | staged | rejected"`
Reason string `json:"reason,omitempty" jsonschema:"on rejection: stable reason code (invalid_intent, secret_detected, ...)"`
Message string `json:"message,omitempty" jsonschema:"human-readable detail to accompany the reason code"`
Routing memory.Routing `json:"routing,omitempty" jsonschema:"resolved approval routing for traceability"`
StagingID string `json:"staging_id,omitempty" jsonschema:"on staged: directory name under .agent-memory/staging/"`
Files []string `json:"files,omitempty" jsonschema:"forward-slash relative paths the proposal touched"`
Findings []memory.Finding `json:"findings,omitempty" jsonschema:"on secret_detected: per-finding type + line"`
Violations []schema.SectionViolation `json:"violations,omitempty" jsonschema:"on validation_failed: per-section schema violations"`
ProvenanceViolations []string `json:"provenance_violations,omitempty" jsonschema:"on provenance_violation: list of violation strings"`
// Applied output (design §15.2).
AppliedAt string `json:"applied_at,omitempty" jsonschema:"on applied: RFC3339 UTC write time"`
AffectedSections []memory.AffectedSection `json:"affected_sections,omitempty" jsonschema:"on applied: (file, section_id) pairs touched"`
IndexUpdated bool `json:"index_updated,omitempty" jsonschema:"on applied: whether the FTS index was refreshed"`
Warnings []string `json:"warnings,omitempty" jsonschema:"on applied: non-fatal advisories"`
// Staged output (design §15.2).
StagingTTLSeconds int `json:"staging_ttl_seconds,omitempty" jsonschema:"on staged: seconds until the proposal expires"`
HumanApprovalRequired bool `json:"human_approval_required,omitempty" jsonschema:"on staged: always true — a human must review"`
ReviewCommand string `json:"review_command,omitempty" jsonschema:"on staged: CLI command to inspect the proposal"`
}
ProposeUpdateOutput is the JSON shape memory.propose_update returns. Mirrors memory.ProposeResponse; same wrapping rationale as the input.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a thin wrapper over mcp.Server that knows about the agent-memory repo root. Tools registered on it read the root each time a call comes in, so the user can edit .agent-memory/ files between invocations without restarting the server.
func New ¶
New constructs a Server but does not start it. Call RegisterTools then Run.
The logger is built to STDERR deliberately: this process speaks JSON-RPC over stdout, so a log line on stdout would corrupt the protocol. Level is quiet by default (WARN) and opt-in via $AGENT_MEMORY_LOG. The logger is threaded into the write/read deps so the memory layer's structured logs (propose outcomes, fetch summaries) land on stderr without ever touching the JSON-RPC channel.
func (*Server) RegisterTools ¶
RegisterTools attaches the agent-facing tools to the server: the full three-tool surface from design §15 — memory.fetch_context (M2), memory.propose_update (M3 T3.9), and memory.status (M3 batch 4).
type StatusInput ¶
type StatusInput struct{}
StatusInput is the (empty) input shape for memory.status. The tool takes no parameters today; the struct exists so the SDK can advertise a JSON schema. A future revision might add an `include` filter.
type StatusOutput ¶
type StatusOutput struct {
MemoryVersion string `json:"memory_version" jsonschema:"the agent-memory binary version"`
Repo string `json:"repo" jsonschema:"project name from the manifest"`
ActiveBranch string `json:"active_branch,omitempty" jsonschema:"current git branch, empty outside a repo"`
DurableFiles int `json:"durable_files" jsonschema:"count of long-lived git-tracked memory files"`
ArchiveFiles int `json:"archive_files" jsonschema:"count of files under archive/"`
LocalSessions int `json:"local_sessions" jsonschema:"count of session-log files under sessions/"`
LocalCurrentFiles int `json:"local_current_files" jsonschema:"count of branch-local current.*.md files"`
OrphanLocalFiles []string `json:"orphan_local_files,omitempty" jsonschema:"local current files whose branch no longer exists"`
IndexSizeBytes int64 `json:"index_size_bytes" jsonschema:"size of the FTS5 shadow index on disk"`
CurrentSizeBytes int64 `json:"current_size_bytes" jsonschema:"combined size of the active branch + shared current files"`
StagedUpdates []memory.StagedStatusEntry `json:"staged_updates,omitempty" jsonschema:"pending staged proposals with age, TTL, and drift status"`
StaleNotes []string `json:"stale_notes,omitempty" jsonschema:"files flagged stale by freshness tracking (future)"`
Security memory.MemoryStatusSecurity `json:"security" jsonschema:"secret-scan + provenance posture"`
Git memory.MemoryStatusGit `json:"git" jsonschema:"git integration flags"`
Lock memory.MemoryStatusLock `json:"lock" jsonschema:"advisory-lock state"`
}
StatusOutput is the JSON shape memory.status returns. It mirrors memory.MemoryStatus (design §15.11) field-for-field; the jsonschema tags document each block for the tool catalog.
Source Files