Codebase Bindings

Link decisions and patterns to code paths using glob patterns. When AI agents edit files, bound context surfaces automatically — no manual prompting and no loading the entire knowledge base.

Why bindings?

Without bindings, getting the right context to an AI agent requires a choice between two bad options: load your entire knowledge base into every prompt (expensive and noisy), or manually remind the agent of relevant decisions every time you start a task (tedious and easy to forget). Bindings solve both problems. They create a permanent map between your project's knowledge and your project's code — so the right context surfaces automatically, and only when it's needed.

Cost savings

The difference in token usage between a project with and without bindings compounds quickly as the knowledge base grows.

Scenario	Without Bindings	With Bindings
Project has 60 decisions	~12,000 tokens loaded per session	~800 tokens for the 4–6 relevant to the files being touched
Creating a new API route	AI searches broadly; retrieves ~15 items "to be safe"	get_context_for_files returns exactly the decisions bound to src/api/routes/**/*.py
Junior dev touches a config file	Gets overwhelmed with unrelated DB and auth decisions	Gets only the 2 decisions bound to src/config/**/*.py
20-step coding session	200,000+ tokens consumed on knowledge-base context	15,000–20,000 tokens — same session, ~90% reduction

Beyond direct API cost, a leaner context window means the AI can hold more of the actual task in focus — fewer decisions get quietly dropped as the window fills up on long sessions.

How it works

Maya has been the lead backend developer on her team's healthcare API for two years. In that time, the team has made dozens of hard-won decisions — some after painful production incidents, some after long architecture debates. They're all logged in Engrams: HIPAA logging rules, the repository pattern requirement, JWT role-checking, UTC date formats, structured error shapes.

One afternoon, she spends twenty minutes setting up bindings. No code, just mapping:

Maya: "Bind decision 7 and pattern 5 to all route files under src/api/routes.
       Bind decisions 24 and 23 to everything under src/db.
       Bind decisions 23 and 31 to all model files."

AI:   Bindings created:
      D-7  (JWT auth)              → src/api/routes/**/*.py
      SP-5 (Structured errors)     → src/api/routes/**/*.py
      D-24 (Repository pattern)    → src/db/**/*.py
      D-23 (UTC datetimes)         → src/db/**/*.py
      D-23 (UTC datetimes)         → src/models/**/*.py
      D-31 (No PII in repr/str)    → src/models/**/*.py

Each binding uses a glob pattern. src/api/routes/**/*.py means every Python file nested under that directory — including files that don't exist yet. She doesn't touch these again. The bindings are set.

---

Three weeks later, Alex joins the team. It's his first day. His first task: add an endpoint to retrieve a patient's recent appointments.

He opens his AI coding assistant and types: "Create src/api/routes/appointments.py with a GET endpoint that returns a patient's appointments from the database."

Before writing a single line of code, his AI agent identifies the files it's going to create and touch. It calls get_context_for_files with those paths. Maya's bindings activate:

src/api/routes/appointments.py is bound to:
  D-7:  JWT required; check that the requesting user has access to this patient's records
  SP-5: All errors must use {"error": "...", "code": "...", "request_id": "..."}

src/db/repositories/appointments.py is bound to:
  D-24: All queries go through Repository classes — no direct ORM calls in routes
  D-23: All datetime fields must be stored and returned as UTC ISO 8601

The agent writes an endpoint with JWT validation, role checking, a repository-pattern DB call, UTC-formatted dates, and structured error responses.

Alex didn't know any of those rules. He didn't read the architecture docs. He didn't ask Maya. The bindings carried two years of institutional knowledge directly into his first pull request — automatically, silently, and at a fraction of the token cost of loading the full knowledge base.

Creating bindings

You: "Bind the SQLAlchemy decision to the data layer, the JWT auth
      decision to the auth module, and the error handling pattern to
      all route files"

AI:  Bindings created:
     Decision #24 (SQLAlchemy ORM) → src/db/**/*.py
     Decision #7  (JWT auth)       → src/auth/**/*.py
     Pattern #5  (Error handling)  → src/api/routes/**/*.py

Binding management

Bindings can become stale when files are moved or deleted. Use verify_bindings (with mode='full' for filesystem scan or mode='staleness' for timestamp check) to audit, and suggest_bindings to automatically propose new bindings based on pattern analysis.

MCP tools

• bind_code_to_item — create a binding (supports glob patterns)
• get_bindings_for_item — list all bindings for a decision or pattern
• get_context_for_files — retrieve all context bound to a set of files
• verify_bindings — check binding health: mode='full' for filesystem scan, mode='staleness' for timestamp-based check
• suggest_bindings — propose bindings based on analysis
• unbind_code_from_item — remove a binding