File Anchors

File anchors create direct links between the knowledge in your database (decisions and patterns) and the source code in your repository. By anchoring items to specific files or directories, you make your context highly queryable and context-aware.

Managing Anchors

You can manage file anchors using the dedicated anchor command, or attach them inline when logging new decisions.

1. Adding Anchors

To attach file or directory paths to an existing decision or pattern: 

engrams anchor add --type decision --id 4 --path src/db.rs --path src/models.rs
engrams anchor add --type pattern --id 1 --path src/controllers/

Alternatively, you can attach anchors immediately when creating a decision: 

engrams decision log --summary "Use AES-GCM-256 encryption" --anchor src/db.rs --anchor src/models.rs

2. Listing Anchors

To view all file anchors currently attached to an item: 

engrams anchor list --type decision --id 4

The command returns a JSON array of registered anchors: 

[
  {
    "path": "src/db.rs",
    "timestamp": "2026-07-12T10:15:30Z"
  },
  {
    "path": "src/models.rs",
    "timestamp": "2026-07-12T10:15:30Z"
  }
]

3. Removing Anchors

To remove a specific file anchor from an item: 

engrams anchor remove --type decision --id 4 --path src/models.rs

Path Normalization & Directory Resolving

Engrams automatically normalizes paths to keep them consistent across different environments:

  • Relative path prefixes like ./ are automatically stripped (e.g. ./src/db.rs becomes src/db.rs).
  • If you anchor an item to a directory (e.g. src/controllers/), any query for file paths inside that directory (e.g. src/controllers/auth.rs) will match that anchor.

Why Anchors Matter

By building a map of file anchors, the CLI enables features like:

  • Relevant Context Queries: Retrieve only the decisions/patterns relevant to the files you are currently staging or modifying (see Context Relevance).
  • Drift/Staleness Auditing: Automatically check if files associated with a decision have been modified in Git since the decision was committed (see Database Auditing).