ekkOS_docs
API Reference

MCP Tools

Complete reference for all ekkOS MCP tools available to AI agents.

These tools are available when you connect an AI agent (Claude Code, Cursor) to ekkOS via MCP. They appear in the agent's tool list with the prefix mcp__ekkos-memory__.

Available Tools

ekko

Search your memory substrate for patterns, solutions, and context.

Parameters

querystringrequiredWhat to search for in your memory
limitnumberMax results to return (default: 10)

Returns

Array of matching memories with relevance scores and source metadata.

Example Prompt

"Search my memory for how we handled authentication"
crystallize

Save important decisions and patterns permanently to memory.

Parameters

titlestringrequiredClear, descriptive title
problemstringrequiredWhat problem does this solve?
solutionstringrequiredThe solution/pattern/approach that works
tagsstring[]Tags for categorization
works_whenstring[]Conditions when this pattern applies
anti_patternsstring[]What NOT to do

Returns

Confirmation with pattern ID.

Example Prompt

"Remember that we always use Supabase for authentication"
reflex

Validate AI suggestions against your established patterns. The Hallucination Firewall.

Parameters

requeststringrequiredYour original question/request
proposed_answerstringrequiredThe AI's proposed response or code
user_idstringOptional user ID for personalized checking

Returns

GROUNDED (safe), SPECULATIVE (no evidence), or CONFLICT (contradicts history) with explanation.

Example Prompt

"Before implementing this, check if it aligns with our patterns"
forge_insight

Create new patterns from learnings. The creation side of the Golden Loop.

Parameters

titlestringrequiredClear, descriptive title
problemstringrequiredWhat problem does this solve?
solutionstringrequiredThe solution that works
sourcestringWhere this insight came from
tagsstring[]Categorization tags
works_whenstring[]When this pattern applies
anti_patternsstring[]Common mistakes to avoid

Returns

Pattern ID and confirmation.

Example Prompt

"Forge pattern: RLS requires service role for admin operations"
trace

Explain why a suggestion was made. Show provenance of retrieved memories.

Parameters

retrieval_idstringrequiredRetrieval ID from an ekko search
memory_idsstring[]Specific memory IDs to trace

Returns

Detailed provenance with relevance scores and source information.

Example Prompt

"Show me which memories influenced this suggestion"
get_directives

Get current MUST/NEVER/PREFER/AVOID behavioral rules.

Parameters

userIdstringUser ID (default: "system")
windowHoursnumberHours of recent signals to include (default: 72)

Returns

Active directives with priorities.

Example Prompt

"What rules should I follow for this project?"
search_memory

Search across all memory layers with configurable sources.

Parameters

querystringrequiredSearch query
limitnumberMax results (default: 10)
sourcesstring[]Which memory sources to search: patterns, graph, signals, all

Returns

Search results with retrieval_id for outcome tracking.

Example Prompt

"Search memory for database connection patterns"
recall_conversations

Search past conversations semantically. Automatic memory recall.

Parameters

querystringrequiredWhat to search for
knumberHow many results to return (default: 3)
thresholdnumberMinimum similarity threshold 0-1 (default: 0.35)

Returns

Relevant conversation excerpts.

Example Prompt

"What did we discuss about the API design yesterday?"
track_memory_application

Track when memories are applied (Phase 2 of MCP lifecycle).

Parameters

retrieval_idstringrequiredRetrieval ID from search_memory
memory_idsstring[]requiredArray of memory IDs that were actually used
model_usedstringLLM model that applied the patterns

Returns

Application ID for later outcome recording.

Example Prompt

Called after using retrieved memories to solve a problem.
record_memory_outcome

Record the outcome of applied memories (Phase 3 of MCP lifecycle).

Parameters

application_idstringrequiredApplication ID from track_memory_application
successbooleanrequiredWhether the applied memories were helpful
metricsobjectOptional metrics: helpful, time_saved, user_rating

Returns

Confirmation. Triggers confidence score evolution.

Example Prompt

Called after determining if the retrieved patterns helped.

Related

REST API

HTTP endpoints for direct integration

View API

MCP Setup

How to connect these tools

Setup guide