Code Intelligence (MCI)

A queryable semantic map of your codebase — every function, class, and route is a symbol; every call, import, and test relationship is an edge. Shared across every agent in your workspace.

What MCI is, in plain English

Your codebase is a graph — every function connects to every function that calls it, every file it imports, every test that covers it. MCI builds and maintains that graph so AI agents (and humans) can answer two questions that normally take an hour:

1. Where is the thing that does X? — by meaning, not text. Search "user signup flow" and find the right function even when it's named createInitialAccount and never uses the word "signup."
2. What breaks if I change this? — every caller, every test, every file that historically changes alongside it. Before the edit, not after the bug.

Everything else MCI does (architectural tours, cluster maps, multi-agent coordination) is downstream of that graph. Finding and impact are why it earns its keep.

The four tools

Full schemas in the MCP Tool Reference (items 27–30).

Graph model

Languages with full AST extraction: TypeScript, JavaScript, Python, Go. Swift uses regex-based same-file CALLS only.

The npm package: @momentalos/cli

The indexer and agent listener ship as one published package: @momentalos/cli. Requires Node.js 20+.

npm install -g @momentalos/cli

Or run without installing:

npx -p @momentalos/cli momental-indexer --help
npx -p @momentalos/cli momental-agent   --help

Three bins

Environment variables

API key auto-discovery (first hit wins): --api-key flag → $MOMENTAL_API_KEY → .mcp.json walked up to home → ~/.claude.json → ~/.momental/config.json.

Indexing — full vs. incremental

Indexing populates the graph for one repo. There are two paths:

• Full index wraps code_manage action:submit_index, which is an atomic full replacement of all symbols + edges for that repoId.
• Incremental reindex wraps code_manage action:update_files, which deletes stale symbols for the listed files and inserts the new ones. Co-change pairs, embeddings, and references for unchanged files are preserved.

First-time full index

momental-indexer \
  --dir . \
  --api-key mmt_YOUR_KEY \
  --name my-repo \
  --ts-calls \
  --ts-tests \
  --git-cochange \
  --git-sha "$(git rev-parse HEAD)"

Pipeline:

1. Calls code_manage action:register (or reuses --repo-id) → returns repoId.
2. Walks the source tree, respecting .gitignore and --exclude.
3. Extracts symbols via AST (TypeScript Compiler API, python3 AST, go compiler, Swift parser); falls back to enhanced regex if a runtime is missing.
4. Builds edges: IMPORTS, EXTENDS, IMPLEMENTS, plus type-aware CALLS when --ts-calls.
5. Optional: TESTS edges (--ts-tests), DI edges (--ts-di), git co-change pairs (--git-cochange), LSP references (auto-detected for TS).
6. Submits via code_manage action:submit_index — atomic full replacement.
7. Follow-ups: submit_references if LSP refs were extracted; cochange if --git-cochange ran.

After the full index lands, kick off semantic embeddings asynchronously:

# via MCP — generates embeddings for all symbols missing them
code_manage({ action: "embed", repoId })

Embedding takes ~1 minute per ~1k symbols. Until embeddings exist, code_search action:search returns degraded: true and ranks via BM25 alone.

Incremental reindex on top of an existing index

Use this after editing files — much faster than a full re-index, and preserves co-change pairs and embeddings for files you did not touch.

Stdin file list (typical CI / git-hook):

git diff --name-only HEAD~1 HEAD | \
  momental-indexer \
    --dir . \
    --repo-id <existing-repo-id> \
    --incremental-files - \
    --git-sha "$(git rev-parse HEAD)"

Explicit file list:

momental-indexer \
  --dir . \
  --repo-id <existing-repo-id> \
  --incremental-files src/auth.ts,src/billing.ts

Behind the scenes the indexer:

1. Parses only the listed files.
2. Calls code_manage action:update_files with { repoId, filePaths, symbols, edges }.
3. The handler deletes stale symbols for those files, then inserts the new ones.
4. Co-change pairs, embeddings, and references for unchanged files are untouched.

update_files is the canonical "incremental on top of existing index" entry point. submit_index, by contrast, is always a full wipe-and-replace for the repo.

Pending-reindex signal (UI-triggered reindex)

When a user clicks "Reindex" in the Momental UI (or another process wants the indexer to re-run), the request is recorded as a pending reindex on the repo row. An indexer running in --watch mode polls for those requests and runs a full index when one appears:

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

Programmatic check:

code_manage({ action: "check_pending" })
# → repos where reindexRequestedAt > lastIndexedAt

--watch requires --repo-id (the watched repo). Use this on a long-running developer machine or a CI box to keep one repo continuously up to date with UI-triggered requests.

CI integration (GitHub Actions)

Full index on main:

- name: Index codebase
  run: |
    npm install -g @momentalos/cli
    momental-indexer \
      --dir . \
      --api-key "${{ secrets.MOMENTAL_API_KEY }}" \
      --name my-repo \
      --ts-calls --ts-tests --git-cochange \
      --git-sha "$(git rev-parse HEAD)"

Incremental on PR (only changed files):

- name: Incremental MCI update
  run: |
    git diff --name-only origin/main...HEAD | \
      momental-indexer \
        --dir . \
        --repo-id "${{ secrets.MOMENTAL_REPO_ID }}" \
        --incremental-files - \
        --git-sha "$(git rev-parse HEAD)" \
        --quiet

Most-used indexer flags

Daily usage — the agent playbook

For agents and humans both, MCI replaces grep / glob / cold reads. The mandate inside Momental's own agents:

Before touching any file — search MCI first.
Before modifying any function — check its blast radius first.
Before writing any code — claim your files first.

Recommended startup sequence (every session)

1. code_manage({ action: "list" })                              # what repos are indexed
2. code_map({ action: "tour", repoId, persona: "agent" })       # for new codebases — dependency-ordered learning path
3. code_manage({ action: "claim", repoId, filePaths, taskId })  # before edits
4. code_inspect({ action: "diff_impact", repoId, filePaths })   # blast + testsToRun[] before writing
5.   ... do the work ...
6. code_inspect({ action: "tests", repoId, filePath })          # exactly the right tests, not all tests

Don't do these without MCI first

code_manage({ action: "active", repoId })
# → { activeAgents: 3, claims: [{ agentId, filePaths, ttlRemainingSeconds, isExpired }] }

npm install -g @momentalos/cli

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

git diff --name-only HEAD~1 | \
  momental-indexer \
    --repo-id <id> \
    --incremental-files -

code_search({
  action: "search",
  query: "webhook authentication"
})

code_inspect({
  action: "diff_impact",
  repoId,
  filePaths: [
    "src/routes/payments.ts",
    "src/services/billing.ts"
  ]
})

code_manage({
  action: "claim",
  repoId,
  filePaths: ["src/auth.ts"],
  taskId
})