150+ MCP Tools — cc-soul

Core Memory 14 tools ▾

rememberStore text in memory with optional tags, type, realm, and visibility level

recallSearch memory by semantic similarity with optional tag and realm filters

recall_temporalSearch memories within a time window with optional semantic filtering

smart_recallIntelligent recall — classifies query intent and routes to optimal retrieval method

list_aspectsShow available semantic aspects (preferences, corrections, insights, etc.)

list_by_aspectFilter memories by semantic category (aspect)

growAdd wisdom, belief, failure, aspiration, or dream with structured metadata

getGet a node by ID — returns full content, confidence, tags, and metadata

updateUpdate the content of an existing memory node

forgetRemove a memory permanently by its ID

batch_forgetDelete multiple nodes by ID array or search pattern (batch deletion)

strengthenIncrease confidence of a memory (default +0.1). Hebbian reinforcement.

weakenDecrease confidence of a memory (default −0.1). Intentional forgetting.

tagAdd or remove tags from a node for categorical filtering

Graph & Triplets 3 tools ▾

connectCreate a subject → predicate → object triplet relationship

queryQuery triplets with flexible subject/predicate/object filters

query_graphQuery triplets by subject or object — convenience wrapper

Hook Integration 2 tools ▾

observeStore an observation/learning — used by hooks for [LEARN] extraction

full_resonateSemantic search with full context for hooks — supports realm filtering and kind exclusion

Context & Status 4 tools ▾

soul_contextGet current soul state — memory count, confidence distribution, realm info, uptime

health_checkCheck daemon health and readiness

version_checkGet daemon version information

pending_embed_idsInspect or purge the stuck embed queue — supports purge_orphans and force_clear modes

Code Intelligence 17 tools ▾

extract_symbolsExtract symbols (functions, classes, methods) from a source file using tree-sitter

learn_codebaseIndex an entire codebase — extract symbols, relationships, and call graphs

find_symbolSearch for symbols by name with optional kind filter (function, class, method)

read_symbolRead actual source code for a symbol by name or ID — avoids full file reads

read_functionRead source code of a function/method by name — convenience wrapper

symbol_callersFind all symbols that call the given symbol (reverse call graph)

symbol_calleesFind all symbols that the given symbol calls (forward call graph)

type_hierarchyGet type hierarchy — base classes, interfaces, ancestors, and descendants

file_importsGet all imports/includes for a source file

file_dependentsGet all files that import/include the given module

resolve_callsitesResolve callsites to symbols and populate call edge table

describe_symbolSet semantic description for a code symbol (stored in symbol table)

embed_symbolsFast embed symbol metadata without LLM — batch processing at ~100 symbols/sec

dedupe_symbolsRemove duplicate symbols from the database

codebase_overviewGet full indexed codebase structure: files, classes, functions, relationships (tree/flat/JSON)

clear_codebaseRemove all code intelligence data (symbols, triplets) for a project

clear_tripletsDelete triplets by subject pattern (e.g., ‘%.cpp’ for all C++ file triplets)

Code Wisdom & Context 6 tools ▾

smart_contextBuild intelligent context combining memories, code symbols, and graph relationships for a task

code_contextGet code context summary — optionally scoped to a file path

cleanup_code_wisdomMigration tool: delete [code] wisdom memories and clear orphaned symbol references

search_symbolsSemantic search for code symbols by natural language query using embeddings

enrichment_statusGet code enrichment progress (semantic descriptions for symbols)

subconscious_statsGet subconscious background processor statistics

Context Management 1 tool ▾

compact_contextMemory-aware context compaction — drops conversation turns already covered by soul memories, scores survivors by recency and semantic relevance to next task

Unlike token-budget truncation or generic compaction (e.g. Morph Compact), chitta scores each conversation turn against what it already knows. A turn whose content is already distilled into a memory can be dropped without information loss — the knowledge lives in the graph. Turns with novel content are preserved.

Hook integration: wire compact_context into your UserPromptSubmit hook to auto-compact before each turn when the session is long. Pass the user’s message as query so the scoring biases toward what is relevant next, not just what was relevant historically.

score(msg) = weight × (0.3 · recency + 0.4 · semantic_sim + 0.3 · (1 − memory_coverage))
// high memory_coverage → already learned → safe to drop

live demo

