sinew 1.0.2

Structural dependency graph for codebases - the memory layer for developers and AI agents

Sinew 🗺️

The structural memory of your codebase. For developers. For AI agents. Forever.

---

Sinew is a CLI tool that converts any codebase into a living, machine-readable dependency graph — a structural map of how every file, module, class, function, variable, and relationship in your project connects.

It is not a documentation tool. It is not a search tool. It is not a visualization tool.

It is the ground truth of your codebase's structure — always current, always queryable, readable by humans and AI agents equally.

The output is a JSON graph that powers:

• A 2D architectural map — layered topology of your system
• A spider-web dependency graph — every relationship visualized as a dense, interactive web
• A developer CLI — query, trace, search, and understand any part of your codebase in seconds
• An agent infrastructure layer — structural context, hallucination guards, territory maps, and session memory for any AI coding agent

---

Why Sinew Exists

Modern repositories contain thousands of files and deeply tangled dependencies. The questions developers and AI agents ask most often have no fast answer:

• Where is this function first defined?
• What breaks if I change this variable?
• Which files import this module?
• Has this function been duplicated somewhere?
• What is the full call chain for this feature?
• Has an agent touched this file already?
• What does this codebase's architecture actually look like?

Every existing tool answers these by re-scanning the codebase on demand — which is slow, incomplete, and stateless. Sinew pre-computes the answer to all of them once, stores it as a structural graph, and makes every answer instant.

For AI agents specifically, the problem is deeper. Agents forget everything between sessions. They hallucinate functions that don't exist. They violate architecture rules they were never told. They duplicate code that already exists three files away. They create merge conflicts with other agents running in parallel. Sinew is the structural layer that eliminates all of these failures — not by making agents smarter, but by giving them the structural knowledge they have no other way to access.

---

Table of Contents

• Installation
• Quick Start
• Core Concepts
• CLI Reference
• Developer Features
• Agent Features
• sinew Schema
• Architecture Constitution
• Configuration
• JSON Graph Schema
• Language Support
• MCP Server
• Integrations
• Architecture
• Roadmap

---

Installation

pip install sinew

Verify:

sinew --version

---

Quick Start

Build a graph from any repository:

sinew build ./my-project

This scans the repository, parses all supported source files, and produces sinew.json in the project root.

Explore it immediately:

sinew web sinew.json      # opens spider-web graph in browser
sinew map sinew.json      # opens 2D architectural map in browser
sinew stats                   # prints repository health summary

Ask your first structural question:

sinew trace login             # full call chain from login
sinew impact verify_password  # what breaks if this changes
sinew search db_conn          # where is this used

---

Core Concepts

The Graph

Everything Sinew does derives from a single source of truth: the dependency graph. The graph is a collection of nodes (every code object — files, modules, classes, functions, variables) and edges (every relationship — calls, imports, inheritance, data flow).

The graph is stored as sinew.json. Every CLI command, every visualization, every agent feature, every query runs against this file. You never re-parse the codebase for a query. The graph already knows.

Nodes

A node represents any named code object:

Node Type	Examples
file	auth/login.py, utils/crypto.js
module	database, os, express
class	AuthService, UserModel
function	verify_password, get_user
method	AuthService.login
variable	db_conn, MAX_RETRIES
interface	IAuthProvider
struct	UserConfig

Edges

An edge represents a directional relationship between two nodes:

Edge Type	Meaning
calls	Function A calls function B
imports	File A imports module B
inherits	Class A inherits from class B
implements	Class A implements interface B
instantiates	Code creates an instance of class B
reads	Code reads variable B
writes	Code writes variable B
returns	Function A returns type B

Every edge carries a confidence score between 0 and 1. In dynamic languages like Python and JavaScript, some edges cannot be proven with certainty — an argument typed as handler could be any object at runtime. Sinew marks these inferred edges with lower confidence so you always know what is structural fact versus structural inference.

Origin

Every node carries its origin — the exact file and line number where it was first defined, not where it was imported or re-exported. This eliminates confusion in large codebases where symbols travel through many files before being used.

sinew Schema

An optional inline annotation system for enriching the graph with human intent. Developers leave structured notes directly in source code that Sinew reads into graph nodes. Details in the sinew Schema section.

---

CLI Reference

Build Commands

