Local AI context (zero LLM cost)¶

This repo ships a local-first AI context stack for coding agents. It improves orientation, reduces token waste, and adds optional static quality checks — without paid LLM APIs, OpenAI/Anthropic/Gemini keys, or hosted AI review services.

What is included¶

Tool	Purpose	LLM/API cost
REPO_INDEX.md	File tree + MCP export scan	None (Node only)
Graphify (`--code-only`)	AST code graph, call/import map	None (tree-sitter, local)
Semgrep (optional)	Community static security rules (bash/python/yaml)	None (local CLI or Docker)

Generated artifacts live in ai-context/ and graphify-out/ — gitignored, never committed.

Prerequisites¶

Node.js 22+
Graphify: Python 3.10+ and pipx install graphifyy or uv tool install graphifyy — or npm run ai:setup
Semgrep (optional): pipx install semgrep or Docker

CI does not install or run Graphify on the VPS.

Commands¶

npm run ai:context           # force regenerate
npm run ai:context:if-stale  # stale-only refresh (automation)
npm run ai:context:verify    # verify no secrets in output
npm run ai:quality           # Semgrep (bash/python/yaml rules)
npm run ai:doctor            # health check
npm run ai:repair            # safe auto-repair
npm run ai:setup             # full install after clone

Health check and repair¶

Command	Purpose
`npm run ai:doctor`	Report Graphify CLI, graph files, IDE skills, REPO_INDEX
`npm run ai:repair`	Fix missing graph/skill/index when CLI is available
`npm run ai:setup`	Full install (pipx + skills + graph) — run once after clone

Automatic on Cursor session: repair if fixable; banner if still unhealthy after repair.

Escape hatches: AI_CONTEXT_SKIP=1 skips stale refresh; AI_AUTO_SETUP=1 allows ai:repair to run full ai:setup when CLI missing.

IDE support¶

npm run ai:setup installs Graphify skills for Cursor, Gemini CLI, and Antigravity.

IDE	Config files	Agent behavior
Cursor	`.cursor/rules/graphify.mdc`, `ai-context-auto.mdc`, `infra-mcp-routing.mdc`, `ci-red-pipeline.mdc`, `no-cursor-commit-attribution.mdc`; `sessionStart` hook	Graphify query-first; auto doctor/repair on session; MCP routing; no Cursor co-author trailers
Gemini CLI	`GEMINI.md`, `.gemini/skills/graphify/`	BeforeTool hook (patched at setup)
Antigravity	`.agents/rules/`, `.agents/workflows/`, `.agents/skills/`, `AGENTS.md`	`/graphify` and `/ai-context` workflows

Full three-repo Cursor map: Cursor agent setup.

After clone on a new machine: npm run ai:setup.

Automatic refresh¶

Trigger	When
Cursor session	`.cursor/hooks.json` → `sessionStart`
Claude Code session	`.claude/settings.local.json` → `SessionStart` (per-machine, not in the repo)
`git pull` / merge	`.githooks/post-merge`
Branch checkout	`.githooks/post-checkout` (branch checkouts only — `$3 = 1`)

npm install sets core.hooksPath to .githooks locally via postinstall.

Stale = ai-context/REPO_INDEX.md missing, graphify-out/GRAPH_REPORT.md missing, or any source file newer than ai-context/.source-stamp.json.

"Source file" means the whole repo minus the skip list in scripts/lib/ai-context-staleness.mjs (which mirrors .graphifyignore). This replaced a hand-maintained allow-list that never included ship/, so ship-only commits left the graph stale with no signal. Watching by exclusion means a new top-level directory is covered without editing a list.

The session hook (scripts/ai-context-on-session.mjs, shared by Cursor and Claude Code) does the cheap staleness check in the foreground, then rebuilds detached — guarded by graphify-out/.rebuild.lock, logged to graphify-out/.rebuild.log. It always exits 0; a context refresh never blocks a session from opening.

Force full rebuild: npm run ai:context

Excluded paths¶

These are never indexed (.graphifyignore + .gitignore):

Pattern	Reason
`.env`, `.env.`, `.enc.env`	Credentials
`local/`, `secrets/`, `secrets/plain/`	Local secrets
`node_modules/`, `site/`, `dist/`	Dependencies / build output
`ai-context/`, `graphify-out/`, `.graphify/`	Generated artifacts
`plane/plane-app/`	Upstream Plane app checkout
`mcp-server/node_modules/`	MCP build deps

How agents should use this¶

Before broad file reads, run graphify query "<question>" or check ai-context/REPO_INDEX.md.
If artifacts are missing or stale, run npm run ai:context.
Prefer graph/symbol context over reading entire files.
Never send .env, secrets/, local/, SOPS keys, or credentials to external tools.

Idea → Done conductor¶

Platform vision for automatic work delivery (intake → approve → Plane → Forgejo PR → Woodpecker → ship): architecture/idea-to-done.md. Update that page when refining stages or open decisions; do not invent a parallel orchestration product that replaces Plane/Forgejo/Woodpecker.

Patterns to borrow (not products)¶

Research notes from external tooling evaluations — steal patterns, do not install unless an open decision says so:

→ architecture/agent-patterns-borrow.md (symbolic memory, compound loop, prefix-cache discipline, safe outputs, Playwright-over-Cypress, …)

Future: team agent memory (not started)¶

Optional later — do not install yet

TencentDB Agent Memory (MIT) is a team memory hub: Chat Memory, Skills, LLM-Wiki, Code-Graph, plus symbolic short-term offload and layered long-term recall. First-class plugs are OpenClaw and Hermes, not Cursor / Antigravity / Gemini.

Why park it (today): Graphify already covers code graph (and optional wiki); Plane is the shared ticket/state bus for Idea → Done; this repo’s AI context stack stays local / zero LLM cost. Adopting the product now would add a Gateway + LLM extraction path and duplicate assets we already own.

When to reopen: if we run OpenClaw/Hermes workers, or need cross-session chat/persona memory that Plane + docs cannot hold. Until then, steal ideas only (Mermaid/task-map offload, layered recall) — see agent patterns to borrow. Do not wire the npm package or Gateway into the platform.

Tracked as open decision D37 on Idea → Done.

Semgrep¶

npm run ai:quality runs community rules: p/default, p/bash, p/python, p/yaml.

Excludes: node_modules/, site/, secrets/, local/, graphify-out/, ai-context/.

Install: pipx install semgrep or use Docker. Exits 0 with a warning if unavailable.

CI¶

Woodpecker runs a non-blocking ai-context-validate step that checks exclude rules in .graphifyignore and .gitignore.

Separately, the build-docs step installs Graphify and publishes interactive HTML (--code-only, still zero LLM cost) under:

Path	Source
`/graph/`	Hub + live project table
`/graph/infra-devops/`	This repo
`/graph/portfolio/`	`rafael.gonzalez.albes/portfolio` (when `.graphifyignore` present)

Registry: config/graphify-docs-projects.yml. Sibling clones need Woodpecker secret forgejo_clone_token. Daily cron name: graphify-docs-daily. See Code graphs.

Agent-facing artifacts (graphify-out/, ai-context/) remain local and gitignored — CI does not commit them.

Plane ticket

Plane was unreachable when this feature landed; create a platform ticket retrospectively if the board should track the docs graph publish work.

Why zero LLM/API billing¶

Graphify --code-only uses tree-sitter AST parsing only
REPO_INDEX.md is built with Node fs + regex — no network
Semgrep community rules run locally — no Semgrep Cloud account