sidegraph 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,392 @@
1
+ Metadata-Version: 2.5
2
+ Name: sidegraph
3
+ Version: 0.1.0
4
+ Summary: Own the memory, rent the graph — a durable decision/lessons layer as a sidecar over a code-graph engine.
5
+ Project-URL: Homepage, https://github.com/SantyagoSeaman/sidegraph
6
+ Project-URL: Repository, https://github.com/SantyagoSeaman/sidegraph
7
+ Project-URL: Documentation, https://github.com/SantyagoSeaman/sidegraph/tree/main/docs
8
+ Project-URL: Issues, https://github.com/SantyagoSeaman/sidegraph/issues
9
+ Project-URL: Changelog, https://github.com/SantyagoSeaman/sidegraph/blob/main/CHANGELOG.md
10
+ Author: SantyagoSeaman
11
+ License-Expression: Apache-2.0
12
+ License-File: LICENSE
13
+ Keywords: adr,agent-memory,claude-code,code-graph,codex,coding-agents,decision-log,decision-records,developer-tools,knowledge-graph,mcp,mcp-server,team-memory
14
+ Classifier: Development Status :: 4 - Beta
15
+ Classifier: Environment :: Console
16
+ Classifier: Intended Audience :: Developers
17
+ Classifier: License :: OSI Approved :: Apache Software License
18
+ Classifier: Operating System :: OS Independent
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Topic :: Software Development :: Documentation
22
+ Classifier: Topic :: Software Development :: Libraries
23
+ Requires-Python: >=3.13
24
+ Requires-Dist: fastmcp>=3.4
25
+ Requires-Dist: pydantic>=2.9
26
+ Requires-Dist: python-ulid>=3.0
27
+ Description-Content-Type: text/markdown
28
+
29
+ # Sidegraph
30
+
31
+ > **Every agent session starts fresh. Your project should not.**
32
+
33
+ Sidegraph carries the project's accumulated decision map across sessions, so the next
34
+ agent approaches its task with the context a returning engineer has built over years:
35
+ why the code took its current shape, what was tried, and what the team learned.
36
+
37
+ Coding agents broke an old equilibrium: **code is now produced faster than anyone
38
+ accumulates the understanding of why it is the way it is.** The reasoning that shaped
39
+ each change happens once — inside a session — and is discarded with its context window.
40
+ You pay for the tokens, keep the diff, and throw away the judgment.
41
+
42
+ Half of a project's knowledge is derivable: what the code does, how it's connected — an
43
+ agent excavates that with grep, cheaper with every model generation. The half that
44
+ decides projects is not: **why it's built this way, what was tried and abandoned, which
45
+ constraint from outside the code forced the shape.** That information isn't in the
46
+ artifact at all. No future model will recover it, because it exists exactly once — at
47
+ decision time — and then evaporates: people leave, sessions end, the ticket from three
48
+ years ago is never found.
49
+
50
+ Sidegraph keeps that half and serves it back. Specs say what should be true and code
51
+ says what was built; Sidegraph keeps the third line — *how one became the other*: the
52
+ decisions, the rejected alternatives, and the lessons learned by doing — knowledge
53
+ recoverable from neither the documents nor the code. Every record is bound into one
54
+ graph with your code and your own planning artifacts, so the memory knows what it
55
+ governs — and notices when it goes stale. And it reaches the agent at the moment of
56
+ work, **mistakes first, before the first grep** — so no mistake is paid for twice, and
57
+ an agent doesn't confidently re-propose the design your team already rejected.
58
+
59
+ **Deciding whether this is worth your team's time?** Read the
60
+ [engineering whitepaper](docs/whitepaper/index.md) first. It states the idea,
61
+ walks one real decision chain end to end, reports what running it showed
62
+ (including the corpus where memory cost 25.5% more and answered worse), and
63
+ gives a fit test you can apply to your own repository before installing anything.
64
+
65
+ ```text
66
+ You: "refactor risk/fee_gate.py"
67
+
68
+ Injected into the agent's context — before it reads a single file:
69
+
70
+ ## ⚠ Known mistakes & gotchas
71
+ - [gotcha] HFT strategies require 0% maker/taker fees: assert_zero_fees()
72
+ checks account fees up front and raises FeeGateError — the bot refuses
73
+ to trade.
74
+
75
+ ## Decisions
76
+ - [adr] Stop levels ratchet monotonically: force_widen() is the only
77
+ entry point allowed to widen an active stop.
78
+ evidence: backtest showed ad-hoc re-widening added ~12% drawdown [internal backtest, 2026-03]
79
+
80
+ ## Related
81
+ ~ tried, reverted 2026-01: [adr] threshold-based fee checks
82
+ ```
83
+
84
+ **Maximum relevant context before the first grep — and no mistake paid for twice.**
85
+
86
+ No vector database, no service, no API key: your team's **decision log as small text
87
+ records in the repo** — decisions, domain definitions, anchors — merging like code and
88
+ readable in the PR diff, plus a local MCP server and three hooks.
89
+
90
+ [![tests](https://img.shields.io/github/actions/workflow/status/SantyagoSeaman/sidegraph/ci.yml?label=tests)](https://github.com/SantyagoSeaman/sidegraph/actions/workflows/ci.yml)
91
+ [![PyPI](https://img.shields.io/pypi/v/sidegraph)](https://pypi.org/project/sidegraph/)
92
+ ![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue)
93
+ ![License](https://img.shields.io/badge/license-Apache--2.0-green)
94
+ ![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)
95
+
96
+ Green `tests` badge = the full suite (ruff · mypy · pytest) passing in CI on every push.
97
+ Install: **`pip install sidegraph`** (or `uv tool install sidegraph`) — a pure-Python package
98
+ (`sidegraph` on PyPI: the MCP server, the three hooks, and the `sidegraph-*` CLIs), no service,
99
+ no API key.
100
+
101
+ ## Quickstart
102
+
103
+ Works cold: no existing ADRs required. No API key — the core loop is fully local
104
+ (one optional docs-analysis feature uses one; it's clearly marked below).
105
+
106
+ Already have ADRs or supported flow specifications? After building the graph, run
107
+ `sidegraph-bootstrap --host claude-code` to preview, review, anchor, and prove one record
108
+ through production retrieval. The 10–15 minute path is an explicitly unmeasured launch target;
109
+ see the [Bootstrap guide](docs/getting-started/bootstrap.md) for the six supported profiles,
110
+ host matrix, recovery contract, and reproducible dogfood path.
111
+
112
+ ```bash
113
+ # 1. Install the graph engine and build a graph over your repo (code or markdown)
114
+ uv tool install graphifyy # double "y" — that's the PyPI name; CLI is `graphify`
115
+ cd /path/to/your/repo && graphify update .
116
+ ```
117
+
118
+ `[mcp]` is an **optional** extra on `graphifyy` (`uv tool install "graphifyy[mcp]"`) — it adds
119
+ Graphify's *own* MCP server, a deeper structure-query layer over the same graph. It works fine
120
+ installed alongside Sidegraph; Sidegraph itself only ever reads `graph.json`, so the plain
121
+ install above is all it needs.
122
+
123
+ ```
124
+ # 2. Inside a Claude Code session in that repo: install the plugin — MCP server + all
125
+ # three hooks, wired automatically. Builds straight from this repo via uv; no PyPI
126
+ # publish needed.
127
+ /plugin marketplace add SantyagoSeaman/sidegraph
128
+ /plugin install sidegraph@sidegraph
129
+ ```
130
+
131
+ > **`@main` is a mutable ref.** These commands track the branch — fine for trying Sidegraph out, but pin a commit SHA (`…/sidegraph@<sha>`) for CI, a shared team setup, or a pilot you intend to measure. See [docs/reference/stability.md](docs/reference/stability.md).
132
+
133
+ ```bash
134
+ # 3. Install the CLIs + MCP server, then bootstrap the store in your repo
135
+ # (creates .sidegraph/, prints setup instructions)
136
+ uv tool install sidegraph # from PyPI — puts sidegraph-init / sidegraph-mcp / … on PATH
137
+ sidegraph-init
138
+
139
+ # Optional day-one seeding: import the rationale already sitting in your docstrings
140
+ sidegraph-import --dry-run
141
+
142
+ # Prefer the latest unreleased build straight from git instead of PyPI? Swap step 3 for:
143
+ # uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-init
144
+ ```
145
+
146
+ 4. **Name your domains** — turns the graph's communities into a described table of
147
+ contents. Tell your agent *"name my domains"* (or run `/sidegraph:name-domains`) and
148
+ pick one of the 2–3 ready-made sets it proposes — no long list to hand-curate. CLI
149
+ alternative for scripted/CI use: `sidegraph-domains bootstrap` + `sidegraph-ratify` —
150
+ see [naming your domains](docs/guides/naming-your-domains.md).
151
+
152
+ Then record your first decision in a session — *"record a gotcha: … anchor it to
153
+ `<function or heading>` in `<file>`"* — and watch it come back at the top of the context
154
+ next time the agent works near that code. The moment you accept a domain, `SessionStart`
155
+ starts answering from the top — a named table of contents instead of a bare community
156
+ listing. Full setup (hooks, env vars, Codex, and the source-checkout path for contributors):
157
+ [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md) and
158
+ [docs/getting-started/installation.md](docs/getting-started/installation.md). Existing rationale:
159
+ [docs/getting-started/bootstrap.md](docs/getting-started/bootstrap.md).
160
+
161
+ **See it in action.** Sidegraph dogfoods itself: a
162
+ [`demo` branch](https://github.com/SantyagoSeaman/sidegraph/tree/demo) will carry Sidegraph's
163
+ own decision store — decisions and facts distilled from this project's design notes and
164
+ anchored to its real code graph. Once it ships, clone it (`git clone -b demo …`), run
165
+ `graphify update .`, and query the corpus to watch retrieval, supersession chains, and
166
+ mistakes-first ranking on a genuine project. The `public`/plugin branch stays lean — the store
167
+ ships only to `demo`, so installing the plugin never drags it along. **The `demo` branch ships
168
+ with a later release** — it does not exist yet, so the link above and the clone command do not
169
+ resolve today; see the
170
+ [Bootstrap guide's reproduce-the-dogfood-path section](docs/getting-started/bootstrap.md#reproduce-the-dogfood-path)
171
+ for the same note.
172
+
173
+ ## Why
174
+
175
+ **For the team** — the senior engineer who never quits: what leaves with a person is not
176
+ code, it's the map of dead ends. Onboarding a new engineer and a new agent session is the
177
+ same problem, solved once. Settled questions stay settled — reopening one is a deliberate
178
+ supersede with a reason, not amnesia.
179
+
180
+ **For the project** — documentation that knows when it's stale: unlike a wiki, the memory
181
+ is anchored into the code and flags its own decay when the code moves on. Decisions are
182
+ made *in view of* prior decisions, so agent-speed production doesn't become agent-speed
183
+ architectural drift.
184
+
185
+ **For the business** — opex becomes an asset: today 100% of an agent's reasoning
186
+ amortizes to zero the moment the session ends. With Sidegraph every agent session leaves
187
+ a residue — decision capital that *compounds with project age* while everything else
188
+ (human memory, doc accuracy) decays. And it's the one investment model progress can't
189
+ commoditize: better models make derivable knowledge cheaper, not the non-derivable kind.
190
+
191
+ **For the process** — a sidecar, not a reform: it sits beside whatever spec/ADR flow you
192
+ already run, capture is a byproduct of ordinary sessions, and the single ritual is a
193
+ ratification gate — human by default, or a stamped auto-ratification policy where no human is
194
+ in the loop. Provenance on every record (who decided, when, on what evidence)
195
+ is a ready audit trail for the era of agent-made decisions.
196
+
197
+ One honest boundary, stated up front: this is not "cheaper agents in general." Memory
198
+ pays off where it replaces reading prose and where the answer isn't in the code at all;
199
+ on a large monorepo where two greps answer the question, it costs more than it saves.
200
+ What you buy is not speed — it's **owning your engineering judgment instead of renting it
201
+ back every session**. And writing decisions down is necessary but not sufficient: records
202
+ nothing surfaces at the moment of work simply go unread — delivery is the product.
203
+
204
+ Three kinds of tools circle this problem, and each misses it:
205
+
206
+ - **Agent memory** (mem0, Letta, Graphiti) remembers *conversations* — not decisions
207
+ bound to code entities.
208
+ - **Code graphs and indexers** (Serena, Potpie, repo maps) know *what calls what* — not
209
+ why it's built this way or what was learned the hard way.
210
+ - **ADR markdown** records the why — as prose in a folder nobody opens at the moment it
211
+ matters, with no link to the code it concerns.
212
+
213
+ None of them can answer: **"which decisions touch *this* function — and how did they
214
+ evolve?"** Sidegraph is built for exactly that question: decision memory, anchored to a
215
+ real code graph, with temporal history.
216
+
217
+ | | CLAUDE.md / AGENTS.md | Session memory tools | ADR markdown | Code-graph engines | OKF bundle | **Sidegraph** |
218
+ |---|---|---|---|---|---|---|
219
+ | Retrieved at the moment of need | ✗ whole-loaded, every session | partially | ✗ | ✓ structure only | partially — progressive disclosure | ✓ task-seeded, budgeted |
220
+ | Knows *what was tried and rejected* | ✗ | ✗ | sometimes | ✗ | ✗ | ✓ first-class `rejected` field |
221
+ | Anchored to the code it concerns | ✗ | ✗ | ✗ | ✓ | partially — concept links, not code | ✓ and survives refactors ([how](docs/guides/surviving-refactors.md)) |
222
+ | Temporal validity & supersession | ✗ edit-in-place | ✗ | sometimes a status header | ✗ | ✗ | ✓ append-only: `valid_from`/`valid_to`, `supersedes` chains |
223
+ | Human gate on what enters memory | ✓ | ✗ | ✓ | ✗ | ✓ curated like code | ✓ ratification loop |
224
+ | Lives in your repo, merges like code | ✓ | ✗ opaque store | ✓ | ✗ per-tool cache | ✓ | ✓ file-per-record log, ratified in the PR diff |
225
+ | Health is CI-gateable | ✗ | ✗ | ✗ | ✗ | ✓ `okf validate` | ✓ `sidegraph-verify` + `sidegraph-doctor` exit codes |
226
+
227
+ [OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/)
228
+ is complementary, not competing: it standardizes portable knowledge *bundles*, not decision
229
+ memory — and `sidegraph-export-okf` ships exactly that projection: the full store, history
230
+ included, as an OKF v0.1 bundle any OKF consumer can read.
231
+
232
+ The memory that matters most is what was tried, abandoned, and **why** — the mistake
233
+ you'd otherwise pay for twice. Sidegraph keeps it attached to the code and retrievable
234
+ long after everyone forgot.
235
+
236
+ ## How it works
237
+
238
+ ```
239
+ you work a session ──▶ Stop hook nudges the agent to distill durable decisions
240
+ │ propose_decisions / propose_domains (secrets redacted)
241
+ ▼
242
+ you ratify / drop ──▶ append-only decision log,
243
+ committed with your repo
244
+ │
245
+ next session ◀── SessionStart TOC anchored to entities in the
246
+ of named domains ◀── get_task_context ◀────── engine's graph (read-only);
247
+ mistakes first drill_down re-anchored after refactors
248
+ blind Read/Grep ──▶ nudged back to get_task_context (once per session)
249
+ ```
250
+
251
+ Under the hood there are two layers that age differently: the **structure** layer
252
+ (the code graph — entities, dependencies, communities: *the what*) and the **decision**
253
+ layer on top (*the why*). The graph is disposable — the engine regenerates it from source at any moment. The
254
+ memory must never be — so it lives in a separate store that nothing regenerates, and
255
+ re-anchors itself as the code moves. The unit of memory is an **entity, never a line
256
+ of code**: functions, classes, modules, document headings. Line numbers shift with every
257
+ edit; entities persist through them.
258
+
259
+ A third piece sits on top of both: named **domains**. Rather than hand-curate a
260
+ 200-line list of raw communities, you tell your agent *"name my domains"* and pick one of
261
+ 2–3 ready-made sets it proposes (`/sidegraph:name-domains`); each domain is a described area
262
+ — title, WHY-IT-EXISTS summary, optional subdomains — so the agent's first read of a session
263
+ is a table of contents it can answer from, not a blind community listing. A domain's
264
+ membership anchors to durable entities, not volatile community ids, so it **survives a fresh
265
+ clone and a graph rebuild** — the mind-model layer is repo-committed team memory, same as the
266
+ decisions. See [docs/concepts/mind-model.md](docs/concepts/mind-model.md).
267
+
268
+ That is the whole design in one line: **a decision log that stays alive — anchored
269
+ precisely to code entities, durably to named domains, delivered mistakes-first before
270
+ the agent's first grep, and merging like code.**
271
+
272
+ ## What gets stored
273
+
274
+ | Record | What it is |
275
+ |---|---|
276
+ | `Decision` | The memory: kind (`adr` / `lesson` / `constraint` / `gotcha`), context, choice, **rejected alternatives**, consequences, validity period, supersession chain, provenance |
277
+ | `Fact` | The evidence layer: compact, non-derivable knowledge — a benchmark, an external constraint, something trial-learned — that supports a decision or stands alone; razor: never "the code does X" |
278
+ | `Entity` | Durable identity for a code/doc entity — survives the engine's shifting node ids |
279
+ | `AnchorBinding` | The link between a decision and the entities it concerns — degrades gracefully on refactors, never guesses |
280
+ | `Domain` | A named, described area of the system (title + WHY-IT-EXISTS summary, optional subdomains) — what the `SessionStart` table of contents and `drill_down` are built from |
281
+
282
+ Append-only is a feature: a reversed decision is closed and superseded, never deleted —
283
+ *"tried before, abandoned because…"* stays retrievable via `get_entity_history`.
284
+
285
+ Facts ride the same append-only/ratification rules as decisions, plus a cascade: ratifying
286
+ or dropping a decision carries every still-pending fact that supports it along in the same
287
+ call — one verdict, both records move. Retrieval renders a live fact as an inline
288
+ `evidence: <statement> [<source>]` line under the decision it supports, and a standalone one
289
+ in its own `## Known facts` block — never displacing a mistake line. Details:
290
+ [docs/concepts/data-model.md](docs/concepts/data-model.md) and
291
+ [docs/guides/capturing-decisions.md#facts-the-evidence-layer](docs/guides/capturing-decisions.md#facts-the-evidence-layer).
292
+
293
+ ## MCP tools
294
+
295
+ | Tool | What it does |
296
+ |---|---|
297
+ | `get_task_context` / `query_structure` / `query_decisions` | Task-seeded context under a char budget, **mistakes ranked first** — the full slice, or either half alone |
298
+ | `drill_down` | Walk one named domain: summary, subdomains, members, decisions |
299
+ | `list_domain_candidates` | Read-only, path-grouped domain candidates — the machine half of naming a project |
300
+ | `list_domains` | Read-only listing of every domain (optionally filtered by status), with member counts and parent/child lineage |
301
+ | `add_decision` / `supersede_decision` | Append / reverse a decision (nothing is ever deleted) |
302
+ | `add_fact` / `supersede_fact` | Append / falsify a non-derivable fact — evidence for a decision, or standalone |
303
+ | `find_entity` / `get_entity_history` | Which decisions *and facts* touch this entity, and how they evolved |
304
+ | `retrieve_decisions` / `list_facts` | List current decisions / current facts |
305
+ | `propose_decisions` / `propose_domains` / `add_domain` | Draft a decision (plus attached or standalone facts) or name a domain, from a session or by hand |
306
+ | `supersede_domain` | Lineage-correct rename/re-scope of a domain: closes the old, writes a `proposed` successor |
307
+ | `list_proposed` / `ratify` | The human gate (by default — see `SIDEGRAPH_RATIFY_POLICY` in the configuration reference): review pending decisions, facts, *and* domains, accept/drop (dropping/accepting a decision cascades to its still-pending facts) |
308
+ | `sync_anchors` | Diagnostic/heal MCP counterpart to `sidegraph-sync` — re-anchor against the current graph and return the rebind report as data |
309
+ | `verify_store` | Read-only integrity lint of the store's canonical files — the MCP counterpart to `sidegraph-verify` |
310
+ | `add_anchors` | Append bindings to an existing decision or fact — in-place re-anchoring for the `heal-anchors` triage flow |
311
+
312
+ CLIs: `sidegraph-bootstrap` (reviewed cold-start import and production proof),
313
+ `sidegraph-init` (initialize the store), `sidegraph-domains` (bootstrap/name domains),
314
+ `sidegraph-import` (seed from existing rationale or ADR/spec markdown), `sidegraph-ratify`
315
+ (gate drafts), `sidegraph-sync` (re-anchor after a rebuild), `sidegraph-compact` (archive
316
+ closed decisions/domains), `sidegraph-verify` (lint store integrity; `--against <git-ref>`
317
+ for CI). See [docs/guides/ci-cd-maintenance.md](docs/guides/ci-cd-maintenance.md) for
318
+ GitHub Actions recipes built on `sidegraph-sync --check`/`sidegraph-verify`.
319
+ Reference: [docs/reference/](docs/reference/mcp-tools.md).
320
+
321
+ ## Works on code and on docs
322
+
323
+ Anchor decisions to functions and classes — or to **headings in your architecture
324
+ markdown** (LLM-free graph build, non-git folders supported). `sidegraph-import`
325
+ seeds the store from rationale already sitting in your sources: docstrings with zero
326
+ extra setup, and — via `--docs` — your existing ADRs and design specs, parsed into
327
+ anchored decisions deterministically, no LLM.
328
+
329
+ An optional **semantic pass** (`graphify extract`, one API key, cached per file) goes a
330
+ layer deeper on documentation: prose becomes `concept` nodes and thematic clusters, and
331
+ import picks up rationale from the documents themselves. Walkthrough:
332
+ [docs/guides/semantic-docs.md](docs/guides/semantic-docs.md).
333
+
334
+ ## Trust & privacy
335
+
336
+ - **Everything is local.** Sidegraph reads your repo and the engine's `graph.json`
337
+ (strictly read-only) and writes small human-readable JSON records inside your repo,
338
+ plus a local, gitignored index it can always rebuild. **Nothing leaves your machine** —
339
+ no network calls, no remote telemetry, no account. Sidegraph does keep local usage
340
+ diagnostics in that gitignored index (which stored memory was shown, and which files a
341
+ session touched afterwards) so you can tell which memory is earning its keep; they never
342
+ travel, and `SIDEGRAPH_TELEMETRY=off` disables them.
343
+ - **Secrets don't enter memory.** Proposed decisions and facts pass redaction before they
344
+ are stored; a ratification gate — human by default, or an opt-in stamped policy — controls
345
+ what the agent's drafts can persist.
346
+ - **Nothing is silently rewritten.** The store is append-only; every change of mind is
347
+ recorded as a supersession with its reason.
348
+
349
+ ## The engine underneath
350
+
351
+ Entity extraction and graph construction come from
352
+ [Graphify](https://github.com/safishamsi/graphify) (its LLM-free build covers both code
353
+ and markdown), and Sidegraph never re-implements them or writes into the engine's output.
354
+ The engine is optional at runtime: without a graph, records anchor to file paths and
355
+ domains and retrieval still works, but symbol-level anchors, communities, and moved-code
356
+ resolution need it (see the [operations reference](docs/reference/operations.md#the-graph-dependency-stated-plainly)). Everything the engine produces is derived
357
+ and regenerated on every rebuild; everything Sidegraph stores is deliberate, ratified,
358
+ and permanent. That split is the design: **own the memory, rent the graph.**
359
+
360
+ ## Status
361
+
362
+ v0.1.0, on PyPI as [`sidegraph`](https://pypi.org/project/sidegraph/) (`pip install sidegraph`)
363
+ — also installable via the Claude Code plugin or directly from git (see Quickstart).
364
+ Published by a tag-triggered GitHub Actions workflow that gates on the full test suite
365
+ (trusted publishing, no stored token). Interfaces may still move before 1.0. The full loop — capture, ratification,
366
+ mistakes-first retrieval, refactor-surviving re-anchoring, semantic docs layer, the
367
+ mind-model layer (named domains, `SessionStart` table of contents, `drill_down`), and now the
368
+ facts layer (evidence attached to a decision or anchored standalone) — is exercised
369
+ end-to-end on real code and ADR corpora (a 4,700-node Python trading system and a 15-document
370
+ architecture corpus), with 2,339 tests as of this writing (a public checkout runs 2,196: the
371
+ four release-mechanics test files that read `tools/` aren't shipped, since `tools/` itself
372
+ isn't shipped, and 3 internal-corpus calibration tests skip — they need a private design
373
+ corpus not included here). Exact counts drift as tests are added; the `tests` badge above
374
+ tracks the suite passing, not a frozen number.
375
+ Honest boundaries: not a code indexer, not general agent memory, not a graph engine —
376
+ decision memory over a rented graph, and nothing else.
377
+
378
+ ## Documentation
379
+
380
+ [Getting started](docs/getting-started/installation.md) ·
381
+ [Concepts](docs/concepts/decision-memory.md) ·
382
+ [Guides](docs/guides/capturing-decisions.md) ·
383
+ [Reference](docs/reference/mcp-tools.md) ·
384
+ [Integrations](docs/integrations/graphify.md) (Graphify · Claude Code · Codex) ·
385
+ [Verify your setup](docs/guides/verifying-your-setup.md) ·
386
+ [Operations](docs/reference/operations.md) ·
387
+ [Pilot kit](docs/pilot-kit/README.md) ·
388
+ [Engineering whitepaper](docs/whitepaper/index.md)
389
+
390
+ ## License
391
+
392
+ [Apache-2.0](LICENSE).
@@ -0,0 +1,42 @@
1
+ sidegraph/__init__.py,sha256=EpRyey-0I6jrJc_4fAiYxTWaOVAudfVmHGcxLPVnePw,743
2
+ sidegraph/anchoring.py,sha256=zf1ehBW4UTwPcu3-rVRVOJ2QJETmxeD6M_IdVnVVNjk,12542
3
+ sidegraph/capture.py,sha256=BwtqlhLoVSmn1QjOEwKTzpECLNyAYeYXXUR8U8Pk-6U,88759
4
+ sidegraph/cli.py,sha256=7QwJQmS0dpAOOJzxD9h6ggtE4dhBWzVP4X-k3K7hXgA,86429
5
+ sidegraph/config.py,sha256=AiewGrtF7VZIbh-TxMNw2bl7K7p-3dGmAgpERO6z9xc,6751
6
+ sidegraph/doc_import.py,sha256=sYmJjHA2uYY-YCuKGsOpJM-tI3wbsjsNDeFSWywpcfU,109351
7
+ sidegraph/doctor.py,sha256=DvB40Oc1wKNLE6RLUe9Xw0Kxz5E38QCBCf8eQZJ5pMU,70378
8
+ sidegraph/domains.py,sha256=ngLXUnPBojd_inSXlUaRAqpPHTAH0g4prcd9l-foaH0,47447
9
+ sidegraph/gitio.py,sha256=Wvqix3KAGpXZyoyDt5L9ol8hTqGVV56CPDe34xgKTsY,22892
10
+ sidegraph/importer.py,sha256=8bJpwlzHg6J0LZS284H-XGIwS4GbRH3OSHNayQUxQuU,10696
11
+ sidegraph/okf.py,sha256=ssP2HqYzYbghNEoWO_PMooQ3bzDu5cdePVnbxVPcP4E,19292
12
+ sidegraph/profiles.py,sha256=Zp9xZae4MsJaslAdeBRlziuTP1VkMVUECPey8EIfYaE,25789
13
+ sidegraph/retrieval.py,sha256=xVViVYOjtm6Qri-G7_t7Eg9hroA5s9lEDJ1JUqXWjCE,84478
14
+ sidegraph/schema.py,sha256=wCO71GUTWu_ngkJLzK3_uiIglaLq_fWvDssBk77WJ7A,17591
15
+ sidegraph/server.py,sha256=bEfuOPbZGRPz7539y4LfeXEAvklSSevGBZ5KuF7ffu4,124061
16
+ sidegraph/store.py,sha256=f-cYFGqmNTXNEEOxBvvShA5Bcpb9Jy3OxljONcoOHic,188397
17
+ sidegraph/sync.py,sha256=hYrFXIZ7hitAjckWr3cxB_X6hk2Up9RpAn-66oCb96c,49386
18
+ sidegraph/verify.py,sha256=8ruFh8aJDp2Jy8Gv0TxvYNH5DATLYweq3WOskidKGJU,53179
19
+ sidegraph/bootstrap/__init__.py,sha256=CRYUbO4AHysyN68zIVTmUFJ5HzmKUBZ_25KmwH6Zchc,912
20
+ sidegraph/bootstrap/apply.py,sha256=UCGrma61Ynbvfx_9r8Q91RLNCj8TmtuuihlgXo6SsLY,21118
21
+ sidegraph/bootstrap/catalog.py,sha256=0X6wH5KYc2NEF0pvpejR-FbU2uI02Mo68ISk2ZqM2ek,3512
22
+ sidegraph/bootstrap/cli.py,sha256=xm3rL8o_byt1i7q5sfJ1h1zbCgo8m8Ca0MfdGsInikw,30445
23
+ sidegraph/bootstrap/integrations.py,sha256=i8BmcAE4lVf9b7Q4qQwIHqqdOpWAr5osJLHu98KDtaM,6576
24
+ sidegraph/bootstrap/model.py,sha256=t86tgoPh1SbR_qt_WmSpVVNjnrZEaWGEiT1t0J7JJ2I,9291
25
+ sidegraph/bootstrap/planner.py,sha256=XOUAmv5Wd7At8qp3PRmveNYAOUHn-fM3InAL4peMRMM,14263
26
+ sidegraph/bootstrap/proof.py,sha256=Iy3vayl17tJSGRWMv8mUf4ecEZi0TO4ibkcdb2wbUX0,3974
27
+ sidegraph/bootstrap/review.py,sha256=EXXe80AnJ8ZjnJFdv8MXeCw5MPqF3RdfvLFdM4RVdLU,13345
28
+ sidegraph/bootstrap/scan.py,sha256=Vo9-6cknnmkLGBLleR1sKYAZzntiq4txanx3WR485TI,9538
29
+ sidegraph/engine/__init__.py,sha256=75Rmx2mGpRysHloLu3F3dZDjUnjz7bkdJO4g-MsA8dk,433
30
+ sidegraph/engine/reader.py,sha256=hzCvc-K36B-JVCuZRTpkYSiKijSBLSZTQaoM8FHTf0U,16145
31
+ sidegraph/host/__init__.py,sha256=vocHITFQUJJ9qXEU3gC_7DSxywEBuyVk72X4R8vcK08,387
32
+ sidegraph/host/hooks.py,sha256=Sw8Gv4nSXmztAAfKvmr2-AySVhqlE_cTLbNEhEXXmfM,38491
33
+ sidegraph/viz/__init__.py,sha256=jSG9LiVxjFr0g9o0UdDYse5-67wXZiTEIMric0JBUzU,161
34
+ sidegraph/viz/model.py,sha256=dnk8LJj-cofz53o4FWRGYKgrhaOEe3bYGQEeZDGCkKU,9658
35
+ sidegraph/viz/render.py,sha256=usz1BTrc6-k95o3m9sW_L6QWdvTLTfJEYa0qk-FncbU,3906
36
+ sidegraph/viz/template.html,sha256=Jz-oBGfhulbbsV7tNhKA_NP-XMD1JpVDXbS24z84d1E,5573
37
+ sidegraph/viz/assets/vis-network.min.js,sha256=V2u4h3M-sBu1LudbkO9G2BhFTeX921thb7iimNMHyhI,702611
38
+ sidegraph-0.1.0.dist-info/METADATA,sha256=WpbIIJxRK2P9GPXEZT5X_i5vqoZgZKOnA6dYqwMttTo,24781
39
+ sidegraph-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
40
+ sidegraph-0.1.0.dist-info/entry_points.txt,sha256=LJId_KwrB2dcSTqx7qlJZZTiJ4bwfL1TS1TyciBye08,830
41
+ sidegraph-0.1.0.dist-info/licenses/LICENSE,sha256=IcNJvaMW6W6rlLfXrKY5kA1U1HjuByUccsPnV6OaEJU,11352
42
+ sidegraph-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.32.3
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,18 @@
1
+ [console_scripts]
2
+ sidegraph-blame = sidegraph.cli:blame_main
3
+ sidegraph-bootstrap = sidegraph.bootstrap.cli:main
4
+ sidegraph-compact = sidegraph.cli:compact_main
5
+ sidegraph-doctor = sidegraph.cli:doctor_main
6
+ sidegraph-domains = sidegraph.cli:domains_main
7
+ sidegraph-export-okf = sidegraph.cli:export_okf_main
8
+ sidegraph-import = sidegraph.cli:import_main
9
+ sidegraph-init = sidegraph.cli:init_main
10
+ sidegraph-mcp = sidegraph.server:main
11
+ sidegraph-pre-tool-use = sidegraph.host.hooks:pre_tool_use
12
+ sidegraph-prepare-commit-msg = sidegraph.cli:prepare_commit_msg_main
13
+ sidegraph-ratify = sidegraph.cli:ratify_main
14
+ sidegraph-session-start = sidegraph.host.hooks:session_start
15
+ sidegraph-stop = sidegraph.host.hooks:stop
16
+ sidegraph-sync = sidegraph.cli:sync_main
17
+ sidegraph-verify = sidegraph.cli:verify_main
18
+ sidegraph-viz = sidegraph.cli:viz_main