Command	Description
sinew build <path>	Build full repository graph
sinew build <file> --file	Build graph for a single file only
sinew build <path> --output <file>	Custom output path for JSON
sinew build <path> --ignore <paths>	Ignore specific files or folders
sinew watch <path>	Watch mode — live rebuild on file changes

Visualization Commands

Command	Description
sinew map <json>	Open 2D architectural layer map in browser
sinew web <json>	Open spider-web dependency graph in browser
sinew web <json> --heatmap activity	Web with runtime activity overlay
sinew web <json> --heatmap coverage	Web with test coverage overlay
sinew web <json> --heatmap modification	Web with git modification recency overlay

Query Commands

Command	Description
sinew search <symbol>	Search graph and return matching nodes + subgraph
sinew search <symbol> --save <file>	Save temporary search map as JSON
sinew trace <symbol>	Trace full execution call chain
sinew reverse <symbol>	Show everything that depends on this symbol
sinew impact <symbol>	Blast radius analysis before a change
sinew lineage <variable>	Trace full birth-to-death path of a variable
sinew origin <symbol>	Find first definition of any symbol
sinew explain <file>	Graph-generated plain-language summary of a file
sinew query "<expression>"	Structured query against the graph

Listing Commands

Command	Description
sinew list functions	All functions with file, line, origin
sinew list classes	All classes
sinew list variables	All variables
sinew list modules	All modules
sinew list --group <name>	All symbols tagged with sinew Schema group
sinew list --critical	All symbols marked critical in sinew Schema
sinew list --deprecated	All symbols marked deprecated
sinew module <name>	Full usage details for a module

Analysis Commands

Command	Description
sinew stats	Full repository health metrics
sinew score	Structural debt score with trend
sinew dead	All unused symbols
sinew phantoms	All imported-but-never-used symbols
sinew hotspots	High-coupling nodes — architectural risk
sinew clusters	Auto-detected architectural domains
sinew ownership	Per-symbol ownership and bus factor
sinew diff <a.json> <b.json>	Structural diff between two graph snapshots
sinew audit --since last-commit	Structural audit of recent AI-generated code
sinew review --base <branch> --head <branch>	PR structural impact report

Snapshot Commands

Command	Description
sinew snapshot --tag <name>	Save a named graph snapshot
sinew diff --tag <a> --tag <b>	Compare two named snapshots
sinew timeline	Show architectural history across all snapshots

Agent Commands

Command	Description
sinew agent-boot --task "<description>"	Generate task-scoped agent boot payload
sinew agent-boot --task "<description>" --resume <session>	Resume a previous agent session
sinew context "<task>" --tokens <n>	Precision-scoped context payload within token budget
sinew verify <file>	Hallucination check — validate agent output against graph
sinew preflight --changes "<description>"	Risk report before any agent edit
sinew territory claim --agent <id> --scope <path> --task "<description>"	Claim territory for multi-agent coordination
sinew territory status	Show all active agent territories
sinew territory release --agent <id>	Release territory on task completion
sinew agent-log mistake --node <id> --description "<text>" --severity <level>	Attach a mistake memory to a graph node
sinew session-snapshot save --session <id> --summary "<text>"	Save agent session continuity state
sinew agent-export	Export full agent-optimized graph

Export Commands

Command	Description
sinew export --format dot	Graphviz DOT format
sinew export --format graphml	GraphML for Gephi / yEd
sinew export --format csv	nodes.csv + edges.csv
sinew export --format markdown	Human-readable structural summary
sinew tour --audience <type>	Generate guided onboarding tour

---

Developer Features

File-Specific sinew

Generate a graph for a single file without scanning the full repository. Useful for focused analysis, parser testing, or isolating a single module.

sinew build ./auth/login.py --file

Origin Tracking

Every symbol in the graph carries its true first-definition location — the exact file and line where it was created, not where it was imported, re-exported, or re-assigned downstream. When a symbol travels through dozens of files, the origin tells you where it was born.

{
  "id": "auth.verify_password",
  "type": "function",
  "origin": { "file": "auth/security.py", "line": 42 }
}

Module Import Tracking

Sinew tracks the complete import chain for every module and symbol — which files import it, which specific symbols each file pulls from it, and the full usage locations of each imported symbol.

sinew module database

