symbol-memory 0.1.0

Manual markdown-based symbol memory for Python codebases.

Symbol Memory

Manual symbol memory for Python codebases.
Explicit symbol indexing for agents, tools, and developers who need exact navigation.

Symbol Memory gives Python projects a small, explicit navigation layer on top of real source code.
You annotate the symbols that matter, build once, and then query the project by exact symbol id instead of repeatedly scanning large files or guessing relationships.

It is intentionally not a RAG system, not a semantic search layer, and not a code execution engine.
The model is simple: manual meaning, automatic structure, deterministic lookup.

uv add symbol-memory

from symbol_memory import SymbolMemory, symbol

---

Why This Exists

Most code-assistance pipelines fail in one of two ways:

1. They read too much code and waste context on irrelevant files.
2. They invent connections that were never explicitly defined.

Symbol Memory takes the opposite approach:

• semantics stay manual
• structure comes from AST
• relations remain explicit and auditable
• navigation stays exact and stable

If a symbol is not annotated, it does not exist for this system.

---

At a Glance

Exact symbol graph	Map important functions, classes, and methods to string ids and manual relation ids.
AST-only scanning	Reads source without importing or executing project code.
Fast generated artifacts	Produces JSON indexes and markdown symbol cards optimized for repeat lookup.
Validation-first workflow	Reports duplicate ids, broken relations, malformed metadata, and artifact drift with structured diagnostics.
CLI and Python API	Use it from scripts, local tooling, or directly from the terminal.

---

Core Model

Annotate top-level functions, classes, and class methods with a single decorator:

from symbol_memory import symbol


@symbol(
    "1",
    r=["2", "1.2"],
    role="auth",
    summary="Validates access token",
    notes="Critical auth path",
    tags=["auth", "critical"],
)
def validate_token(token: str) -> bool:
    return token == "ok"

Manual metadata

• id: primary string symbol id such as "1" or "1.2"
• r: manually declared relation ids
• role: short human-written role
• summary: short human-written summary
• notes: optional string or None
• tags: optional list of strings; omitted values normalize to []
• expose: optional boolean
• entrypoint: optional boolean

Validation rules

• symbol ids use numeric dot-separated string segments such as "1" or "1.2.3"
• r is required, but r=[] is completely valid
• role and summary must be non-empty string literals
• tags may be omitted, None, or a list of non-empty strings
• the decorator does not wrap the object and does not change runtime behavior

Automatically extracted fields

• name
• qualified_name
• symbol_type
• file_path
• module_path
• start_line
• end_line
• parent_class_name
• child_method_ids
• hierarchy_parent_id
• hierarchy_child_ids

---

Quick Start

Install

uv add symbol-memory

The package name is symbol-memory, but the Python import is symbol_memory.

Annotate symbols

from symbol_memory import symbol


@symbol(
    "1",
    r=["2"],
    role="auth",
    summary="Validates access token",
)
def validate_token(token: str) -> bool:
    return token == "ok"

Build symbol memory

symbol-memory build path/to/project

Query it

symbol-memory list --project-root path/to/project
symbol-memory find auth --project-root path/to/project
symbol-memory show 1 --project-root path/to/project
symbol-memory relations 1 --project-root path/to/project
symbol-memory branches 1 --project-root path/to/project
symbol-memory children 1 --project-root path/to/project
symbol-memory parent 1.2 --project-root path/to/project
symbol-memory roots --project-root path/to/project
symbol-memory open 1 --project-root path/to/project

Validate after changes

symbol-memory validate path/to/project

End-to-end example

uv add symbol-memory
symbol-memory build path/to/project
symbol-memory show 1 --project-root path/to/project
symbol-memory relations 1 --project-root path/to/project

---

Python API

from symbol_memory import SymbolMemory

memory = SymbolMemory(project_root=".")

report = memory.build()
if report.status == "error":
    print(report.error_count)

symbol = memory.get_symbol("1")
relations = memory.show_relations("1")
branches = memory.list_branches("1")
source = memory.open_symbol("1")

Main API surface:

• build()
• validate()
• find()
• get_symbol()
• get_symbol_card()
• show_relations()
• preview_relation()
• open_symbol()
• open_file_range()
• list_symbols()
• list_children()
• list_branches()
• get_parent()
• list_roots()

---

CLI Reference

Command	Purpose
symbol-memory build [project-root]	Scan source and write .symbol_memory/
symbol-memory validate [project-root]	Compare source truth with saved artifacts
symbol-memory find QUERY	Lookup by id, exact name, qualified name, or substring
symbol-memory show ID	Print the markdown symbol card
symbol-memory relations ID	Show resolved relation previews
symbol-memory branches ID	Print the full branch tree rooted at the given id
symbol-memory children ID	Print direct children for the given id
symbol-memory parent ID	Print the direct parent for the given id
symbol-memory roots	Print all root-level symbols
symbol-memory open ID	Print the source slice for a symbol
symbol-memory list	List all indexed symbols sorted by id

---

Generated Artifacts

Running a build creates a .symbol_memory/ directory inside the target project:

.symbol_memory/
  index.json
  relations.json
  validation_report.json
  project_map.md
  symbols/
    1.md
    1.1.md
    2.md

index.json	Canonical machine-readable index with symbols and lookup tables.
relations.json	Resolved relation previews for each source symbol.
validation_report.json	Structured validation output with issue codes, locations, and hints.
project_map.md	High-level human-readable project overview.
symbols/{id}.md	Markdown card for each indexed symbol, including dotted ids such as 1.1.md.

---

Validation and Error Handling

Symbol Memory is built to fail clearly.

Diagnostics include:

• stage-aware issues from scan, parse, resolve, artifact, and query
• exact issue codes
• file and line context where available
• field-level hints for broken decorator metadata
• drift detection when generated artifacts no longer match source

Examples of problems it catches:

• duplicate symbol ids
• invalid decorator usage
• invalid literal types in metadata
• missing relation target ids
• missing or broken generated artifacts
• stale symbol cards or lookup indexes after refactors

build still writes .symbol_memory/validation_report.json even when errors exist, so broken states remain inspectable and debuggable.

---

Agent Prompts

This repository includes project prompts in formats that are practical to use directly:

• Codex skill: codex/skills/symbol-memory/SKILL.md
• Claude project file: CLAUDE.md

They are intentionally short. They tell the agent to:

• build or validate before relying on symbol memory
• use find, relations, and open before broad grep
• treat .symbol_memory/ as generated output
• respect the manual relation model from r=[...]

How to use them

• Codex: Copy the codex/skills/symbol-memory/ folder into your Codex skills directory or install it as a local skill.
• Claude: Copy CLAUDE.md into the root of the target repository so Claude can pick it up as a project instruction file.

---

Design Principles

• Never infer semantic meaning from code automatically.
• Never invent relations automatically.
• Never import or execute user project code during scanning.
• Keep the system small, explicit, and tool-first.
• Prefer exact source coordinates over fuzzy repository search.

---

Current Scope

Supported in the current version:

• Python 3.12+
• top-level functions
• top-level classes
• class methods
• string ids such as "1" and "1.2"
• hierarchy inferred from dotted ids
• @symbol(...)
• @module.symbol(...)

Not supported in v1:

• nested symbol indexing
• alias-aware decorator resolution
• multi-language scanning
• automatic relation discovery
• semantic inference
• incremental rebuilds

---

Development

git clone https://github.com/Madikhan33/Symbol.git
cd Symbol
uv sync
uv run --with pytest pytest
uv build

---

License

MIT - see LICENSE.