Ecosystem

codemap is the structural-intelligence hub of a local, XDG-stored toolchain: it feeds the call/test graph to its siblings and fetches meaning, runtime, and secrets back, over each tool's CLI --json (one hop, never MCP→MCP). Two integrations are live: vecgrep (meaning) and tinyvault (secrets).

codemap ⇄ vecgrep

codemap composes with vecgrep, a sibling local-first semantic code-search tool. Their vector stores and embedding profiles are independent. The integration exchanges source selectors (file, start_line, fqn, kind) and versioned CLI results; it does not require a shared embedding model.

The boundary: codemap owns structure (the resolved call/type/test graph + a durable, symbol-pinned annotation layer); vecgrep owns meaning (chunk-level semantic search) and a cross-project agent-memory store. They talk over each other's CLI (--json), one hop deep — neither calls the other's MCP server.

Enabling it

To make Vecgrep the semantic owner, add this to your Codemap configuration:

semantic:
  backend: vecgrep
vecgrep:
  enabled: true

Codemap indexes structure and delegates semantic retrieval to Vecgrep. Without this setting, the default fallback backend prefers local embeddings and tries Vecgrep when local vectors are absent. To point at a specific binary:

vecgrep:
  enabled: true     # default
  bin: /usr/local/bin/vecgrep

or CODEMAP_VECGREP_ENABLED=false / CODEMAP_VECGREP_BIN=…. Every integrated call degrades gracefully when vecgrep is absent, disabled, or hasn't indexed the project.

OpenAI embeddings in Vecgrep

Configure the complete profile together in Vecgrep's global defaults:

vecgrep config set --global embedding.provider openai
vecgrep config set --global embedding.model text-embedding-3-small
vecgrep config set --global embedding.dimensions 1536
vecgrep config show

The process running Vecgrep needs OPENAI_API_KEY or VECGREP_OPENAI_API_KEY. Project configuration takes priority over global defaults: remove local provider/model/dimensions overrides if they still select Nomic. Rebuild existing indexes with vecgrep index --full after changing the embedding profile and restart existing MCP processes so they load the new configuration. OpenAI receives the source chunks sent for embedding.

Vecgrep's cross-project memory uses a separate Ollama-backed store. Selecting OpenAI for code indexing does not migrate memory or change its provider.

What flows where

codemap fetches meaning from vecgrep:

• Semantic search with no local embeddings. If a project is structure-only in codemap (indexed with --no-embed, or before Ollama was available) but embedded in vecgrep, codemap semantic delegates to vecgrep search and maps each hit back onto the graph — so you get meaning-ranked results carrying codemap's FQN/kind/signature, with no codemap embedding pass. The result is marked mode: "vecgrep".
• Agent memory in context. codemap context <symbol> surfaces relevant notes recalled from vecgrep's global agent-memory store, scoped to this project (see project_key below). They appear as a transient memories list — distinct from codemap's own durable annotations.

codemap feeds structure to vecgrep (implemented on the vecgrep side): vecgrep_related_files uses codemap's real call/test graph instead of import-text heuristics; vecgrep re-ranks its semantic hits by codemap's structural component — hub fan-in dominant, plus a minority learning-from-use term from the query_frequency counters that hotspots --json exposes (how many past searches surfaced each symbol, tracked per symbol name so they survive reindex); it pins search relevance back as codemap annotations (source: vecgrep); and vecgrep_status reports the codemap graph alongside its own index, including the per-file freshness delta (changed_files/new_files/deleted_files) from codemap structural-manifest --json. vecgrep can also shell codemap inconsistencies --json to learn where the structural knowledge contradicts itself (dangling annotations, name edges on precise-resolved files, coverage without nodes).

project_key — leak-free memory scoping

vecgrep's agent memory is a single global store. To recall only this project's notes without leaking across projects, memories are tagged ['codemap', <project_key>], where <project_key> is a stable, collision-resistant id codemap derives (git-rooted RepoHash). codemap is the single authority for the key — it's reported by codemap status --json (project_key) and the codemap_status MCP tool. A tool or agent writing a codemap-scoped memory uses that exact value rather than re-deriving it, and recall matches on the exact tag set, so a wrong or absent key returns nothing (it fails closed).

# write a codemap-scoped memory (the key comes from codemap, not re-derived)
KEY=$(codemap status --json | jq -r .project_key)
vecgrep memory remember "ValidateToken is a hot path; refactor pending" --tags "codemap,$KEY" --importance 0.8

# …and it surfaces, scoped to this project, on:
codemap context ValidateToken

codemap ⇄ tinyvault

codemap pairs with tinyvault (tvault), a local secret manager, to answer "what code breaks if I rotate this secret?" — without either tool crossing into the other's domain. tinyvault is the value-free key-name authority (it never knows where a key is used); codemap is the code-location + blast-radius authority (it has no notion of secrets). Only key NAMES cross the seam — secret values never enter codemap, so a rotation report is safe to paste into a PR, ticket, or LLM context.

codemap secret-impact — for each secret key name, codemap scans its indexed source for the key's usages (os.Getenv("KEY"), os.environ["KEY"], process.env.KEY), resolves each to the enclosing symbol, and unions the transitive callers + covering tests:

codemap secret-impact STRIPE_KEY DATABASE_URL          # explicit key names (value-blind, no tvault needed)
codemap secret-impact --via-vault payments --prefix STRIPE_   # fetch the names from tvault (value-free)

Each key reports used_by (the reading symbols), blast_radius, covering_tests, and untested (a loud warning that you're about to rotate a key no test reaches). orphan_keys lists keys with no code usages (verify before treating as dead — dynamically-constructed names like os.Getenv(prefix+x) are invisible to a literal scan). The result is candidate usage + impact, not an authoritative gate: a name-based index over-counts (precise:false — reindex --precise for exact figures), and the scan finds string literals (Go is exact via go/scanner; comments are excluded, but a name in an unrelated string equality can still appear).

codemap required-keys <entrypoint> derives the least-privilege key set: which candidate keys the entrypoint's transitive call tree actually reads. Pipe it to seal/inject only what a code path needs:

codemap required-keys Checkout --via-vault payments | xargs -I{} tvault seal --key {}

codemap index --via-vault <project> runs indexing inside tvault run -p <project> so the language servers (gopls/pyright/typescript-language-server) inherit the project's private-registry creds (GOPRIVATE/NPM_TOKEN/…) when resolving private dependencies during the precise pass. codemap only ever invokes tvault run/list — never tvault get — so secret values are unreachable. Degrades to a normal index when tvault is absent.