Module: database
─────────────────────────────────────────────
get_user        → auth.py (line 14), admin.py (line 8)
db_conn         → auth.py (line 22), session.py (line 11)
create_record   → records.py (line 5)
─────────────────────────────────────────────
Imported by 6 files. Used in 14 locations.

Impact Analysis

Before modifying any symbol, evaluate its full blast radius — not just direct callers, but the complete transitive dependency chain across all files and modules.

sinew impact verify_password

Symbol         : verify_password
Risk           : HIGH
─────────────────────────────────────────────
Direct callers      : login, admin_login, reset_flow
Indirect chain      : token_check → reset_flow → verify_password
Affected functions  : 17
Affected files      : 6
Affected modules    : 3
Dependency depth    : 4 levels
Test coverage       : 4 of 17 callers have tests ⚠
Frozen downstream   : 0
Agent warnings      : 1
─────────────────────────────────────────────
Recommendation: 13 callers have no test coverage. Add tests before changing signature.

Execution Tracing

Trace the complete call chain from any entry point, following every branch of execution across files and modules.

sinew trace login

login
  → verify_password
      → database.get_user
          → redis_cache.fetch
      → hash_password
  → session.create
      → token.generate

Variable Lineage

Trace the complete life of any variable from first assignment through every read, write, pass, and mutation across every file it touches.

sinew lineage db_conn

db_conn
  born     → config.py line 12 (assigned from env)
  passed   → auth.py line 34 (constructor argument)
  read     → auth.py line 41 (used in query)
  passed   → session.py line 19 (argument to create_session)
  mutated  → session.py line 27 (reassigned to pool connection)
  dies     → session.py line 89 (out of scope)

Graph Search and Temporary Search Maps

Search the graph for any symbol and receive a filtered subgraph — a temporary search map — showing only the nodes and edges connected to that symbol. Temporary maps can be saved and shared without affecting the main graph.

sinew search verify_password
sinew search verify_password --save search_verify.json

sinew Query Language

Query the graph directly with structured expressions for precise filtering that simple search cannot achieve.

sinew query "calls(verify_password) AND file(auth.*)"
sinew query "type=function AND callers > 10"
sinew query "imports(database) AND NOT has_tests"
sinew query "confidence < 0.75 AND type=calls"
sinew query "modified_after(2026-01-01) AND hotspot=true"

Queries run against the JSON graph. No re-parsing. Instant results.

sinew explain

The graph narrates any file to you in plain language — not by reading the code, but by analysing the node's structural properties in the graph.

sinew explain auth/login.py

auth/login.py
─────────────────────────────────────────────
Centrality     : HIGH — imported by 11 other files
Outgoing deps  : 4 modules (database, session, cache, config)
Most-called fn : verify_password (17 callers)
Dead code      : 2 functions with no callers
Circular deps  : 1 (auth ↔ session)
Confidence     : 3 edges below 0.75 (dynamic dispatch detected)
Bus factor     : 1 (Raj is sole knowledge owner) ⚠
Agent warnings : 1 on verify_password
─────────────────────────────────────────────

Dead Code and Phantom Detection

Dead code — symbols defined but never called. Phantoms — symbols imported but never used within the importing file. Both add noise, slow parsers, and mislead agents.

sinew dead
sinew phantoms

Hotspot Detection

Nodes with unusually high in-degree are silent architectural risks — functions called by many callers are single points of failure.

sinew hotspots

verify_password    → 17 callers    ⚠ HIGH COUPLING
db_conn            → 34 usages     ⚠ CRITICAL DEPENDENCY
config.load        → 28 callers    ⚠ HIGH COUPLING

Cluster Auto-Detection

The graph builder automatically identifies natural architectural domains — groups of nodes that are densely connected internally and loosely connected externally — without requiring any manual labelling.

sinew clusters

Cluster 1 (12 files, 84 nodes)  — likely: authentication
Cluster 2 (7 files, 43 nodes)   — likely: database layer
Cluster 3 (19 files, 201 nodes) — likely: API routing

Structural Debt Score

Technical debt expressed as a number, not a feeling — with trend tracking across builds so teams can see whether the codebase is improving or degrading over time.

sinew score

Sinew Structural Score : 68 / 100

Coupling      : 71/100  (3 modules with > 15 dependents)
Cohesion      : 83/100
Circularity   : 55/100  (4 circular dependency chains)
Testability   : 72/100  (19% of hotspot functions untested)
Dead code     : 61/100  (231 unused symbols)
Documentation : 45/100  (67% of public functions without notes)