before: — after: — dropped: —

Realms 7 tools ▾

realm_listList all known realms with memory counts

realm_getGet the realm assignment for a specific memory

realm_setSet the primary realm for a memory

realm_addAdd a memory to an additional realm (multi-realm membership)

realm_removeRemove a memory from a realm

realm_visibilitySet visibility level — private, shared, or global

realm_detectDetect current realm from environment, .cc-soul-realm file, or git repository

Session Continuity 6 tools ▾

ledger_saveSave session checkpoint — todos, decisions, blockers, mood, active files, discoveries

ledger_loadLoad most recent checkpoint for a session or project

ledger_listList recent checkpoints with optional project filter

ledger_getGet a specific checkpoint by ID

ledger_deleteDelete a checkpoint by ID

checkpointSave session state — uses active long task if exists, otherwise standalone ledger

Cross-Session Messaging 7 tools ▾

session_registerRegister a Claude session in the cross-session registry with realm and PID

session_syncReconcile registry with running processes — marks dead sessions

session_listList all registered sessions with status, realm, and last heartbeat

msg_sendSend message to session UUID, realm name, or "*" for broadcast

msg_inboxCheck unread messages for the current session

msg_ack_allAcknowledge (mark as read) all messages for a session

msg_historyView sent and received message history

Narrative (Work Modes) 3 tools ▾

narrative_statusGet current work mode, confidence, and segment summary for the session

narrative_logManually append an event to the session event log

narrative_historyGet history of work mode segments for a session

Transcript & Distillation 8 tools ▾

transcript_registerRegister a transcript JSONL file for distillation tracking

transcript_getGet processing state for a registered transcript

transcript_listList all registered transcripts with processing status

transcript_updateUpdate transcript processing progress (last processed line)

transcript_removeRemove a transcript from tracking

transcript_parseParse new turns from a transcript JSONL file

distill_statusGet distillation system status — transcripts, realms, pending work

epiplexity_checkCompute epiplexity (ε) score — measures reconstruction quality of compressed seeds

Theme Memory 6 tools ▾

theme_listList all themes with stats — hierarchical memory organization

theme_getGet theme details with representative memories

theme_recallTwo-stage retrieval: match theme representatives, then expand to full memories

theme_statsGet theme organization statistics for a realm

theme_maintainForce theme maintenance — split large themes, merge similar, reassign orphans

theme_assign_orphansAssign orphan memories to themes in batches

Memory Quality & Introspection 4 tools ▾

what_do_i_know_aboutIntrospect what cc-soul believes about a topic — returns claims with provenance, staleness verdict, and contradiction flags

cross_harness_conflictsFind memories where claude-code and codex harnesses disagree on the same topic, ranked by disagreement score

write_gate_statsShow staged memory count and oldest staged memory age (write-gate admission stats)

mark_memory_invalidatedMark a memory as invalidated by a commit hash or symbol-change ID, setting invalidated_by on MemoryState

Hygiene & Calibration 5 tools ▾

hygiene_statsGet memory health — confidence distribution, growth rate, stale memory count

hygiene_runRun memory hygiene: decay, prune low-confidence, consolidate similar memories

calibration_recordRecord a prediction outcome (success/failure) for a domain

calibration_scoreGet calibration accuracy for a domain

episode_cluster_statusGet episode clustering statistics for auto-distillation

Maintenance 2 tools ▾

cycleRun full maintenance cycle — decay, cleanup, consolidation

cleanupRemove weak/garbage nodes (dry-run by default)

Import / Export 2 tools ▾

import_soulImport a .soul file in SSL format — from file path or inline content

export_soulExport memories to SSL format with optional tag filter and limit

Background Processing 3 tools ▾

background_statusGet background processing and embedding scheduler status

background_scheduleSchedule a background task with type and optional JSON parameters

background_run_cycleRun one cycle of background processing — processes pending tasks

Learning & Tracking 6 tools ▾

learn_correctionStore when I was wrong — creates high-confidence counter-memory with ‘corrects’ triplet

learn_preferenceStore user preference with global visibility across all projects

learn_insightStore generalizable insight that applies across projects (patterns, techniques, wisdom)

learn_approachStore what approach worked in a particular state (stuck, debugging, flowing, frustrated)

learn_outcomeRecord whether a suggestion/approach helped — builds feedback loop

