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:
- File collection: walks the directory tree, collecting files by language.
- AST parsing: extracts code entities and relationships from each file.
- Cross-file resolution: builds a symbol table to resolve import bindings across modules.
- Graph writing: creates nodes and edges in the knowledge graph.
- Embedding generation: generates vector embeddings for each entity.
- 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-projectThen 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
| Parameter | Description |
|---|---|
PATH | Directory to index. Use . for the current repo. |
--repo | Short repository identifier such as "my-service". |
--language | Repeatable language selector. Supports python and typescript. Defaults to Python. |
--exclude | Repeatable directory name to skip. |
--commit-hash | Override the Git commit SHA. Pass an empty string to suppress auto-detection. |
Entity types
The parser extracts five entity types from source code:
| Entity type | Description | Example |
|---|---|---|
module | A source file | smartmemory/code/parser.py |
class | Class definition | class CodeParser |
function | Function or method definition | def parse_file(...) |
route | FastAPI or Express route handler | @router.get("/health") |
test | Test function | def 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:
| Property | Type | Always present | Description |
|---|---|---|---|
item_id | str | yes | Deterministic node ID |
name | str | yes | Entity name |
entity_type | str | yes | One of module, class, function, route, test |
file_path | str | yes | Relative path from the repository root |
line_number | int | yes | Line number where the entity is defined |
repo | str | yes | Repository identifier |
memory_type | str | yes | Always "code" |
docstring | str | if present | First 500 characters of the entity's docstring |
decorators | str | if present | Comma-separated decorator names |
bases | str | if present | Comma-separated base class names |
http_method | str | routes only | HTTP method such as GET or POST |
http_path | str | routes only | Route path such as /health |
commit_hash | str | if provided | Git 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_at | str | yes | ISO timestamp of when the entity was indexed |
Relationship edges
The indexer creates five types of edges between code entity nodes:
| Edge type | Meaning | Example |
|---|---|---|
DEFINES | A module defines a class or function | parser.py defines CodeParser |
IMPORTS | A file imports a symbol from another module | indexer.py imports CodeEntity |
CALLS | A function calls another function | index() calls parse_file() |
INHERITS | A class extends another class | SqliteStore inherits BaseStore |
TESTS | A test function tests a specific entity | test_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| Option | Meaning |
|---|---|
--repo | Repo name stamped on the file. Required. |
--out | File to write. Required. |
--language | Narrow to python or typescript. Repeatable. Default is every supported language present. |
--exclude | Extra directory names to skip. Repeatable. |
--allow-partial | Write the file even when some files fail to parse. |
--fields | full (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_hashandsource: the revision of the checkout. A dirty tree gets<HEAD>-dirty-<fingerprint>.source.repo_identityis the same checkout identity the hosted index uses.entities: each has anitem_id, and every relation endpoint is theitem_idof an entity in the same file.relations:DEFINES,IMPORTS,CALLS,INHERITS,TESTSandREFERENCES. A call site with several candidates produces one relation per candidate.edge_stateon every call, test and reference relation:resolved(one candidate) orambiguous(several). A site with no candidate, whetherunresolvedorunsupported, is not written as a relation. It stays incall_evidenceortest_evidencewith 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_evidenceandtest_evidenceon 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 withgrammar_unavailablewhen the optional grammars are missing. Install them withpip install "smartmemory-core[typescript]".complete: true when no file failed to parse.failed_pathslists the failures, andbudget_exhaustedsays whether the run stopped at its entity limit.source.resolution_dependencies: the files the resolvers read, such astsconfig.jsonfiles in anextendschain and the nearestpackage.jsonof each JavaScript file. A change to one of them can change edges even whencommit_hashdoes not change, so re-check them to decide whether a snapshot is stale. Content entries carry asha256. Directory listing and glob entries carrymembers_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_sha256is null andmembers_errorsays 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
| Language | Status | File extensions | Notes |
|---|---|---|---|
| Python | Full support | .py | AST-based parsing. Extracts classes, functions, FastAPI routes, pytest tests, imports, calls, and inheritance. |
| TypeScript | Experimental | .ts, .tsx, .js, .jsx | Basic 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.