Trend : ↓ dropped 4 points in the last 30 days
Cause : circular dependencies added in recent PRs

Bus Factor and Ownership

By reading git history alongside the graph, Sinew calculates the bus factor of every node — how many developers need to leave before that piece of code has no knowledgeable owner.

sinew ownership

verify_password    → 1 owner (Raj)          BUS FACTOR: 1 ⚠ CRITICAL
auth cluster       → 2 owners (Raj, Priya)  BUS FACTOR: 2 ⚠
payment module     → 4 owners               BUS FACTOR: 4 ✓

Highest risk departure : Raj (sole owner of 14 nodes)

PR Structural Review

sinew review --base main --head feature/password-reset

Sinew Structural Review
─────────────────────────────────────────────
Impact level           : MEDIUM
New functions          : 4
Removed functions      : 1
Hotspot nodes touched  : 2 (verify_password, session.create)
Circular deps added    : 1 ⚠
Untested new code      : 3 functions
Dead code introduced   : 0
Confidence degraded    : 4 edges now below 0.75

Action required: Review circular dependency between auth ↔ reset_service before merging.
─────────────────────────────────────────────

AI Session Audit

After any AI coding session, audit the structural changes for violations, duplications, and regressions before they make it into a commit.

sinew audit --since last-commit

AI session audit
─────────────────────────────────────────────
Duplicate logic detected    : 3 functions already exist elsewhere
Architecture violations     : auth layer calling db directly (2 cases)
Naming inconsistencies      : camelCase in 4 files (project uses snake_case)
New circular dependencies   : 1 (auth ↔ session) ⚠
Dead code added             : 2 functions never called
Confidence warnings         : 6 edges below 0.75
─────────────────────────────────────────────
Estimated tech debt added   : HIGH

Guided Onboarding Tour

Generate a curated walkthrough of any codebase that takes a new developer from zero to architectural understanding in under an hour.

sinew tour ./repo --audience new-developer

Produces TOUR.md or an interactive web sequence walking through entry points, core architecture, data flow, isolated clusters, and known complexity zones — all derived automatically from the graph.

Heatmap Layers

Overlay different data dimensions onto the web or map visualization to reveal what structure alone cannot show.

sinew web sinew.json --heatmap activity     # runtime call frequency
sinew web sinew.json --heatmap coverage     # test coverage
sinew web sinew.json --heatmap modification # git modification recency

Graph Snapshots and Timeline

Capture named snapshots of the graph at any point in time and compare them to understand how architecture evolved.

sinew snapshot --tag "before-refactor"
sinew snapshot --tag "after-refactor"
sinew diff --tag before-refactor after-refactor
sinew timeline

Watch Mode

sinew watch ./repo

Monitors the filesystem and rebuilds only the affected portions of the graph as files change. The web and map views auto-refresh. The graph stays current during active development without a full rebuild.

---

Agent Features

Sinew is agent-native infrastructure. Every feature in this section exists because AI coding agents face problems that are structurally different from what human developers face — and that require structural solutions, not prompting tricks.

Agent Boot Payload

The most common agent failure: starting a session with no knowledge of the codebase's conventions, existing functions, architectural decisions, or past mistakes. Sinew generates a task-scoped boot payload that gives any agent complete structural orientation in under 1,000 tokens.

sinew agent-boot --task "add password reset to auth module"

Output boot.json:

{
  "task_scope": {
    "relevant_files": ["auth/login.py", "auth/security.py", "models/user.py"],
    "entry_points": ["auth.login", "auth.logout"],
    "hotspots_in_scope": ["verify_password — 17 callers, HIGH RISK"]
  },
  "conventions": {
    "naming": "snake_case functions, PascalCase classes",
    "error_handling": "raise AuthError — never return None for auth failures",
    "patterns": ["no direct db calls from auth layer", "dependency injection via constructor"]
  },
  "what_already_exists": {
    "do_not_recreate": [
      "get_user — database/queries.py line 42",
      "hash_password — auth/security.py line 18"
    ]
  },
  "past_mistakes": [
    "verify_password was inlined into login on 2026-01-09 — broke 17 callers, reverted",
    "Circular dep introduced between auth ↔ session on 2026-02-14 — reverted"
  ],
  "frozen_zones": [
    "auth/legacy_sso.py — vendor contract, do not modify"
  ],
  "confidence_warnings": [
    "auth.middleware — 3 edges below 0.75, dynamic dispatch, tread carefully"
  ]
}