learn_milestoneRecord relationship milestones — achievements, significant moments worth remembering

Exploration (RLM-style) 4 tools ▾

explore_recallLightweight recall — returns titles/scores only, no full content (for iterative exploration)

explore_peekGet summary of a memory (first 200 chars) without loading full content

explore_expandGet full content of a memory (use sparingly during exploration)

explore_neighborsGet nodes connected via triplets — outgoing, incoming, or both directions

Long Tasks 9 tools ▾

long_task_startStart a long-running task with goal, work items, and completion criteria

long_task_getGet a long-running task by ID with full state

long_task_activeGet the currently active long-running task for a realm

long_task_updateUpdate task progress — completed summary, work items, blockers

long_task_completeMark a long-running task as completed with outcome summary

long_task_eventAppend event to task log (tool_result, decision, observation, error, checkpoint)

long_task_snapshotGet synthesized task context for injection (inject or debug mode)

long_task_evaluateEvaluate task completion: run hard checks, return decision (complete/continue/blocked)

checkpointSave session state — uses active long task if exists, otherwise standalone ledger

Anticipation & Habits 10 tools ▾

anticipation_observeRecord a context→action pattern when an action is taken in response to a context

anticipation_predictGiven a context, predict likely actions based on learned patterns

anticipation_successMark a predicted action as successful — the prediction was correct and helpful

anticipation_listList learned anticipation patterns, ordered by frequency

anticipation_filterFilter predictions through annoyance gate based on work mode and confidence

habit_observeRecord a trigger→response pattern — each observation strengthens the habit

habit_matchFind habits that match the given context above a minimum strength threshold

habit_strengthenManually strengthen a habit (positive reinforcement)

habit_weakenWeaken a habit (negative feedback)

habit_listList formed habits, ordered by strength

User Profile 3 tools ▾

profile_getGet user profile — expertise, communication style, work patterns, preferences

profile_updateUpdate a specific profile field (expertise, style, patterns, preferences)

profile_observeRecord an observation about the user (expertise level, style, pattern, preference)

Goals 5 tools ▾

goal_setDefine a new long-term goal with optional milestones and deadline

goal_getGet details of a specific goal by ID

goal_listList goals filtered by status (active, paused, completed, abandoned) and realm

goal_progressUpdate goal progress (0–1) and optionally mark a milestone complete

goal_completeMark a goal as completed with an outcome summary

Consolidation 3 tools ▾

consolidation_scanFind similar memory pairs that could be merged (configurable similarity threshold)

consolidation_mergeMerge two similar memories (primary absorbs secondary) with optional combined content

consolidation_autoAuto-merge highly similar memories (>90% similarity) up to a configurable limit

Metacognition 3 tools ▾

metacognition_correctionsAnalyze patterns in past corrections — find recurring mistakes

metacognition_outcomesAnalyze suggestion outcomes (what worked vs failed) — find success patterns

metacognition_evaluateSelf-evaluate learning effectiveness — returns metrics and recommendations

Curiosity & Research 6 tools ▾

curiosity_note_gapRecord a knowledge gap — something I don't know or couldn't answer

curiosity_gapsList current knowledge gaps awaiting exploration

curiosity_resolveMark a gap as explored/resolved with what was learned

research_topicsGet topics that need research from gaps, weak memories, or suggestions

research_storeStore research results as memories with source attribution

research_cycleRun one curiosity-driven research cycle — returns a topic with context

Sadhana (Autonomous Agents) 12 tools ▾

sadhana_startStart an autonomous agent with a goal, model, interval, and optional goal_dsl for typed behavior

sadhana_listList sadhanas filtered by status (running, paused, done) and realm

sadhana_statusFull detail for one sadhana — goal, state, iterations, last action, history

sadhana_pausePause a running sadhana (can be resumed later)

sadhana_resumeResume a paused sadhana

sadhana_stopStop a sadhana and mark it as done

sadhana_set_goalUpdate the goal text for a sadhana

sadhana_set_intervalChange the tick interval (seconds) for a sadhana

sadhana_set_modelSwitch the model a sadhana uses (e.g. claude/sonnet, openai/gpt-4o)

sadhana_set_max_turnsSet maximum agent turns per cycle for a sadhana

sadhana_historyGet recent cycle history for a sadhana — decisions, tool calls, outcomes

