MCP Server

Kiro Memory exposes 10 tools through the Model Context Protocol (MCP). These tools allow AI coding assistants to search, store, and retrieve memory programmatically during a session.

Starting the MCP Server

The MCP server starts automatically when invoked by your editor. You can also run it manually:

kiro-memory mcp

This starts the MCP server using stdio transport, which is the standard for editor integrations.

Tools Reference

search

Full-text search across observations and summaries using SQLite FTS5.

Parameters:

Parameter	Type	Required	Default	Description
query	string	Yes	--	Text to search for
project	string	No	auto	Filter by project name
type	string	No	all	Filter by observation type
limit	number	No	20	Maximum results to return

Observation types: file-write, command, research, tool-use, constraint, decision, heuristic, rejected

Returns: Markdown-formatted table with ID, type, title, and date for each match.

Example usage by an AI assistant:

I'll search your memory for previous work on authentication.
→ search({ query: "authentication", type: "file-write", limit: 10 })

---

semantic_search

Vector similarity search using local embeddings. Finds observations by meaning rather than exact keywords.

Parameters:

Parameter	Type	Required	Default	Description
query	string	Yes	--	Natural language query
project	string	No	auto	Filter by project name
limit	number	No	10	Maximum results to return

Returns: Ranked results with similarity scores and source information.

Example:

→ semantic_search({ query: "how to handle API rate limiting", limit: 5 })

info

Semantic search uses a hybrid approach combining vector similarity with keyword matching for the best results. Embeddings are generated locally -- no API keys required.

---

timeline

Show chronological context around a specific observation. Useful for understanding the sequence of events before and after a particular action.

Parameters:

Parameter	Type	Required	Default	Description
anchor	number	Yes	--	Observation ID as the reference point
depth_before	number	No	5	Number of observations before the anchor
depth_after	number	No	5	Number of observations after the anchor

Returns: Chronological list of observations with the anchor observation marked. Each entry includes timestamp, type, title, and content.

Example:

→ timeline({ anchor: 42, depth_before: 3, depth_after: 3 })

---

get_observations

Retrieve full details of specific observations by their IDs. Typically used after a search to get complete content for relevant results.

Parameters:

Parameter	Type	Required	Description
ids	number[]	Yes	Array of observation IDs to retrieve

Returns: Detailed markdown for each observation including:

• Type and project
• Creation date
• Full content and narrative
• Associated concepts (tags)
• Related file paths

Example:

→ get_observations({ ids: [12, 45, 67] })

---

get_context

Retrieve recent context for a project: observations, summaries, and recent prompts. This is the primary tool for context injection at session start.

Parameters:

Parameter	Type	Required	Description
project	string	Yes	Project name

Returns: Formatted context including:

• Recent summaries (session-level learnings)
• Recent observations (up to 10, with type, title, and timestamp)

Example:

→ get_context({ project: "my-app" })

tip

This tool is called automatically at session start by the hooks/rules system. You typically do not need to call it manually.

---

store_observation

Add a new observation to memory. Used by hooks to automatically capture file writes, commands, and research during a session.

Parameters:

Parameter	Type	Required	Description
type	string	Yes	Observation type: file-write, command, research, tool-use, constraint, decision, heuristic, rejected
title	string	Yes	Short descriptive title
content	string	Yes	Detailed content
concepts	string[]	No	Related tags/concepts
files	string[]	No	Related file paths

Returns: Confirmation with the assigned observation ID.

Example:

→ store_observation({
    type: "decision",
    title: "Use Zod for validation",
    content: "Chose Zod over Yup for schema validation due to TypeScript-first design",
    concepts: ["validation", "typescript"],
    files: ["src/schemas/user.ts"]
  })

---

store_summary

Store a session summary capturing what was learned and accomplished. Automatically called by the Stop hook when a session ends.

Parameters:

Parameter	Type	Required	Description
request	string	Yes	What was requested/attempted
learned	string	No	Key insights discovered
completed	string[]	No	List of completed tasks
nextSteps	string[]	No	Recommended follow-up actions

Returns: Confirmation with the assigned summary ID.

---

store_knowledge

Store structured knowledge as a first-class item. Knowledge persists independently of sessions and represents architectural decisions, constraints, and guidelines.

Parameters:

Parameter	Type	Required	Description
knowledge_type	string	Yes	constraint, decision, heuristic, or rejected
title	string	Yes	Short descriptive title
content	string	Yes	Detailed explanation
project	string	Yes	Project name
severity	string	No	For constraints: hard or soft
alternatives	string[]	No	Alternative options considered
reason	string	No	Why this was chosen or rejected
context	string	No	When this applies (for heuristics)
confidence	string	No	high, medium, or low (for heuristics)
concepts	string[]	No	Related tags
files	string[]	No	Related file paths

Returns: Confirmation with the assigned knowledge ID.

Example:

→ store_knowledge({
    knowledge_type: "constraint",
    title: "No external fonts",
    content: "Must use system fonts only for GDPR compliance and performance",
    project: "my-app",
    severity: "hard",
    concepts: ["gdpr", "performance", "fonts"]
  })

---

resume_session

Resume a previous coding session by retrieving checkpoint data including task description, progress, next steps, and relevant files.

Parameters:

Parameter	Type	Required	Default	Description
project	string	No	auto	Project name (auto-detected from environment)
session_id	number	No	latest	Specific session ID (uses latest checkpoint if omitted)

Returns: Formatted checkpoint data:

• Task description
• Progress summary
• Next steps as a checklist
• Open questions
• List of relevant files

Example:

→ resume_session({ project: "my-app" })

---

generate_report

Generate an activity report summarizing development work over a time period.

Parameters:

Parameter	Type	Required	Default	Description
project	string	No	auto	Project name (auto-detected)
period	string	No	weekly	Report period: weekly or monthly

Returns: Markdown report including:

• Overview (observation count, session count, time span)
• Session summaries
• Key learnings
• Completed tasks
• Next steps
• Top 10 file hotspots

---

Editor-Specific MCP Configuration

Claude Code

Claude Code discovers MCP servers through its configuration. The kiro-memory install --claude-code command registers the server automatically.

Manual configuration in .claude/mcp.json:

{
  "mcpServers": {
    "kiro-memory": {
      "command": "kiro-memory",
      "args": ["mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "kiro-memory": {
      "command": "kiro-memory",
      "args": ["mcp"],
      "env": {}
    }
  }
}

After adding the configuration, restart Cursor for the MCP server to be detected.

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "kiro-memory": {
      "command": "kiro-memory",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Cline

Add to your Cline MCP settings (accessible via the Cline extension settings in VS Code):

{
  "mcpServers": {
    "kiro-memory": {
      "command": "kiro-memory",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Generic MCP Client

Any client implementing the MCP specification can connect to Kiro Memory. The server uses stdio transport and expects to be invoked as:

kiro-memory mcp

The server advertises all 10 tools with their schemas upon connection via the standard MCP tools/list method.