Distillation

Date: Sep 17, 2026

• 🔴 (09:22) Lore is a TypeScript monorepo using pnpm workspaces, Node.js >=22.5, SQLite in WAL mode with FTS5, and production data stored at ~/.local/share/lore/lore.db; root tooling pins pnpm@10.28.0 and Volta pins Node 24.16.0 plus pnpm 10.28.0.
• 🔴 (09:22) Lore’s four packages are: @loreai/core at packages/core/ (shared memory engine), @loreai/gateway at packages/gateway/ (transparent LLM proxy and lore CLI), @loreai/opencode at packages/opencode/ (OpenCode adapter), and @loreai/pi at packages/pi/ (Pi adapter). @loreai/core version is 0.40.0.
• 🔴 (09:22) Lore’s three memory tiers are: Tier 1 temporal storage in packages/core/src/temporal.ts; Tier 2 distillation in packages/core/src/distillation.ts, with at most 16K tokens per segment and meta-distillation when gen-0 count exceeds 20; Tier 3 gradient context management in packages/core/src/gradient.ts, using four layers from full passthrough through emergency compression.
• 🔴 (09:22) Lore knowledge entries in packages/core/src/ltm.ts use categories decision, pattern, preference, architecture, and gotcha; fields are id (UUIDv7), project_id, category, title, content (maximum 1200 characters), confidence (0.0–1.0), and cross_project. Creation paths are LLM curator, regex pattern extraction, .lore.md file import, and consolidation when entry count exceeds maxEntries (25).
• 🔴 (09:22) Tests use a temporary SQLite database configured through packages/core/test/setup.ts, never the production DB.
• 🔴 (09:22) Release workflow uses Sentry Craft through GitHub Actions; never manually bump versions or edit CHANGELOG.md, because Craft handles both automatically. Releases are triggered with gh workflow run release.yml -f version=auto or an explicit version such as gh workflow run release.yml -f version=0.23.0.
• 🔴 (09:22) The release workflow order is: 1. scripts/bump-version.sh updates all package.json versions; 2. conventional commits generate the changelog; 3. a release/X.Y.Z branch is created and pushed; 4. CI tests and builds npm tarballs, standalone binaries, and delta patches; 5. Craft opens a publish issue and the Publish workflow runs after it receives the accepted label; 6. publishing uses npm OIDC trusted publishing and creates a GitHub Release with binaries and patches. .craft.yml defines four npm workspace targets, the legacy opencode-lore alias, and the GitHub Release target.
• 🔴 (09:22) Root project commands are pnpm test (Vitest), pnpm run typecheck, pnpm run lint (oxlint --type-aware), pnpm run lint:fix, pnpm run format (oxfmt), pnpm run format:check, pnpm run build, pnpm run test:coverage, pnpm run evals, and pnpm run mutation.
• 🔴 (09:22) packages/core/src/cgroup-memory.ts resolves Linux cgroup memory files dynamically from /proc/self/cgroup and /proc/self/mountinfo, decoding procfs octal escapes, rejecting non-absolute paths, NUL bytes, and .. path components, and preferring an explicit cgroup v1 memory controller over a unified cgroup v2 membership on hybrid hosts.
• 🔴 (09:22) Cgroup memory discovery must re-read procfs for each call so a worker is never admitted from a stale cgroup directory or a cached discovery miss.
• 🔴 (09:22) readLinuxCgroupMemoryHeadroomBytes() computes cgroup v2 headroom using memory.current against both memory.high and memory.max, computes cgroup v1 headroom using memory.usage_in_bytes against memory.limit_in_bytes, walks from the process cgroup directory toward the mount point, and takes the minimum finite headroom across boundaries.
• 🔴 (09:22) Every descendant cgroup boundary must remain readable so sibling usage is never subtracted from the wrong scope; failures generally return undefined, with a narrow exception allowing the unresource-controlled cgroup v2 root to omit memory.current, memory.high, and memory.max.
• 🔴 (09:22) Cgroup resolution never falls back to v2 when an explicit v1 memory membership exists but its memory mount is absent.
• 🔴 (09:22) Cgroup tests cover process-mount resolution rather than fixed paths, selecting only the v1 memory controller, refusing v2 fallback for an unresolved explicit v1 membership, preferring the mount whose root contains the process cgroup, malformed input, namespace handling, narrow versus broad roots, ancestor limits, repeated procfs discovery, and failing closed when membership changes during one accounting call.
• 🔴 (09:23) Project review policy requires every adversarial-review defect to receive a deterministic regression test in the same PR that fails on the base branch, passes with the fix, and drives the real precondition; a guard test must fail when the guard is deleted.
• 🔴 (09:23) Adversarial test setup must reproduce hostile ordering: state present before the operation that should handle it, delete-then-recreate across lifecycle boundaries, and modify-while-off where disabled sync prevents capture triggers from observing the change.
• 🔴 (09:23) Fan-out registry contract coverage is mandatory: SYNCED_TABLES via packages/core/test/sync-registry-contract.test.ts; MIGRATIONS via the db.test.ts schema-version assertion plus migration-specific tests; and AGENTS via agents.test.ts, validating name, displayName, binary, and detect() with binary as a constant placeholder string.
• 🔴 (09:23) Standing bug batteries are: registry contracts for SYNCED_TABLES; per-operation sync invariants in packages/core/src/sync-data.ts through assertSyncInvariants; and sequence properties in packages/gateway/test/sync.property.test.ts covering invariants after every operation, prune-floor progress, eventual convergence, no ping-pong, and currentTier correctness.
• 🔴 (09:23) Project review heuristics identify skip/early-return branches as the highest-risk surface; every such branch needs a test that causes it to skip something incorrectly and proves that failure is prevented. Property-based tests should use faithful mocks, bug fixes follow failing-first TDD, memoized shared arrays should be frozen, and SQL-counting tests must use log.registerSink({ withDbSpan }) because the tracing Proxy shadows direct db().query monkeypatches.
• 🔴 [requested-review] (09:23) Non-trivial changes require two distinct review passes: 1. adversarial/correctness review covering break-inducing state, enumerated cases, apply-then-revert mutants, property-test stability ×10, hash equivalence, frozen-array mutation safety, and stale-cache analysis; 2. security/pentest review covering injection, credential leaks, protocol attacks, and privilege escalation. Adversarial review is mandatory before merge; security review depends on risk profile.
• 🔴 (09:23) Reviewers must run pnpm test, pnpm run typecheck, pnpm run lint, and pnpm run format:check; inspect exit codes because a blank output tail may conceal lint or format failures; run property tests ×10; hash-verify that the working tree ends unmodified; and report per-point PASS, FAIL, CONCERN, or MUST-FIX verdicts with file:line evidence plus an overall MERGE or DO-NOT-MERGE verdict. Unstructured “LGTM” is not acceptable.
• 🔴 (09:23) Any PR touching correctness-critical sync engine, hashing, lifecycle, or migration paths requires adversarial review regardless of size; mechanical or test-only PRs may skip it at reviewer discretion.