sadhana_checkpointSave a checkpoint for a sadhana (state snapshot for recovery)

Dreams & Self-Improvement 7 tools ▾

dream_wanderAuto-pick a topic from memory gaps or curiosity seeds and start a dream sadhana

dream_startStart a dream exploring a specific topic — web-searches and stores [dream] memories

dream_listList recent dreams with status, topic, findings summary, and memories created

dream_statusFull detail for one dream — joined sadhana record and last cycle events

dream_force_wokeForce a stuck dream to woke status, finalizing its findings

dream_cancelCancel a dream and mark it as forgotten

impl_startStart the daily self-improvement sadhana — reads [impl] memories, implements changes, commits if review gate passes

Suggestions 4 tools ▾

suggestion_trackTrack a suggestion made for later outcome evaluation

suggestion_pendingList suggestions awaiting outcome feedback

suggestion_resolveRecord the outcome of a suggestion (did it help?)

suggestion_countCount pending suggestions awaiting feedback

Insights 2 tools ▾

insight_promotePromote a memory to global visibility so it applies across all projects

insight_globalList all global insights that apply across projects

Surprise Memory (Layer 4) 4 tools ▾

record_surpriseRecord a prediction error — what was expected vs what actually happened, with magnitude and domain

query_surprisesFilter surprise events by domain, realm, magnitude threshold, and time range

get_blind_spotsIdentify recurring surprise patterns — domains/actions where predictions consistently fail

surprise_statsSummary statistics: event counts, average magnitude, domain breakdown

Epistemic Debt (Layer 5) 6 tools ▾

register_debtRegister an epistemic uncertainty — competing hypotheses with fragility score and discriminating test

resolve_debtMark an epistemic debt as resolved with explanation

defer_debtDefer a debt for later investigation

query_debtsFilter debts by status (open/resolved/deferred), domain, realm, fragility

get_fragile_decisionsOpen debts sorted by fragility — decisions most likely to be wrong

debt_statsSummary statistics: counts by status, average fragility score

Integration Kernel (Layer 6) 4 tools ▾

record_feedbackRecord whether a recall source was useful — updates learned source weights via Bayesian feedback

get_source_weightsView learned recall source weights per domain — how much each source is trusted

update_source_weightManually override a recall source weight [0–2]

integration_statsPer-source success rates and learned weights across all domains

Autonomous Learning 9 tools ▾

surprise_learning_statsRolling surprise credit stats — tracked memories, gates passed, strength adjustments

upsert_wisdom_candidateCreate or update a wisdom candidate from clustered surprise patterns

update_wisdom_lifecycleAdvance candidate through lifecycle: candidate → provisional → trusted → demoted

query_wisdom_candidatesQuery wisdom candidates by lifecycle stage and/or domain

wisdom_promotion_statsOverview of wisdom promotion pipeline — total candidates by lifecycle stage

attach_debt_evidenceAttach supporting evidence (memory IDs + confidence) to an epistemic debt

update_scorer_modelApply learned weight deltas to the scoring model from outcome calibration

learned_scorer_statsCurrent learned scoring model — version, factor count, loss, outcome count

effective_scorer_weightsShow effective scoring weights — baseline + learned deltas for all factors

Intervention Ledger (Layer 7) 8 tools ▾

start_interventionBegin tracking an agent intervention — record intent, action type, preconditions and expected observables before execution

add_observationRecord an observation during an open intervention (stdout, test result, diff, etc.)

close_interventionClose an intervention with its final outcome status (Open=0 Succeeded=1 Failed=2 Partial=3 Aborted=4)

record_attributionAttribute a closed intervention to a causal class — routes feedback to the appropriate learning subsystem

query_interventionsQuery the intervention ledger with optional realm/session/status filters

get_interventionGet a single intervention record with its observations and attributions

intervention_statsIntervention ledger statistics — total, open, succeeded, failed, aborted counts

list_open_interventionsList all currently open (in-progress) interventions

Agent Protocol Memory (Layer 8) 10 tools ▾

register_taskRegister a task contract — goal, constraints, acceptance criteria, priority, deadline, and optional parent task

update_taskUpdate task status (Active=0, Blocked=1, Completed=2, Failed=3, Abandoned=4); optionally attach an intervention or tag