Every piece of this is derived entirely from the live graph. Nothing needs to be written manually. The agent loads this once, and it already knows the territory — before opening a single file.

Precision Context Budgeting

More context does not always mean better agent output. Studies show agents perform worse, not better, when flooded with irrelevant context. Sinew generates a precision-scoped context payload calibrated to an exact token budget — containing only the structural information the agent actually needs for the stated task.

sinew context "fix bug in verify_password where locked accounts still authenticate" --tokens 4000

Sinew traverses the graph to determine the minimum structural knowledge needed — the 3 relevant files, 2 affected callers, the User.is_locked field origin, the test file, and any sinew Schema notes — and outputs exactly that. No noise. No irrelevant modules. Maximum agent focus.

Hallucination Guard

Before an agent writes any file, validate its proposed output against the live graph. Sinew checks every function call, import, class reference, and method call for structural existence — in under a second, without executing any code.

sinew verify agent_output.py

Hallucination check
─────────────────────────────────────────────
auth.get_user_by_email     → NOT FOUND ⚠
                              Did you mean: database.get_user (takes username, not email)
session.create_secure()    → EXISTS ✓
User.is_locked             → EXISTS ✓
User.lock_account()        → NOT FOUND ⚠
                              User has: User.set_active(False) — same intent, different API
─────────────────────────────────────────────
2 hallucinations detected. Blocked before write.

The agent never runs. The developer never spends 20 minutes debugging why the agent's code throws AttributeError.

Dependency Pre-Flight

Before any agent modification, generate a machine-readable risk report that the agent can incorporate into its plan. The agent receives structural risk information it had no other way to access.

sinew preflight --changes "modify verify_password signature to add mfa_token param"

{
  "risk": "HIGH",
  "callers_affected": 17,
  "test_coverage_on_callers": "4 of 17 callers have tests",
  "frozen_nodes_touched": 0,
  "circular_deps_introduced": 0,
  "agent_warnings_on_node": 1,
  "confidence_warnings": 2,
  "recommendation": "13 untested callers. Add tests before changing signature."
}

Multi-Agent Territory Map

When multiple agents work on the same codebase simultaneously, they have no shared awareness of each other. Sinew is the shared ground truth — a territory layer that all agents talk to so none collide.

sinew territory claim --agent "agent-auth" --scope "auth/" --task "refactor verify_password"
sinew territory claim --agent "agent-reset" --scope "auth/reset.py" --task "add password reset"

Territory conflict detected
─────────────────────────────────────────────
agent-auth    claims: auth/           (touches verify_password)
agent-reset   claims: auth/reset.py   (imports verify_password)

Shared dependency : verify_password
Resolution        : agent-reset should wait for agent-auth to complete,
                    or agent-auth should mark verify_password interface stable first.
─────────────────────────────────────────────

sinew territory status       # see all active agent territories
sinew territory release --agent "agent-auth"  # release on completion

Mistake Memory

When an agent makes a mistake and a developer reverts it, that knowledge disappears. The next session — same agent, different agent — makes the same mistake again. Sinew attaches mistake memories permanently to graph nodes. Every future agent boot payload touching that node includes the warning automatically.

sinew agent-log mistake \
  --node "auth.verify_password" \
  --description "inlining this function breaks 17 callers — always keep it separate" \
  --severity high

The mistake is made once. Never again. Across all agents, all sessions, all time.

Session Continuity Snapshots

When a long-horizon agent session ends, everything it learned — which files it read, which decisions it made, which dead ends it hit — evaporates. Sinew saves a continuity snapshot so the next session resumes with full context instead of starting from zero.

# At end of session
sinew session-snapshot save \
  --session "auth-refactor-session-1" \
  --summary "Refactored verify_password. Did not touch session.py yet — needs mfa_token propagated. Dead end: middleware approach creates circular dep with auth."

# At start of next session
sinew agent-boot --task "continue auth-refactor" --resume "auth-refactor-session-1"

No handoff document. No human memory required. The graph carries the session state forward.

Agent Export

Export a complete agent-optimized representation of the repository — a single JSON structured for maximum agent utility.

sinew agent-export

Output agent_graph.json:

