weavatrix-memory

Bitemporal, evidence-carrying agent memory with a hard token budget — written in Rust, exposed to Node.js and Bun through Node-API.

It answers two different questions that most memory systems conflate: what was true at time T, and what did the agent know at time T. Every fact carries both axes plus the evidence behind it, so a wrong answer can be traced to the fact that caused it.

No LLM, no vector database, no network service, no async runtime, no external graph database.

npm install weavatrix-memory
# or
bun add weavatrix-memory

const { Memory } = require('weavatrix-memory')

const memory = new Memory({
  knownAt: 20,
  nodes: [
    { id: 'task:1', kind: 'task', label: 'Fix query' },
    { id: 'file:1', kind: 'file', label: 'query.js' },
  ],
  facts: [{
    id: 'fact:1',
    source: 'task:1',
    relation: 'depends_on',
    target: 'file:1',
    validFrom: 10,
    recordedAt: 12,
    agentId: 'agent:1',
    sessionId: 'session:1',
    evidence: [{ kind: 'test', source: 'query-suite' }],
  }],
})

const context = memory.compileContext({
  seeds: ['task:1'],
  validAt: 20,
  knownAt: 20,
  tokenBudget: 2_000,
  maxDepth: 2,
})

context.view      // the facts and nodes that survived both time filters
context.graph     // their projected provenance graph
context.receipt   // exactly why this bundle looks the way it does

The two time axes

| Axis | Field | Question it answers | | --- | --- | --- | | Valid time | validFrom, validUntil | When was this true in the world? | | Known time | recordedAt | When did the system learn it? |

A query supplies both (validAt, knownAt). Asking "what did we believe last Tuesday about the state of the repository last Monday" is a single query, not a reconstruction.

All timestamps are integer Unix microseconds and must stay inside JavaScript's safe-integer range; a non-integer or out-of-range value is rejected, never rounded.

Input

MemoryNode

| Field | Type | Notes | | --- | --- | --- | | id | string | Stable identity. | | kind | string | Entity category. | | label | string | Human-readable name. | | repository, branch | string? | Scope, filterable at query time. | | attributes | Record<string, string>? | |

MemoryFact

| Field | Type | Notes | | --- | --- | --- | | id | string | | | source, target | string | Node ids. | | relation | string | Relation type; filterable at query time. | | validFrom | number | Start of valid time. | | validUntil | number? | Open-ended when omitted. | | observedAt | number? | | | recordedAt | number | Known time. | | agentId, sessionId | string | Who asserted it, in which session. | | confidence | number? | Basis points, 0 … 10000. | | evidence | Evidence[] | { kind, source, locator?, digest? } | | supersedes | string? | The fact this one replaces. |

MemoryInput

{ nodes, facts, knownAt, sourcePosition? }

API

new Memory(input)

Validates the whole projection up front: unknown node references, a confidence above 10,000 basis points, and malformed timestamps all throw here rather than at query time.

| Member | Returns | Notes | | --- | --- | --- | | nodeCount | number | | | factCount | number | | | view(validAt, knownAt) | MemoryView | { nodes, facts } after both time filters. | | graph(validAt, knownAt) | object | The projected provenance graph for that same instant. | | compileContext(request) | ContextBundle | See below. |

ContextRequest

| Field | Type | Default | Effect | | --- | --- | --- | --- | | seeds | string[] | required | Where the walk starts. | | validAt | number | required | Valid-time instant. | | knownAt | number | required | Known-time instant. | | tokenBudget | number | required | Hard ceiling. The compiler stops selecting facts before exceeding it. | | maxDepth | number | 2 | Traversal depth from the seeds. | | relations | string[] | all | Restricts which relations may be traversed. | | repositories, branches | string[] | all | Scope filters. |

ContextBundle

{ view, graph, receipt }.

The receipt is the point. It states what the compiler did, so a context can be audited rather than guessed at:

| Field | Meaning | | --- | --- | | validAt, knownAt, sourcePosition | The instant this bundle describes. | | estimator, tokenBudget, estimatedTokens | Which estimator ran, the ceiling, and what was actually spent. | | examinedFacts, selectedFacts | How much was considered versus kept. | | omittedByBudget | Facts dropped because the budget ran out. | | excludedByScope | Facts dropped by relation, repository, or branch filters. |

A context that is missing something always says which of the two reasons applies.

Errors

| code | Cause | | --- | --- | | InvalidArg | Unknown field, fact referencing an undeclared node, confidence above 10,000 basis points, timestamp that is not a safe integer, empty seed list. | | GenericFailure | Node or fact count exceeding the addressable range. |

What ships

| | | | --- | --- | | Runtimes | Node.js 18+ (Node-API 8), Bun 1.4+ | | Platforms | Windows x64/arm64, macOS x64/arm64, glibc Linux x64/arm64 | | Install script | none | | Network at install | none | | Runtime dependencies | none | | Platform packages | none — all six bindings are in this one tarball |

Measured, without fake equivalence

benchmark/RESULTS.md is generated from the weavatrix-benchmarks harness.

There is no zero-network npm package that returns this contract, so the comparison uses graphology as a topology-only floor — and it wins:

| Contract | Node 24 | Bun 1.3 | | --- | ---: | ---: | | Depth-2 neighborhood node ids on a 10,000-node chain | graphology 20x faster | graphology 9x faster |

That row is published rather than hidden, and it is not a like-for-like result. graphology performs the overlapping topology query and nothing else. Weavatrix additionally filters valid time and known time, checks scope and relations, enforces the token budget, selects evidence-carrying facts, materializes the provenance graph and the receipt, crosses Node-API, and serializes the bundle. A depth-2 walk on a chain also reaches only five nodes, so the competitor's median sits at timer resolution: read it as "graphology wins the topology-only query", not as a calibrated multiple.

The Rust repository separately keeps equal-contract comparisons against agentic-memory, where the depth-2 context kernel at 100,000 nodes returned the same result 26.1x faster — and where the bulk constructor lost by 1.68x. That losing row is published too.

Memory owns its repository, package, release evidence, and MIT license, and can be used entirely on its own.

Repository: Weavatrix/weavatrix-memory · Rust crate: crates.io/crates/weavatrix-memory · License: MIT