add_delegationRecord a delegation edge — which agent handed off to which, with optional handoff note

link_evidenceLink a memory to a task as typed evidence (Observation, Artifact, Result, Analysis, UserFeedback) with relevance and producer

add_probeAdd a pending probe — an open question blocking or informing task completion

resolve_probeResolve a pending probe — mark Answered (1) or Dismissed (2) with optional answer text

set_criterionUpsert a completion criterion for a task — idempotent by criterion text; mark met/unmet with evidence note

get_taskGet full task view — contract, delegations, evidence links, pending probes, and completion criteria

query_tasksQuery task contracts with optional realm, session, status, and priority filters

agent_protocol_statsAgent protocol memory statistics — total tasks, delegations, evidence links, probes, and criteria counts

Causal Episode Compiler (Phases 1–17) 26 tools ▾

log_eventLog a structured CEC event — (tool, entity, outcome) appended to EventTape and CDAWG

log_event_exLog event with extended fields — token_cost, latency_ms, retry_count for regret-shaped Q-values

log_decisionRecord a branch point — chosen symbol, rejected alternatives, and typed rejection reasons

recall_last_actionFind the most recent EventTape occurrence of a (tool, entity) pair

recall_failure_patternReturn top-k CDAWG states with high fail_ratio (≥60% failures, ≥3 occurrences)

recall_causalPMI-ranked causal antecedents — what sequences historically preceded this (tool, entity)

recall_causal_antecedentDirect PMI antecedent query with backward eligibility trace context

recall_counterfactualCDAWG sibling-edge divergence — what alternative would have had a lower fail_ratio from the same prefix

recall_true_counterfactualDecisionTape counterfactual — alternatives the agent explicitly considered and rejected

recall_motif_valueTop-k CDAWG states reachable from (tool, entity) sorted by cross-session Q-value

recall_hdcbindHDC heteroassociative binding — unbind a known role/value to infer the missing role by Hamming distance

refutation_statsCausal refutation ledger — live vs refuted Sequitur rules with support/contradict counts

hypothesis_probesTop-k rules by Wilson probe_value — most uncertain hypotheses ranked by expected information gain

executor_flushPromote shadow policies meeting lift gate, demote drifted policies, fire active policies for current context

list_policiesList CEC intervention policies — active and/or shadow, with source rule and lift metrics

consolidation_passRun Sequitur grammar induction, promote rules to triplet KG, rebuild HypothesisMarket, take Turīya sample

turiya_statusTurīya witness health vector — diagnosis, trend, Q-variance, refutation pressure, recent history

tape_statsEventTape statistics — total events, tombstoned count, compression ratio

verbalize_rulesTop-k Sequitur rules as human-readable heuristics, e.g. “Whenever edit(store.rs) fails, recall_failure_pattern tends to follow”

queue_experimentsFile deliberate micro-experiments for high-uncertainty hypotheses (probe_value > 0.4, refute_ratio < 0.3)

fep_statusFEP prior organ — obs_count, states_modeled, ewma_drift (context_drift flag), ewma_shock (emission_shock flag). Variational free energy replacing PPM surprisal in the Phase 3 write gate

routed_recallCPU-native query router — parse a typed RecallRequest (kind_filter, realm, subject, predicate, freetext, time range, causal context) into Exact/Fuzzy/Temporal/Causal/Hybrid dispatch. LLM only called when a named UnboundSlot cannot be filled deterministically

witness_memoryPromote a candidate-band memory to established on closed-loop signal: user correction, tool-result outcome, or router hit-rate delta. Open-weight-generated writes stay in candidate band until witnessed

reconcile_passRun R0 reconciler — scan all assoc_edges for MemoryKind legality violations and candidate→established laundering. Detect contradictions by (realm, 6-word prefix) grouping. Results logged to triplet KG

harvest_scopeGenerate demand-driven extraction targets from current Turīya anomalies and router misses — produces harvest_targets.json consumed by scripts/harvest_ow.py. Never bulk-ingests a static corpus

seed_hdc_geometryLoad vocab_geometry harvest JSON and seed the HDC codebook with binarized f32 directions from an open-weight embedding matrix — grounds HDC vectors in model semantics without ongoing inference cost

Debug 1 tool ▾

sql_queryRun read-only SQL SELECT query against the soul database (debug/analysis)