SmartMemory
Guides

Code Indexing

SmartMemory can parse and index code repositories, turning source code into searchable knowledge graph nodes. Classes, functions, routes, tests, and their relationships become first-class entities that you can query alongside other memories.

How it works

ingest_code() performs a multi-pass analysis of your repository:

  1. File collection: walks the directory tree, collecting files by language.
  2. AST parsing: extracts code entities and relationships from each file.
  3. Cross-file resolution: builds a symbol table to resolve import bindings across modules.
  4. Graph writing: creates nodes and edges in the knowledge graph.
  5. Embedding generation: generates vector embeddings for each entity.
  6. Pattern seeding: promotes class and function names into the EntityRuler pattern set.

Basic usage

Index a repository with the CLI:

sm code index . --repo my-project

Then recall indexed code from Python with search_code():

from smartmemory.pipeline.config import PipelineConfig
from smartmemory.tools.factory import lite_context

lite = dict(pipeline_profile=PipelineConfig.lite(llm_enabled=False))

with lite_context(**lite) as memory:
    hits = memory.search_code(
        "clean up vendor billing records",
        repo="my-project",
    )

    for hit in hits:
        print(
            hit["name"],
            hit["entity_type"],
            f'{hit["file_path"]}:{hit["line_number"]}',
            hit.get("docstring", ""),
            hit["score"],
        )

search_code() returns a list of dictionaries with name, entity_type, file_path, line_number, docstring, and score. There is no sm code search command. Use the Python API for recall after indexing.

CLI parameters

ParameterDescription
PATHDirectory to index. Use . for the current repo.
--repoShort repository identifier such as "my-service".
--languageRepeatable language selector. Supports python and typescript. Defaults to Python.
--excludeRepeatable directory name to skip.
--commit-hashOverride the Git commit SHA. Pass an empty string to suppress auto-detection.

Entity types

The parser extracts five entity types from source code:

Entity typeDescriptionExample
moduleA source filesmartmemory/code/parser.py
classClass definitionclass CodeParser
functionFunction or method definitiondef parse_file(...)
routeFastAPI or Express route handler@router.get("/health")
testTest functiondef test_index_python_repo()

Each entity gets a deterministic ID in the format code::{repo}::{file_path}::{name}, making re-indexing idempotent.

Node properties

Every code entity node carries these properties:

PropertyTypeAlways presentDescription
item_idstryesDeterministic node ID
namestryesEntity name
entity_typestryesOne of module, class, function, route, test
file_pathstryesRelative path from the repository root
line_numberintyesLine number where the entity is defined
repostryesRepository identifier
memory_typestryesAlways "code"
docstringstrif presentFirst 500 characters of the entity's docstring
decoratorsstrif presentComma-separated decorator names
basesstrif presentComma-separated base class names
http_methodstrroutes onlyHTTP method such as GET or POST
http_pathstrroutes onlyRoute path such as /health
commit_hashstrif providedGit commit SHA at index time. A checkout with uncommitted or untracked changes is stamped <sha>-dirty-<fingerprint>, so it never passes for the clean commit.
indexed_atstryesISO timestamp of when the entity was indexed

Relationship edges

The indexer creates five types of edges between code entity nodes:

Edge typeMeaningExample
DEFINESA module defines a class or functionparser.py defines CodeParser
IMPORTSA file imports a symbol from another moduleindexer.py imports CodeEntity
CALLSA function calls another functionindex() calls parse_file()
INHERITSA class extends another classSqliteStore inherits BaseStore
TESTSA test function tests a specific entitytest_parse_file() tests parse_file()

Cross-file CALLS and IMPORTS edges are resolved through a two-pass symbol table that maps local import names to their target entity IDs.

Repo names and checkout identity

Each index is stored under a repo name. A name belongs to one checkout. The checkout is identified by its normalized Git remote URL, or by a hash of its absolute path when it has no remote. Two clones of the same remote count as the same repo.

If you index a different checkout under a name that already belongs to another checkout in the same workspace, the index is refused with an error that names both. The existing index is not changed. Pick a different repo name for the second checkout.

The MCP code_index tool derives the name from the Git remote when you do not pass repo_name, for example github.com/acme/api. A package inside a monorepo gets its path appended, as in github.com/acme/mono#packages/web.

Looking up one entity

GET /memory/code/context and GET /memory/code/dependencies match entity_name against the stored name or qualified name, either exactly or as the last dotted part. So run finds the method Svc.run.

When more than one entity matches, the API returns HTTP 409 with every candidate (item ID, qualified name, file and line). Repeat the call with file_path or item_id from a candidate to choose one.

Snapshot file for local tools

smartmemory code bundle parses a checkout and writes one JSON file. It does not open a memory store, does not need an account or network, and does not create embeddings. Use it when a local tool wants the code graph without running the service.