{
  "function_index": { ... },
  "call_graph": { ... },
  "file_index": { ... },
  "dependency_index": { ... },
  "reverse_index": { ... },
  "origin_index": { ... },
  "sinew_notes": { ... },
  "frozen_zones": { ... },
  "mistake_memory": { ... },
  "architecture_constitution": { ... }
}

Any AI system can consume this file to understand full repository structure without scanning a single source file.

---

sinew Schema

sinew Schema is Sinew's inline annotation system. Developers embed structured notes directly in source code to enrich the graph with human intent — for other developers, for AI agents, and for graph queries.

sinew Schema annotations use the # @sinew: prefix and appear as dedicated fields on graph nodes. They are distinct from regular comments and are written intentionally for graph consumers.

Variables

db_conn = get_connection()  # @sinew: note="primary db connection, do not reassign" critical=true
MAX_RETRIES = 3             # @sinew: note="tuned for production timeout budget" group="config"
temp_buffer = []            # @sinew: ignore

Functions

def verify_password(user, password):
    # @sinew: note="core auth primitive, 17 callers — never inline" critical=true owner="platform-team"

Classes

class AuthService:
    # @sinew: note="handles all authentication" group="auth" owner="platform-team"

Frozen Zones

Marks a node as off-limits for any modification. Enforced in agent boot payloads, hallucination checks, and architecture constitution validation.

class LegacySSOHandler:
    # @sinew: frozen reason="vendor contract" since="2024-03-01" owner="platform-team"

PAYMENT_GATEWAY_VERSION = "2.1.4"  # @sinew: frozen reason="PCI-DSS certified, changes require re-audit"

Supported Annotation Fields

Field	Type	Description
note	string	Human-readable description for graph consumers
critical	bool	High-weight node — highlighted in visualizations and included in all agent payloads
frozen	bool/string	Off-limits for modification — enforced for agents
reason	string	Reason for frozen status
deprecated	bool	Marks node as deprecated in listings and agent payloads
group	string	Architectural group name for cluster queries
owner	string	Team or developer responsible for this symbol
since	date	Date annotation was added
ignore	bool	Exclude node from graph entirely

Querying sinew Schema

sinew list --critical                    # all critical symbols
sinew list --deprecated                  # all deprecated symbols
sinew list --group auth                  # all symbols in auth group
sinew list --owner platform-team         # all symbols owned by platform-team
sinew query "frozen=true"                # all frozen zones

---

Architecture Constitution

The architecture constitution defines structural rules for your codebase that are machine-enforced on every build and on every agent output. Rules live in .sinewconstitution at the repository root and are committed alongside code.

Example .sinewconstitution

[[rule]]
name        = "no-auth-to-db-direct"
description = "Auth layer must not call database layer directly. Use service layer."
forbid_edge = { from_pattern = "auth.*", to_pattern = "database.*", type = "calls" }
severity    = "error"

[[rule]]
name        = "no-circular-deps"
description = "No circular dependencies anywhere in the codebase."
forbid      = "circular_dependency"
severity    = "error"

[[rule]]
name        = "hotspot-functions-must-be-tested"
description = "Any function with more than 10 callers must have at least one test."
require     = "test_coverage"
when        = "callers > 10"
severity    = "error"

[[rule]]
name        = "services-must-be-tested"
description = "Every public function in services/ must have at least one test."
require     = "test_coverage"
scope       = "services/**"
severity    = "warning"

[[rule]]
name        = "no-god-files"
description = "No file may have more than 15 outgoing dependency edges."
max_outgoing_edges = 15
severity    = "warning"

[[rule]]
name        = "no-low-confidence-in-core"
description = "No inferred edges below 0.80 confidence in the auth or payment clusters."
max_confidence = 0.80
scope       = ["auth/**", "payment/**"]
severity    = "warning"

Constitution Enforcement

Constitution violations are reported on every sinew build, every sinew verify on agent output, and every sinew review on a pull request. No agent violates architecture rules silently. No developer merges a constitution violation without knowing it.

sinew build ./repo

Constitution violations
─────────────────────────────────────────────
[error]   no-auth-to-db-direct    auth/login.py line 34 — direct call to database.get_user
[error]   no-circular-deps        auth ↔ session — circular dependency introduced
[warning] services-must-be-tested services/reset.py — 2 public functions with no tests
─────────────────────────────────────────────
Build completed with violations. Fix errors before committing.

