Set Up Code Intelligence

Code Intelligence (MCI) builds a semantic map of your codebase — every function, class, and route, who calls them, and what breaks if you change them. Once indexed, Lyra, Vega, Sirius, and your own agents can search code by meaning rather than text pattern.

Prerequisites

• Node.js 22 or later
• A Momental API key (Authentication guide)
• A git repository (TypeScript, JavaScript, Python, Go, or Swift)

Step 1 — Install the CLI

npm install -g @momentalos/cli

Verify:

momental-indexer --version

Step 2 — Run the initial index

cd /path/to/your-repo

momental-indexer \
  --dir . \
  --api-key mmt_YOUR_KEY \
  --name my-repo

This command:

• Registers my-repo in your Momental workspace
• Scans all source files and extracts symbols (functions, classes, types, routes)
• Builds the call graph (who calls what)
• Enables semantic search across all symbols
• Uploads everything to Momental

You'll see progress as files are processed:

[indexer] Scanning 847 files...
[indexer] Extracted 12,340 symbols
[indexer] Building call graph...
[indexer] Uploading batch 1/13...
[indexer] Done. Repo ID: repo_abc123

Step 3 — Enable advanced features (optional)

Call graph (TypeScript/JavaScript)

momental-indexer --dir . --api-key mmt_YOUR_KEY --name my-repo \
  --ts-calls

Traces which functions call which others. Powers blast radius analysis — before changing a function, see every caller that could be affected.

Test mapping

momental-indexer --dir . --api-key mmt_YOUR_KEY --name my-repo \
  --ts-calls --ts-tests

Maps source files to their test files. When Vega or Sirius modifies a file, they know exactly which tests to run.

Co-change intelligence

momental-indexer --dir . --api-key mmt_YOUR_KEY --name my-repo \
  --ts-calls --ts-tests --git-cochange

Analyzes git history to surface files that tend to change together. If you edit auth.service.ts, and it historically co-changes with session.middleware.ts, you'll be reminded to check both.

Step 4 — Enable semantic search

Embeddings are not auto-generated by the indexer. Until you compute them, code_search action:search falls back to BM25 and the response includes degraded: true. Trigger generation explicitly:

code_manage({ action: "embed", repoId: "<id-from-step-2>" })

Allow ~1 minute per ~1,000 symbols. Check progress without re-generating with code_manage({ action: "embed", repoId, statusOnly: true }).

Step 5 — Run your first search

From Claude Code or any MCP client:

// Semantic search — finds by meaning, not just text
const results = await code_search({
  action: "search",
  query: "user authentication and token refresh",
  repoId: "repo_abc123"
});

// results[0] =>
// {
//   name: "refreshAccessToken",
//   filePath: "src/services/auth.service.ts",
//   docstring: "Refreshes the user's JWT...",
//   callers: [...],
//   callees: [...]
// }

// Exact symbol lookup — fast, no embeddings
const symbol = await code_search({
  action: "find",
  name: "createUser",
  repoId: "repo_abc123"
});

Step 6 — Keep the index current

Incremental reindex (every commit)

The fastest way to keep the graph current. --incremental-files accepts either a comma-separated list or - to read newline-separated paths from stdin. Behind the scenes this calls code_manage action:update_files — a per-file delete-then-insert that preserves co-change pairs and embeddings for files you didn't touch.

# Stdin (typical CI / git-hook):
git diff --name-only HEAD~1 HEAD | \
  momental-indexer \
    --dir . \
    --repo-id <repo-id-from-step-2> \
    --incremental-files - \
    --git-sha "$(git rev-parse HEAD)"

# Or explicit list:
momental-indexer \
  --dir . \
  --repo-id <repo-id> \
  --incremental-files src/auth.ts,src/billing.ts

--repo-id is required for incremental — it's how the indexer skips registration and targets the existing graph.

UI-triggered reindex (--watch mode)

Long-running developer machine or CI box that should pick up "Reindex" button presses from the Momental UI. Polls code_manage action:check_pending on the given interval and runs a full index when a request appears. Not a filesystem watcher.

momental-indexer \
  --dir . \
  --repo-id <repo-id> \
  --watch 30   # poll interval in seconds

--watch requires --repo-id.

Full re-index (weekly or after large refactors)

Re-run the Step 2 command. code_manage action:submit_index is an atomic full replacement of all symbols + edges for the repo.

Step 7 — Auto-index from Claude Code (hands-off)

If you use Claude Code, you don't need to run momental-indexer by hand at all. Add these hooks to your project's .claude/settings.json once and Claude Code keeps the index fresh on its own — a full index when a session starts, and an incremental re-index after every edit. Both run in the background so they never block you, and both no-op silently when the CLI isn't installed.

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "command -v momental-indexer >/dev/null && momental-indexer --dir . --ts-calls --git-cochange --api-key \"$MOMENTAL_API_KEY\" >/dev/null 2>&1 &" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          { "type": "command", "command": "command -v momental-indexer >/dev/null && git diff --name-only HEAD | momental-indexer --dir . --incremental-files - --api-key \"$MOMENTAL_API_KEY\" >/dev/null 2>&1 &" }
        ]
      }
    ]
  }
}

Prereqs: install the CLI once (npm install -g @momentalos/cli) and export your key so the hook can read it (export MOMENTAL_API_KEY=mmt_xxx in your shell profile). After the first SessionStart index, semantic search is ready — no manual step. The manual commands above still work for non–Claude-Code tools, CI pipelines, or a one-off rebuild.

Key MCI Tools

Once indexed, these tools are available via MCP:

// Declare files before editing
await code_manage({
  action: "claim",
  repoId: "repo_abc123",
  filePaths: ["src/services/auth.service.ts"],
  taskId: "task_uuid"
});
// If a peer agent has claimed these files, you'll see:
// { conflicts: [{ agentName: "Sirius", filePaths: [...] }] }