@hexis-ai/engram-core

Pure scoring algorithms for AI session search.

A Session is a sequence of (tool, resources) steps with optional participants. This package builds an offline index over a corpus of sessions and ranks candidates against a query session.

Install

npm i @hexis-ai/engram-core

Usage

import { buildIndex, search } from "@hexis-ai/engram-core";

const corpus = [
  { id: "h1", daysAgo: 2, steps: [
    { tool: "Read", resources: ["file:src/x.ts"] },
    { tool: "Edit", resources: ["file:src/x.ts"] },
  ]},
];

const index = buildIndex(corpus);

const ranked = search(
  [{ tool: "Read", resources: ["file:src/x.ts"] }],
  index,
  { queryParticipants: [] },
);

Algorithm summary

| Signal | Method | Default weight | |---|---|---| | Tool sequence | TF-IDF Weighted LCS over tool names | 0.35 | | Resources | F1 over IDF-weighted resource sets | 0.25 | | Participants | F1 over IDF-weighted participant sets | 0.15 | | Centrality | PageRank on resource co-occurrence graph | 0.15 | | Recency | Exponential decay (half-life 14 days) | 0.10 |

explainScore() returns a per-component breakdown for any candidate so the score is fully inspectable.

License

MIT