---

Configuration

Sinew is configured via .sinewconfig at the repository root. This file is committed to the repository so every developer, every agent, and every CI run produces identical output.

.sinewconfig

[sinew]
languages             = ["python", "typescript", "javascript"]
output                = "./sinew/sinew.json"
confidence_threshold  = 0.75
entry_points          = ["main.py", "app/server.py"]

[sinew.ignore]
directories = [
  "__pycache__", ".venv", "venv", "env",
  "node_modules", ".git", "dist", "build",
  ".next", ".nuxt", ".pytest_cache", ".mypy_cache",
  "*.egg-info", "coverage"
]
files = ["*.min.js", "*.bundle.js", "config/secret.py"]
custom = ["tests/fixtures/", "scripts/legacy/"]

[sinew.schema]
require_annotations   = false
critical_symbols      = ["verify_password", "db_conn", "payment_gateway"]

[sinew.agents]
boot_token_budget     = 800
context_token_budget  = 4000
mistake_memory        = true
territory_map         = true
session_snapshots     = true

[sinew.constitution]
file                  = ".sinewconstitution"
enforce_on_build      = true
enforce_on_agent      = true
block_on_error        = false

.sinewignore

For simpler ignore rules, Sinew also accepts a .sinewignore file using identical syntax to .gitignore.

tests/
scripts/legacy/
docs/
*.min.js
config/secret.py
build/

---

JSON Graph Schema

Node

{
  "id": "auth.verify_password",
  "type": "function",
  "file": "auth/security.py",
  "line": 42,
  "origin": {
    "file": "auth/security.py",
    "line": 42
  },
  "notes": "Docstring or extracted comment attached here",
  "sinew_note": "core auth primitive, 17 callers — never inline",
  "sinew_critical": true,
  "sinew_frozen": false,
  "sinew_owner": "platform-team",
  "sinew_group": "auth",
  "agent_warnings": [
    {
      "description": "inlining this function breaks 17 callers",
      "severity": "high",
      "logged": "2026-01-09"
    }
  ],
  "callers": 17,
  "has_tests": true,
  "confidence_min": 0.91,
  "bus_factor": 1
}

Edge

{
  "from": "auth.login",
  "to": "auth.verify_password",
  "type": "calls",
  "file": "auth/login.py",
  "line": 55,
  "confidence": 0.97
}

---

Language Support

Sinew uses Tree-sitter for all language parsing, providing reliable AST access across every supported language.

Phase 1

Language	Parser	Status
Python	tree-sitter-python + ast fallback	✅ Available
JavaScript	tree-sitter-javascript	✅ Available
TypeScript	tree-sitter-typescript	✅ Available

Phase 2

Language	Parser	Status
Java	tree-sitter-java	🔜 Planned
Go	tree-sitter-go	🔜 Planned
Rust	tree-sitter-rust	🔜 Planned

Phase 3

Language	Parser	Status
C++	tree-sitter-cpp	🔜 Planned
C#	tree-sitter-c-sharp	🔜 Planned
PHP	tree-sitter-php	🔜 Planned
Swift	tree-sitter-swift	🔜 Planned

All parsers extract the same symbol and relationship types and produce the same intermediate schema, making the graph fully language-agnostic.

---

MCP Server

Sinew exposes all graph capabilities as a native MCP server, making it directly consumable by any MCP-compatible agent tool — Cursor, Claude Code, Windsurf, and others.

Starting the server

sinew serve --port 2048

Connecting in your agent tool

{
  "mcp_servers": [
    {
      "name": "sinew",
      "url": "http://localhost:2048/mcp"
    }
  ]
}

Available MCP Tools

Once connected, agents can call Sinew tools natively during their reasoning without any CLI commands.

Tool	Description
sinew.get_boot(task)	Task-scoped boot payload
sinew.get_context(task, tokens)	Precision-scoped context within token budget
sinew.check_exists(symbol)	Hallucination guard — instant structural existence check
sinew.get_impact(symbol)	Blast radius report
sinew.get_preflight(changes)	Risk report before any edit
sinew.claim_territory(agent, scope, task)	Multi-agent conflict prevention
sinew.release_territory(agent)	Release on task completion
sinew.log_mistake(node, description, severity)	Attach mistake memory to graph node
sinew.verify_output(code)	Constitution + hallucination check on agent output
sinew.search(symbol)	Graph search from within agent
sinew.trace(symbol)	Call chain from within agent
sinew.get_impact(symbol)	Impact analysis from within agent

