ai-hist weekly downloads statistics

ai-hist

The local history TypeScript SDK, Node CLI, and MCP server. Storage and local ingestion use one mandatory ai-hist-native Node-API engine. Optional source and destination plugins compose through public interfaces; no JavaScript SQL or commercial dependency is required by this package.

All APIs are async. listSessionCatalog and listSessionCatalogPage are cache-only. discoverSessions is shallow discovery. hydrateSession is targeted evidence acquisition for one existing catalog row. It returns hydrated, updated, unchanged, or capability_limited, an indexed source stamp, evidence counts, related native session IDs, and bounded-work metrics. Targeted remote hydration uses scope: 'remote' and an explicitly configured source plugin registry: Claude web sessions can return capability: 'full' after complete teleport evidence is acquired; Codex cloud tasks return partial when their supported unified diff is indexed or shallow_only when no richer evidence is exposed. Partial results retain discoveryState: 'shallow'. sync is full ingestion. Missing databases return empty read results; they do not trigger provider I/O.

SOURCES and CATALOG_SOURCES are immutable runtime registries corresponding to the exported Source and CatalogSource types. Use isSource(value) or isCatalogSource(value) to validate untyped input without maintaining a copied provider list. CATALOG_SOURCES is the same list as SOURCES: every source can identify a catalog entry.

Session discovery, listing, search, recent history, statistics, and sync accept scope: 'local' | 'remote' | 'all'. Scope defaults to local, preserving offline behavior and making provider-cloud access explicit. The CLI exposes the same mutually exclusive --local, --remote, and --all flags; omitting them is equivalent to --local.

Cached reads preserve the requested scope and never consult commercial auth. Stored remote history can be queried with absent, malformed, expired, or ambiguous credentials. Remote acquisition requires an explicitly loaded plugin registry. Install @relayhistory/provider-sources for Claude web/Codex cloud. Installing a package does not register it or inspect auth.

The CLI accepts --config history.json on acquisition commands. Config lists explicit plugin modules/options; --source-connector selects their IDs and is repeatable. --no-source-connectors disables remote acquisition. MCP uses AI_HIST_PLUGIN_CONFIG and source_connectors. Scope defaults to local even with plugins configured. See source plugins. Native contract 14 rejects old addons that lack the source/delivery boundary.

Catalog pages, discovery results, statistics, and sync results echo the requested scope, and discovery results additionally report locationsRun — the connector locations that actually executed. History and catalog rows have locations, containing local, remote, or both, so an all query still returns one logical session while preserving where it was found. resumeCommand() returns null for a remote-only history row rather than emitting a local CLI command; an empty locations array retains legacy local behavior for rows written before provenance tracking.

The event primitive is page-based and uses { tsMs, id } as a deterministic cursor. The sessionEvents async iterator walks pages without accumulating a large transcript. getSessionEvents is an explicit collecting convenience.

Tool calls and file edits follow the same page / iterator / collect trio (getSessionToolCallsPage, sessionToolCalls, getSessionToolCalls, and the ...FileEdit... equivalents), and take both a source and a session ID because provider session IDs are not unique across providers. The source is half of that identity, so one outside the Source set raises InvalidArgumentError instead of reading as an empty session. Their cursor is { tsMs: number | null, id: number }: a record may be indexed without a timestamp, and undated records are ordered last. Feeding a cursor back in accepts either spelling of that tail — tsMs: null as emitted, or no tsMs at all after a transport that drops nulls — so a printed or JSON-serialized cursor returns unedited. Stored provider JSON is parsed into args and structuredPatch; a value that is absent or unparseable becomes null while the raw string stays available as argsJson and structuredPatchJson, so an unreadable payload never fails a page. parseStoredJson(raw) is that same parse, exported for callers that hold a raw stored string of their own: it returns the parsed value, or null for anything that is not a parseable string.

Session topology

Sessions that delegate to subagents form a tree, and it is queryable:

Each SessionRelationship reports its identityStatus. observed means the provider named the child, so childSessionId is a real session id and childHasEvents says whether its events are independently addressable through getSessionEventsPage. unlinked means the provider recorded a delegation but no stable child identity: childSessionId is null, the child's output stays attributed to the parent, and the row keeps the evidence (evidenceKind, evidenceLocator, evidenceRef) that established it. An identity is never synthesized.

capabilities.stableChildIdentity tells you what to expect from the provider before you read a single row: always for Codex, sometimes for Claude — only provider versions that emit a per-child agentId name the child — and never for the remaining sources.

getSessionTree returns pre-order nodes (the root first), the unlinked evidence found at any depth, and diagnostics. nodes[0] is always the root, so a session with no children — and a database that does not exist yet — comes back as a one-node tree rather than an empty one. Children are ordered by (spawnedAtMs, relationshipUid) with null spawn times last, so repeated calls against the same database return identical results.…

Description from the npm listing.