perf(memory): optimize fact operations (~30% faster writes, ~56% faster reads)

[willkelly]

Summary

This PR significantly improves the performance of the memory package's fact operations through a series of targeted optimizations. The changes are purely performance improvements with no changes to the public API or data model.

Benchmark Results (16KB payload)

Operation	Before	After	Improvement
set fact	~1.2ms	846µs	30% faster
update fact	~906µs	688µs	24% faster
retract fact	~468µs	360µs	23% faster
get fact	~117µs	~51µs	56% faster

What Was Optimized

1. LRU memoization for merkle reference hashing

Added a bounded LRU cache (1000 entries) for refer() results. Provides ~25x speedup on cache hits when the same content is referenced multiple times within or across transactions.

2. SQLite prepared statement caching

Caches 7 frequently-used SQL statements per database connection using a WeakMap for memory safety. Eliminates redundant statement preparation overhead. Result: 2.2x faster queries, ~20% faster writes.

3. Datum/fact hash reordering

The merkle-reference library caches sub-objects by identity during traversal. By computing the datum hash BEFORE the fact hash, the subsequent refer(assertion) call hits the cache when it encounters the payload sub-object. This is a simple reorder with a comment explaining why order matters. Result: ~16% faster sets.

4. Batch label lookups

Previously getLabels() performed N individual SELECT queries for N facts. Now uses a single batched query with SQLite's json_each() function. Reduces N queries to 1 query regardless of transaction size.

5. Use stored fact hash instead of recomputing

In conflict detection, we were reading a fact from the database (which includes the stored hash), discarding the hash, then calling refer() to recompute it. Now recall() returns the stored hash directly. Result: 7-16% faster across all operations.

Why These Changes Are Safe

1. No API changes - All optimizations are internal implementation details
2. No data model changes - Same merkle hashes, same storage format, same behavior
3. All 31 existing tests pass - Full test coverage confirms correctness
4. Caches are bounded - LRU eviction and WeakMap prevent memory leaks
5. Pure performance - Same inputs produce same outputs, just faster

Bottleneck Analysis

Investigation showed that SQLite is NOT the bottleneck (~2-5µs for raw INSERT). Time breakdown for a 16KB fact write:

Component	Time	%
Merkle hashing	~370µs	44%
JSON operations	~280µs	33%
Commit log	~150µs	18%
SQLite	~35µs	4%

The optimizations target the hashing and database overhead where practical, while respecting the merkle DAG architecture that provides content-addressability, conflict detection, and deduplication.

Test plan

• All 31 space-test.ts tests pass
• Benchmarks show consistent improvement
• No changes to public API or data format
• Memory usage bounded by LRU cache limits

🤖 Generated with Claude Code

---

Summary by cubic

Optimized memory fact operations with internal caching and SQL statement reuse, yielding ~30% faster writes and ~56% faster reads on 16KB payloads. No API or data model changes.

• Performance

  • Memoized merkle refer() with a bounded LRU (1000 entries) for repeated content.
  • Cached SQLite prepared statements per connection (WeakMap); ~2.2x faster queries and ~20% faster writes.
  • Computed datum hash before fact hash to reuse merkle sub-object cache (~16% faster sets).
  • Batched label lookups via json_each(), reducing N queries to 1.
  • Used stored fact hash in conflict detection instead of recomputing.

• New Features

  • Added comprehensive benchmarks and a deno task: deno task bench.
  • Included isolation benchmarks to spotlight hashing vs. SQLite costs.

^{Written for commit d066037. Summary will update automatically on new commits.}

[cubic-dev-ai]

3 issues found across 8 files

Prompt for AI agents (all 3 issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/memory/test/benchmark.ts">

<violation number="1" location="packages/memory/test/benchmark.ts:65">
Warm-up calls `session.transact` without ever checking the returned Result, so initialization failures are silently ignored and every benchmark can run with invalid state.</violation>

<violation number="2" location="packages/memory/test/benchmark.ts:65">
The workflow benchmark drops every Result from `session.transact` and `session.query`, so any failure in create/read/update/retract steps is ignored and the workflow timing becomes meaningless.</violation>

<violation number="3" location="packages/memory/test/benchmark.ts:233">
Each query in the “get fact (10 specific docs)” benchmark discards the Result from `session.query`, so read failures are silently ignored and the benchmark can time no-op iterations.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}

[seefeldb]

this looks great! cc @ubik2 who might find this really interesting as well.