API Reference

API Reference

Karta can be used through:

• Rust API
• MCP server tools
• CLI/server binary

Rust Core API

Primary type: karta_core::Karta.

Common operations:

Operation	Purpose
add_note(content)	Store memory note.
add_note_with_session(content, session_id)	Store note and attach session sequence metadata.
search(query, top_k)	Return relevant memory notes.
ask(query, top_k)	Retrieve + synthesize answer.
get_note(id)	Fetch note by id.
run_dreaming(scope_type, scope_id)	Run background consolidation/inference.
get_links(note_id)	Get graph neighbors.
run_forgetting()	Archive/deprecate low-activation memories.
preview_forgetting()	Dry-run forgetting.

MCP Tools

Implemented in crates/karta-server/src/mcp.rs.

add_note

Store new memory note.

Input:

{
  "content": "User prefers short technical responses.",
  "session_id": "optional-session-id"
}

Output includes:

• id
• content
• context
• keywords
• tags
• links
• confidence
• created_at

search

Semantic/hybrid search over memories.

Input:

{
  "query": "What does user prefer?",
  "top_k": 5
}

Output list includes:

• id
• content
• context
• keywords
• confidence
• score
• tags
• created_at

ask

Retrieve memories and synthesize answer.

Input:

{
  "query": "What should I remember about this project?",
  "top_k": 5
}

Output includes:

• answer
• query_mode
• notes_used
• note_ids
• has_contradiction
• contradiction_injected

get_note

Fetch note by id.

Input:

{
  "id": "note-id"
}

note_count

Return total stored memory note count.

Input: none.

Output: plain count string.

dream

Run dream/consolidation pass. Calls Rust Karta::run_dreaming.

Input:

{
  "scope_type": "workspace",
  "scope_id": "default"
}

Output includes:

• dreams_attempted
• dreams_written
• notes_inspected
• types_produced
• total_tokens_used

get_links

Get linked memories.

Input:

{
  "note_id": "note-id"
}

Query Modes

Karta classifies queries into retrieval modes:

Mode	Use
Standard	Balanced retrieval.
Recency	Current/latest/updated queries.
Breadth	Summaries/overviews.
Computation	Compare/count/difference queries.
Temporal	Sequence/timeline/order queries.
Existence	“Did I ever / is it true / contradiction” queries.

Error Model

Errors are surfaced as typed KartaError internally and MCP errors externally. Expected failure classes:

• LLM provider/config error
• vector store error
• graph store error
• migration/schema error
• retrieval/rerank error
• malformed rule/contradiction data

Implemented MCP Tool Names

Actual MCP names from KartaService:

• add_note
• search
• ask
• get_note
• note_count
• dream
• get_links

Auth Notes

Server supports OAuth/OIDC and bearer/session auth. MCP-local usage may not need public OAuth depending deployment mode.

Do not put secrets in wiki examples. Use env placeholders only.