---

Integrations

VS Code Extension

The Sinew VS Code extension shows your structural position in the graph as you navigate files — callers, dependencies, hotspot status, confidence warnings, and sinew Schema notes — without running any command.

Install: search Sinew in the VS Code marketplace.

Git Hook

The included git hook automatically rebuilds the affected graph portions on every commit and appends a structural summary to the commit message.

sinew install-hook

CI Integration

Add structural validation to any CI pipeline.

# GitHub Actions example
- name: Sinew structural check
  run: |
    sinew build ./
    sinew score --min 60
    sinew audit --since last-commit --fail-on-violations

---

Architecture

CLI Entry
    │
    ▼
File Scanner
    │  (respects .sinewignore, .sinewconfig, auto-ignores cache/venv/node_modules)
    ▼
Language Detector
    │
    ▼
Tree-sitter Parser  (per language, parallel)
    │
    ▼
AST Traversal
    │
    ▼
Symbol Extractor
    │   ├─ Functions, classes, variables, interfaces
    │   ├─ Imports and exports
    │   ├─ Conditionals and try/except blocks
    │   ├─ Comments and docstrings → notes
    │   └─ sinew Schema annotations → sinew_* fields
    ▼
Relationship Extractor
    │   ├─ Call graph (with confidence scoring)
    │   ├─ Import graph
    │   ├─ Inheritance graph
    │   └─ Data flow graph
    ▼
Origin Resolver
    │
    ▼
Reverse Index Builder
    │
    ▼
Constitution Validator
    │
    ▼
Graph Builder → sinew.json
    │
    ├── Map Renderer          (2D architectural layout)
    ├── Web Renderer          (spider-web dependency graph)
    ├── Agent Exporter        (agent_graph.json)
    └── MCP Server            (live tool access for agents)

Project Structure

sinew/
├── cli/
│   └── main.py
├── core/
│   ├── scanner.py
│   ├── detector.py
│   ├── graph.py
│   ├── origin.py
│   ├── reverse_index.py
│   ├── confidence.py
│   └── constitution.py
├── parsers/
│   ├── base.py               (shared interface)
│   ├── python/parser.py
│   ├── javascript/parser.py
│   ├── typescript/parser.py
│   └── ...
├── schema/
│   ├── sinew_schema.py
│   └── node.py
├── renderers/
│   ├── map.py
│   └── web.py
├── agents/
│   ├── boot.py
│   ├── context.py
│   ├── territory.py
│   ├── verify.py
│   ├── preflight.py
│   ├── session.py
│   └── export.py
├── mcp/
│   └── server.py
├── exporters/
│   ├── dot.py
│   ├── graphml.py
│   ├── csv.py
│   └── markdown.py
└── tests/

---

Roadmap

Phase 1 — Core Engine

• Python parser and symbol extractor
• Graph builder and JSON schema
• Origin tracking and reverse index
• Confidence scoring on all edges
• Comments and docstrings as notes
• sinew Schema annotations
• Ignore rules and .sinewconfig
• CLI: build, search, trace, impact, stats, dead, list, explain
• Architecture constitution and validation

Phase 2 — Multi-Language and Visualization

• JavaScript and TypeScript parsers
• Java and Go parsers
• Map renderer (2D architectural layout)
• Web renderer (spider-web dependency graph)
• Heatmap layers (activity, coverage, modification)
• Diff mode and snapshots
• PR structural review
• Watch mode
• VS Code extension

Phase 3 — Agent Infrastructure

• Full agent feature suite
• MCP server
• Multi-agent territory map
• Mistake memory
• Session continuity snapshots
• Hallucination guard
• Architecture constitution enforcement on agents
• Rust, C++, C#, PHP, Swift parsers

Phase 4 — Scale and Ecosystem

• 100,000+ file repository support with incremental parsing
• Multi-repo federation
• Runtime profile overlay
• CI/CD integration suite
• Structural debt score trending
• sinew Query Language full implementation
• Open graph schema standard

---

License

MIT

---

Sinew is the structural memory that codebases have always needed and never had — for developers navigating complexity, and for agents navigating blindly.