Context Relevance & Git Integration

Find architectural decisions and codebase patterns relevant to the files you are currently modifying. By querying anchors matched to specific file paths or staged git files, you can quickly review relevant constraints.

How it works

Both decisions and patterns can have one or more file anchors attached to them. Anchors can point to files (e.g. src/main.rs) or directories (e.g. src/ops/).

The relevant command scans these anchors for any matches. If an anchor is a directory, it matches any files inside that directory recursively.

Retrieval Options

1. Query by Specific Paths

Retrieve decisions and patterns matching one or more specific files or directories:

engrams relevant src/db.rs tests/cli.rs

2. Query by Staged Git Files (--staged)

An extremely powerful workflow is checking for relevant context based on your current Git staging area. Running:

engrams relevant --staged

calls git diff --cached --name-only behind the scenes to list all staged files, and returns the decisions and patterns anchored to them.

3. Include Superseded Context (--all)

By default, the relevant command only returns active decisions. If you want to include historical/superseded decisions to see how an area of the codebase evolved, pass the --all flag:

engrams relevant src/auth.rs --all

Example Output

The command returns a JSON object containing lists of matching decisions and patterns:

{
  "decisions": [
    {
      "id": 4,
      "uuid": "f5e6d7c8-b9a0-4f1e-9d2c-8b7a6f5e4d3c",
      "summary": "Encrypt session tokens in SQLite",
      "rationale": "Protect user authentication tokens at rest",
      "implementation_details": "Use AES-GCM-256 via AEAD",
      "tags": ["security", "auth"],
      "timestamp": "2026-07-12T10:00:00Z",
      "status": "active",
      "commit_sha": "f1a2b3c4",
      "pr_urls": [
        "https://github.com/stevebrownlee/engrams-cli/pull/88"
      ],
      "anchors": [
        "src/db.rs"
      ]
    }
  ],
  "patterns": [
    {
      "id": 1,
      "uuid": "a1b2c3d4-e5f6-7a8b-9c0d-1e2f3a4b5c6d",
      "name": "Database Transaction Wrapper",
      "description": "Always execute writes inside a transaction block",
      "tags": ["db", "concurrency"],
      "timestamp": "2026-07-12T09:30:00Z",
      "pr_urls": [],
      "anchors": [
        "src/db.rs"
      ]
    }
  ]
}

Git Hook & Agent Workflows

You can easily integrate engrams relevant --staged into a pre-commit hook to block commits or issue warnings if a developer modifies files in violation of active codebase patterns or decisions.

For AI agents, running engrams relevant --staged is the recommended practice right before they make or propose a code change. This guarantees they are aware of all anchors associated with the files they are touching.