smartmemory code bundle . --repo myapp --out myapp.snapshot.json
OptionMeaning
--repoRepo name stamped on the file. Required.
--outFile to write. Required.
--languageNarrow to python or typescript. Repeatable. Default is every supported language present.
--excludeExtra directory names to skip. Repeatable.
--allow-partialWrite the file even when some files fail to parse.
--fieldsfull (default) or minimal. Minimal drops framework_evidence and the per-entity parse diagnostic when it is clean. The forge/stratum code-graph consumer (STRAT-CODEGRAPH-1) reads minimal by default, and full output is opt-in for it.

The file is written atomically, so a failed run never leaves a half-written file and never replaces an existing one. If you write the file inside the checkout and it is not git-ignored, the command prints a warning, because the next snapshot would see it as an uncommitted change. There is no option to override the commit hash.

What the file holds

  • commit_hash and source: the revision of the checkout. A dirty tree gets <HEAD>-dirty-<fingerprint>. source.repo_identity is the same checkout identity the hosted index uses.
  • entities: each has an item_id, and every relation endpoint is the item_id of an entity in the same file.
  • relations: DEFINES, IMPORTS, CALLS, INHERITS, TESTS and REFERENCES. A call site with several candidates produces one relation per candidate.
  • edge_state on every call, test and reference relation: resolved (one candidate) or ambiguous (several). A site with no candidate, whether unresolved or unsupported, is not written as a relation. It stays in call_evidence or test_evidence with its state. A resolved edge is still a name or binding match, not a proof. Read it from the file and do not recompute it.
  • call_evidence and test_evidence on an entity hold the call and test sites that are not already a relation, including every unresolved or unsupported site, so none are lost.
  • skipped_paths: files left out on purpose, each with a reason. TypeScript and JavaScript files are skipped with grammar_unavailable when the optional grammars are missing. Install them with pip install "smartmemory-core[typescript]".
  • complete: true when no file failed to parse. failed_paths lists the failures, and budget_exhausted says whether the run stopped at its entity limit.
  • source.resolution_dependencies: the files the resolvers read, such as tsconfig.json files in an extends chain and the nearest package.json of each JavaScript file. A change to one of them can change edges even when commit_hash does not change, so re-check them to decide whether a snapshot is stale. Content entries carry a sha256. Directory listing and glob entries carry members_sha256, a digest of the member files that does not depend on where the checkout lives. Adding or removing a member changes it. If a listing, glob member or subtree cannot be read, or a member resolves outside the checkout, members_sha256 is null and members_error says why. Core also logs a warning. The list covers every file the run parsed, including files that failed, were skipped by policy or were dropped by a budget.

By default the command refuses to write when any file fails to parse, and it prints the failing path. With --allow-partial it writes the files that did parse, sets complete to false, exits 0 and prints a warning that names the failed paths. Nothing from a failed file enters the entities, relations or evidence, and files that parsed with a partial result still contribute. If every file failed, the command refuses. It still refuses when the path is not a directory, when no entities were found, or when an entity path escapes the checkout.

The snapshot is not a request body for the hosted index endpoint. Hosted indexing keeps its own upload path and its 64 MiB request limit. The snapshot has no size limit.

Incremental updates

For adding or updating individual code entities without re-indexing an entire repository, use ingest_structured() with the code_entity schema:

from smartmemory.pipeline.config import PipelineConfig
from smartmemory.tools.factory import lite_context

lite = dict(pipeline_profile=PipelineConfig.lite(llm_enabled=False))

with lite_context(**lite) as memory:
    item_id = memory.ingest_structured(
        {
            "name": "AuthMiddleware",
            "entity_type": "class",
            "file_path": "middleware/auth.py",
            "line_number": 42,
            "repo": "my-service",
            "docstring": "JWT authentication middleware for FastAPI.",
            "bases": ["BaseHTTPMiddleware"],
        },
        schema="code_entity",
    )

    print(item_id)

The code_entity schema requires name, entity_type, file_path, line_number, and repo. The entity_type must be one of module, class, function, route, or test.

Languages supported

LanguageStatusFile extensionsNotes
PythonFull support.pyAST-based parsing. Extracts classes, functions, FastAPI routes, pytest tests, imports, calls, and inheritance.
TypeScriptExperimental.ts, .tsx, .js, .jsxBasic entity extraction. Pass --language typescript to the CLI.

IndexResult

The ingest_code() method returns the real IndexResult dataclass from smartmemory.code.models:

from dataclasses import fields

from smartmemory.code.models import IndexResult

print([field.name for field in fields(IndexResult)])

Check result.errors after indexing to see any files that failed to parse. Failed files are skipped without aborting the run.

Pattern seeding

After indexing, seed_patterns_from_code() runs automatically. It extracts {name: entity_type} pairs from the indexed entities and merges them into the workspace's EntityRuler pattern set.

This means that after you index a codebase, future ingest() calls over natural-language text can recognize references to your code symbols. For example, if you index a project containing class SmartGraph, then ingesting the text "The SmartGraph module handles all graph queries" can identify SmartGraph as a named entity of type class.

On this page