DEV Community: YQteam

yq-sanyi v0.4.0: define a component once, use it as a real HTML tag anywhere

YQteam — Mon, 05 Oct 2026 14:34:28 +0000

yq-sanyi is a web component framework with no runtime dependencies. You define a component once, and after that it is a native HTML element you can use anywhere.

yq.define('yq-counter', {
  template: '<button yq-on:click="inc">{{ count }}</button>',
  style: 'button { font-size: 18px; padding: 8px 18px; }',
  script: function () {
    return {
      state: { count: 0 },
      inc: function (state) {
        state.count = state.count + 1
      }
    }
  }
})

Then, in plain HTML:

<yq-counter></yq-counter>

The tag mounts itself, renders, updates and cleans up. The template is HTML, the style is CSS, the script is JS — nothing custom to learn. No JSX, no virtual DOM, no compiler, and whoever drops the component on a page doesn't need a build step either.

~12.6 kB core bundle, gzipped
0 runtime dependencies
298 / 298 tests passing
Apache-2.0

Why another component framework?

Fair question, there are plenty.

But a lot of pages don't need a framework, they need one widget. If you pull React into a landing page for a single dropdown, you also bring its compiler, its runtime and a dependency tree. If you stay native with Web Components instead, you end up writing the templating, style isolation, reactivity and lifecycle wiring yourself, every time.

yq-sanyi is for that middle ground. It removes the boilerplate, and the result is still a plain custom element — so it works in any page, any template engine, any CMS, next to whatever else is already on the page.

Quick start

git clone https://github.com/YQteam-hq/yq-sanyi.git
cd yq-sanyi
npm install
npm run build

Then write a plain HTML file:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>yq-sanyi quick start</title>
</head>
<body>
  <yq-counter></yq-counter>

  <script src="./packages/core/dist/core.global.js"></script>
  <script>
    yq.define('yq-counter', {
      template: '<button yq-on:click="inc">{{ count }}</button>',
      script: function () {
        return {
          state: { count: 0 },
          inc: function (state) { state.count = state.count + 1 }
        }
      }
    })
  </script>
</body>
</html>

Custom element rules still apply: the name starts lowercase and contains a hyphen, so <yq-counter> works and <counter> doesn't. define throws on an invalid name instead of letting it fail quietly in the page.

Template, behavior and style, in one place

Most setups keep structure, logic and style in three separate places. yq-sanyi keeps them in one definition that shares a scope, a reactive state and a lifecycle. That's where the name "trinity" comes from.

The template layer is a set of declarative directives that covers the usual cases:

<!-- list rendering with a stable key and a row index -->
<div yq-for="(task, index) in tasks" yq-key="id">
  {{ index }}. {{ task.title }}
  <button yq-on:click="toggle">toggle</button>
</div>

<!-- new in 0.4.0: nested yq-for at any depth, including on component tags -->
<div yq-for="group in groups" yq-key="id">
  <b>{{ group.name }}</b>
  <yq-row yq-for="row in group.items" yq-key="tag"></yq-row>
</div>

Conditionals are yq-if / yq-else-if / yq-else / yq-show; two-way binding is yq-model, with .trim / .number / .lazy; events are written yq-on:click.

Accessibility got its own pass in 0.4.0. When an aria-* binding resolves to an empty value, the attribute isn't rendered at all, so you don't get a dangling aria-label="" sitting in the DOM:

<input id="email"
       yq-model.trim="email"
       yq-on:focus="markFocus"
       yq-on:blur="validate"
       aria-label="{{ labelFor(name) }}"
       aria-invalid="{{ error ? 'true' : '' }}">

Style isolation uses scope rewriting by default and doesn't require Shadow DOM. That's on purpose — global theming still reaches the component, and outside CSS isn't fully sealed off. When you do want a hard boundary, pass useShadowDOM to createScopedElement. A component's style is injected once and shared by every instance.

State comes back from script. Handlers receive the reactive state, and writing to it re-renders. Several writes in the same synchronous task are batched into one flush.

What's new in v0.4.0

Five merged batches, four areas.

Structure

Nested yq-for at any depth, with yq-key and the row index still working
aria-* bindings, plus yq-on:keydown / focus / blur / paste / wheel
defineAlias(displayName, realName) for hyphenated display names
Reusable static fragments via <template id="x"> and yq.fragment(id, html)
onRecover plus yq.onError(fn) for structured failure handling

SSR and hydration

yq.parseTemplateDSD(src)  // recognize <template shadowrootmode> from the server
yq.hydrate('#app')        // adopt server-rendered DOM in place, no rebuild

The Node renderer entry is still a skeleton, and linkedom is an optional peer — that's what keeps the core dependency-free.

Declarative Shadow DOM -> hydrate in place: server-rendered markup is adopted, not rebuilt" width="800" height="400">

Reactive primitives

import { signal, effectPre, effectScope } from './core.mjs'

const count = signal(0)
const off = count.subscribe(v => render(v))

count.get()    // 0
count.set(5)   // notifies subscribers
count.peek()   // 5 — reads without tracking
off()          // unsubscribe

There's also effectPre (runs synchronously, returns a stop function) and effectScope (disposal in a group, with an idempotent stop()). derived now works out on its own whether a dependency is a signal or a state.

Ecosystem

DevTools extension for Chrome and Firefox (manifest v3)
React / Vue type wrappers (.d.ts only, ≤ 1 kB)
A live playground in examples/playground.html
New examples: SSR hydration, accessible form, nested lists, strict-CSP

Performance is a CI gate

Four performance budgets run in CI, and missing one fails the build, so a rendering regression can't land:

Metric	Budget	Measured (p50)
`first-interactive` — 3000-row cold boot to a click that reaches the DOM	≤ 1000 ms	~127 ms
`update-latency` — state write replacing all 3000 rows until the DOM shows it	≤ 200 ms	~21 ms
`scroll-fps` — 2000 rows, 200-row window, 4 rows per frame	≥ 55 fps	~880 fps (derived from p50 frame cost)
`scroll-frame-ops` — DOM mutations to advance the window one frame	≤ 900 ops/frame	705 ops/frame

The last one is my favorite. It counts DOM operations instead of timing them. One scroll frame always costs exactly 705 mutations, so a fast laptop and a loaded CI runner report the same number, and that catches regressions timing alone can't see.

Under the hood, the static skeleton is cloned once and updates write only the bound slots. No subtree rebuilds, no virtual-DOM diffing.

Trade-offs

SSR is Declarative-Shadow-DOM based and opt-in. The Node renderer is a skeleton, and browsers without DSD support fall back to client-side rendering.
The bundle is over its target. The 0.4.0 goal was ≤ 11 kB gzipped for the core; it landed at 12.58 kB (core.mjs) and 12.78 kB (core.global.js), about 1.6 kB over. Every milestone added net-positive source bytes, and esbuild already runs --minify, so squeezing harder yields less than 100 bytes. Getting under the target needs real feature cuts, tracked for v0.4.1. This release raises the CI size ceiling from 12 kB to 13 kB so the gate matches the size that actually shipped, instead of leaving a red check forever.
No CLI, and no non-browser target. The core is browser-first on purpose.

I'd rather write these down than dress them up. Picking a component layer is a trade-off, and the limits are part of the decision.

Try it

Repository: https://github.com/YQteam-hq/yq-sanyi
v0.4.0 release assets (yq-sanyi-0.4.0.zip / .tar.gz): https://github.com/YQteam-hq/yq-sanyi/releases/tag/v0.4.0
Tutorials: docs/tutorial.md (English), docs/i18n/zh-CN/tutorial.md (Chinese)
Runnable examples: examples/ — playground, SSR hydration, a11y form, nested lists, CSP

If you try it on a real page, I'd like to hear where it breaks. Issues and PRs are welcome.

Building multi-user + security on shared hosting: filesystem as the only state layer

YQteam — Mon, 14 Sep 2026 13:33:22 +0000

The self-hosted utility space shares a quiet truth: once a tool grows past the "one admin logs in" stage, the real work is not adding pages — it's deciding how to let a few people cooperate, who gets to approve dangerous operations, and how to persist all that state when you can't bank on a daemon, a database, or Redis. I recently read through the source of an open-source panel built for PHP shared hosting, and it answered all three with little more than .json files and file locks.

This is not a feature review. It's a look at the implementation trade-offs I found, and a few places where I genuinely don't know the answer.

Default-deny is where multi-user gets done right

The permission model is two layers: a role rank (viewer < operator < admin) plus an action whitelist. Ranking is just integer comparison — boring. The interesting part is the companion default policy: any endpoint not explicitly listed in the ACL map is admin-only. A lot of old panels default to "if it's not written, everyone can call it" — one unguarded endpoint and you leak. Here the default is rejection, and you opt in. That direction matters more than the fancy parts.

A path allowlist that's string-prefix matching raises flags

To limit read-only users to a subtree, the check looks like this:

strpos($normalized, rtrim($p, '/') . '/') === 0

That's raw string-prefix comparison. It does not resolve .., and it does not resolve symlinks. If an allowed directory contains a symlink pointing outside the allowed tree, can the read-only user traverse it? That depends on whether the file layer above normalizes via realpath. I stopped at the ACL layer and didn't chase the whole chain, so it stays an open question. Even a one-line comment ("the layer above normalizes paths") would save everyone the audit.

Double approval is, in effect, a re-dispatch with the gate bypassed

Sensitive operations (DB import, bulk purge, app uninstall) are intercepted and routed through a second-admin approval. Two decisions here are right: a single-admin deployment gets 409 outright instead of a "just let it through" fallback, and the requester cannot be the approver.

The execution path is the part worth unpacking. When the approver clicks approve, the code rebuilds the router, overrides the request body with the stored payload, opens a capture buffer, sets a bypass flag, and synchronously re-dispatches the request inside the approver's own HTTP call. Two consequences:

A slow operation blocks the approver's request until it finishes. For a large import that's a UX and timeout question.
The payload is a snapshot taken at submit time; by the time it runs, the underlying resource may have changed. So "approve" strictly means "approve the action as-of submit", not "apply to current state". Fine in most cases, worth remembering for auditing and error handling.

The rate limiter is honestly not a sliding window

Rate limiting applies only to non-admin roles. State lives in {userid}_{minute-bucket}.json, and the check sums the current bucket plus the previous one to approximate "roughly two minutes":

foreach (array($bucket, $bucket - 1) as $b) { $cur += count; }

That's not a sliding window; accuracy depends on where requests land relative to minute boundaries, and it skews at the seams. Fine as coarse shielding, but don't describe it as precise. One thing that caught my eye: reads and writes each count as 1 (no write weighting), while the read-only role's write quota is one request per minute. That is aggressive and likely to trip legitimate users — worth confirming it's intentional.

An in-process WAF lives and dies by its regexes

The WAF runs on every PHP request, scanning query, body and URI with regex. Three implications worth separating:

It blocks inside the PHP process. By the time it fires, PHP has already handled the request; it just stops it with exit() before business code runs. This is an application-layer filter, not an edge firewall.
The rules are keyword regexes, not semantic analysis. The command-injection rule contains \b(?:ls|dir|cat|grep|find|exec|system|...)\b, so any plaintext containing "cat" or "find" trips it — search results, documents, an ordinary English sentence. And URL encoding or comment obfuscation sidesteps plain-text regex. It's a coarse sieve.
It ships a per-IP 1000 req/hour all-up limit via a locked JSON file — a pragmatic last line of defense on shared hosting.

For shared hosting, the survival metric for this kind of WAF is the false-positive rate. Killing legitimate business costs more than the attacks it stops. "Rules can be turned off and scoped down" beats "the bigger the rule surface the better".

A convention everyone should copy: say plainly when a capability is missing

When the host lacks a capability, the API returns 501 with a machine-readable code (think composer_unavailable, fpm_not_applicable). Shared hosts routinely miss extensions or disable functions, and most panels just throw a generic 500 that sends you guessing. Separating "this host can't do it" from "the software is broken" is more valuable than a dozen more pages.

Open questions I'm keeping

Does the file layer above the path allowlist actually normalize realpath and symlinks?
With snapshot-replay approvals, when the resource changed after submit — replay anyway, or error and ask to resubmit?
All state in JSON with file locks: at what concurrency and volume does that break, and where's the line where SQLite becomes worth it?

The source I read is an open PHP panel; each module lives as one file under its backend/ directory, easy to browse: https://github.com/YQteam-dyq/Go.js-Lite/. If you've measured any of the above, I'd like to hear it.

Why we wrote our own 8.5 kB web component runtime instead of pulling in a framework

YQteam — Mon, 07 Sep 2026 12:23:55 +0000

Hi, we're YQteam 👋 We just open-sourced yq-sanyi (v0.2.0, our initial release): define a component as a native HTML tag, then drop <yq-counter> into a plain page — zero dependencies, zero build.

The first question people ask us is: there are already so many component solutions — why build your own?

This post is not about the API. It's about the decision process behind the project.

A scenario we kept hitting

The need is simple: a reusable counter, a panel, a todo list — instead of copy-pasting the same HTML plus interaction logic into every page.

But in practice you usually have only two options:

Adopt a framework. For a "lightweight reuse" need, you pay for a whole runtime plus a build toolchain. For existing static pages, multi-page sites, or server-rendered template pages, that feels like moving house just to buy a shelf.
Hand-rolled copy-paste. Great the first time, painful from the second: boilerplate, styles bleeding into each other, event listeners nobody remembers to clean up.

We wanted a third way: as light as copy-paste, with the reuse experience of a framework.

The three paths we walked

Native Web Components: the right direction, but parts, not a product

customElements standardized "UI as an element" — that's genuinely great. But to actually use a component comfortably you still have to solve a long list of problems yourself:

How do attributes and internal state stay in sync?
How should the event system be designed?
Where does reactive state come from?
What about style isolation? If you reach for Shadow DOM, form-element piercing, CSS-variable theming, and injecting external styles all become design problems of their own;
Who cleans up listeners and side effects on unmount?

The standard doesn't build those wheels for you. Using it raw means boilerplate; filling the gaps means writing a framework anyway.

A framework runtime: the cost doesn't match the benefit

Our actual need was "a few reusable interactive widgets", not page-wide state management, routing, and an ecosystem. Bringing in the latter for the former is like opening a supermarket to buy a bottle of water.

This is especially true when the target is plain HTML / multi-page / static pages, or a page embedded inside someone else's system — a framework runtime plus build output can easily weigh more than the components themselves.

A minimal self-built loop: do just one thing — components

So we implemented it ourselves, shrinking the scope to the smallest coherent unit:

Let template, behavior and scoped style be one definition, one native tag, and one shared lifecycle.

The name "yq-sanyi" ("trinity") comes exactly from that idea.

The rules we set for ourselves

Web-standard APIs only. No JSX, no virtual DOM, no compiler, no framework runtime;
Single source of truth. Template, behavior and style live in one unit — easy to read, reuse and audit;
Mutate state, the view updates itself. Tags auto-mount, auto-update and auto-cleanup;
Style isolation without mandatory Shadow DOM. Selector-scoping by default, CSS-variable theming, opt-in Shadow DOM when you need strong encapsulation;
Failure isolation. A broken component renders an error placeholder plus a structured warning while the rest of the page keeps working;
Size is a budget, not a souvenir. The core is ~8.5 kB gzipped, and the repo ships dependency-graph and bundle-size gates plus benchmarks so it can't quietly bloat.

What it looks like now

yq.define('yq-counter', {
  template: '<button yq-on:click="inc">count {{ count }}</button>',
  style: 'button { font-size: 18px; padding: 8px 18px; }',
  script: function () {
    return {
      state: { count: 0 },
      inc: function (state) {
        state.count = state.count + 1
      }
    }
  }
})

Define it once. After that, the usage site is a single line:

<yq-counter></yq-counter>

For template syntax, state, lists and scoped styles, the README and the English tutorial cover everything — no need to repeat it here.

We're not telling anyone to abandon their framework

Different constraints call for different choices. If your project is deeply embedded in a framework ecosystem, needs SSR, or depends on a full CLI-driven pipeline — a framework is right for you, and we explicitly list those cases as "deliberately not supported" in our docs.

But if you're on the "I just want to reuse a piece of UI, lightly" side — no build, plain HTML pages, curious about how components actually work under the hood — come say hi at the repo:

Repo: https://github.com/YQteam-dyq/yq-sanyi
Bilingual tutorials and runnable examples live in the repo

v0.2.0 is our initial release and we will keep iterating: fixing known limitations first (event binding inside yq-for rows), evolving the template layer and devtools, and keeping the English/Chinese docs in sync. Stars, issues, and pull requests are all welcome — and if the project saves you time, you can support us on Afdian to help keep it free, open and zero-dependency.

Why a New Compiler Splits Into AST, HIR, and TIR (and Caches by Content)

YQteam — Sat, 05 Sep 2026 14:03:46 +0000

Compiler beginners easily imagine compilation as a straight line: read source, parse, generate machine code. In real engineering, that line is split into several intermediate representations (IRs), where each layer does one set of jobs and layers are joined by lowering. Why go through all this trouble? Because a single representation always hits a conflict between expressiveness and information at some stage: too close to source and it is hard to optimize, too close to machine code and it is hard to analyze. This post uses YQ, an unreleased LLVM-based systems language we are developing, to explain what the AST, HIR, and TIR layers each do, why their order cannot be shuffled, and how a content-addressed cache keeps a multi-layer pipeline from becoming too slow to use.

Three kinds of questions one compilation answers

Splitting "turn YQ source into an executable" apart, a compiler is really answering three different kinds of questions in sequence:

What does this text mean (syntax layer): what does the tree of a + b * c look like?
Are these names and types right (semantic layer): is b an f32 or a user-defined type? Does + have a matching implementation?
How does this logic land on the machine (code generation layer): is addition an add instruction or a function call? How is a struct laid out in memory?

If one AST alone ran the whole way, the first kind of question would be easy to answer and the third would be very hard, because the AST is full of syntactic sugar (if, pattern matching, operators, indentation blocks) and the optimizer would have to guess semantics every time. The industry-standard approach is therefore to let representations "desugar" layer by layer: the AST keeps the full syntactic shape of the source, and the further down the IR you go, the closer you get to a plain instruction-level form, until you reach LLVM IR, a representation that is optimizable and can generate code for many backends.

YQ's pipeline is designed as:

YQ source
  |  lexing/parsing (Unicode identifiers, indentation-aware, error recovery)
  v
Token -> AST (carries Spans: every node remembers its start/end location in source)
  |  semantic analysis: scope resolution, desugaring
  v
HIR (high-level IR: explicit control flow and calls, syntactic sugar flattened)
  |  type checking (HM inference + trait solving) + ownership/borrow checking
  v
TIR (typed IR: every node carries a concrete type)
  |  generic specialization (monomorphization) + lowering to LLVM IR
  v
LLVM IR -> object files

AST: faithfully preserving syntax, Span is its soul

The AST's job is not to be "convenient", but to be "complete". The parser (ours is a hand-written recursive descent one) turns source into a tree where every node hangs on a Span, the start/end line and column range of that node in the source file. A Span looks like a tiny structure, but it is the foundation of all diagnostics quality downstream:

when types mismatch, the error can point precisely at the offending subexpression instead of the whole function;
editor features like hover, go-to-definition, and completion are, at bottom, "map a cursor position onto an AST node";
if an error message wants to show a source snippet with terminal coloring, the only reliable source of that is the correspondence between Spans and source text.

This is also why even adding one field at the AST stage deserves caution: its structure flows through HIR and TIR and affects diagnostics and tooling all the way down. Many new language projects rush with a minimal AST to get something running, and later find that retrofitting the diagnostics experience means almost rewriting the front end. That bill is not worth it.

HIR: flattening "code written by humans" into "code a compiler can handle"

HIR exists to remove syntactic sugar and implicit behavior. Code written by humans is full of conveniences: if is an expression, operators call trait methods, pattern matching hides a chain of branch decisions, and indentation blocks must become explicit scopes. These are friendly to readers, but not to analyzers. The HIR stage does a few typical things:

scope and name resolution: resolve names like x and foo to definite definitions, producing binding relations for every symbol, preparing for type checking;
explicitness: expand syntactic sugar into plainer structures so later stages only face a few node shapes;
keeping what type checking needs: HIR nodes still have no types, but the call structure they record must be clean enough for the type checker to walk smoothly.

A common design question is whether HIR should keep Spans. The answer is almost always yes. Diagnostics at ever later stages need to point back at source, and since HIR has already flattened syntactic sugar, dropping position information here means errors would point at "desugared intermediate nodes" that users cannot understand at all.

TIR: the "final draft" after type and ownership checking

Once type checking (HM-style inference plus trait constraint solving) and ownership checking finish, the compiler has enough information to pin every expression to a concrete type. That representation is TIR. Compared with HIR, the key increment of TIR is that every node carries a definite type, which makes it safe to do:

generic specialization: add 1 2 and add 1.5 2.5 are the same function node in HIR; in TIR the instantiation information is clear, so a dedicated copy can be cloned for (i32, i32) and for (f32, f32) and handed to LLVM for optimization;
memory layout decisions: struct field offsets and enum discriminant layouts can only really be computed once types are known;
ownership-related move/borrow decisions: where a value moves and where it drops needs type information combined with region inference.

Doing specialization at the TIR level instead of the LLVM level is so that "clone code by type" happens on our own IR. On our own IR we can freely copy, rename, and instrument nodes, while the LLVM layer is better at scalar optimization and instruction selection. The two jobs do not overlap.

Why hook up to LLVM instead of writing a whole back end

Everything up to TIR is language-specific. The work after that, instruction selection, register allocation, optimization, and object file generation, is highly generic and an enormous amount of engineering. Calling into LLVM is what most new languages choose, and YQ does too: at the code generation layer, TIR is lowered to LLVM IR through LLVM's C API bindings, and LLVM produces object files. The benefit is getting an industrial-grade optimizer and multi-backend support for free (x86_64, WASM, and even GPU/TPU directions all build on the LLVM ecosystem). The cost is that you have to describe your language in LLVM's world view: you are responsible for struct layout decisions, calling conventions, and translating YQ's error handling model into control flow that LLVM can express.

The cost of a multi-layer pipeline: slowness, and how a cache covers it

The most direct cost of multiple IR layers is slower compilation: every layer walks the whole tree once, and every lowering allocates again. Early new-language projects usually do not care, but once the compiler starts compiling itself (bootstrapping) and the test suite grows into the hundreds, slowness becomes a development-efficiency problem. Our approach is a content-addressed compilation cache: cache intermediate artifacts per file rather than per whole project.

In the compile cache directory, each compilation unit leaves a group of files like this:

1423ba0b-e3b0c442.meta     # metadata
1423ba0b-e3b0c442.bin      # intermediate artifact
1423ba0b-e3b0c442.o        # object file

The .meta content is roughly:

v=1
source_hash=<SHA256 of the source>
flags_hash=<SHA256 of the compile options>
deps=<list of source files this unit depends on>
obj=<corresponding .o file name>
bin=<corresponding .bin file name>

The keyword of this design is "content addressing": the cache key is not a file name or timestamp but a hash of the input content. Change one byte of source and source_hash changes, so that unit is automatically invalidated and rebuilt; units that did not change are reused directly from .o/.bin. The deps field records dependency relations, which makes "only recompile affected modules" possible. That is the skeleton of incremental compilation, and it lays the groundwork for toolchain goals such as "a full rebuild after changing one line stays under 500 ms". Note that what is hashed is the recomputable input, not the artifact path; otherwise the cache would silently hand you stale results.

It is worth stressing: cache correctness matters far more than cache hit rate. Better to invalidate too much and rebuild than to let an old artifact slip into a new build. That is why compile options are folded into the hash as well (flags_hash), ruling out the classic bug of "switching optimization levels yet eating the old cache".

Looking back over the pipeline: the AST is responsible for faithfully preserving syntax and carrying Spans, HIR for flattening syntactic sugar so it can be analyzed, TIR for finalizing after type and ownership checking and performing specialization, and LLVM for the last mile of optimization and code generation. Each layer boundary corresponds to a clear analysis phase in the compiler, and once the order is reversed you are forced to do work on a representation that it was never meant for. The content-addressed cache then pays off the "performance debt" of the multi-layer pipeline, keeping iteration speed usable after bootstrapping and test growth. For new language projects, planning this "layering plus content addressing" combination early is more valuable than jumping straight to a toy compiler, because once the front-end structure is fixed, later changes mean rewriting layer by layer.
**

I built a local memory layer for AI agents: no vector DB, one SQLite file

YQteam — Fri, 04 Sep 2026 10:34:48 +0000

If you build AI agents, you know the feeling: the model itself has no memory. Every conversation starts from zero. To make an agent remember user preferences, pick up where a task left off, or reuse knowledge across sessions, you have to bolt on a memory system yourself.

I looked at the existing options, and none of them felt right for me:

Vector databases (Pinecone, Qdrant, Weaviate…) are powerful, but standing up a distributed service just for memory is a lot of weight for a small project or a solo dev.
Cloud memory services (Mem0 and similar) keep your data on someone else's servers and bill per use.
Rolling my own in-memory store loses everything on restart — and forget semantic search entirely.

What I actually wanted was pretty boring: a local memory layer that runs from one file and one command, works out of the box, and keeps the data fully in my hands. I couldn't find one I liked, so I wrote it. That's how yq-nova-agent started, open sourced on August 3rd: github.com/YQteam-dyq/yq-nova-agent

What it does

In one sentence: a single-file SQLite memory and state layer for agents, built around three operations — remember, recall, forget.

Things an agent learns persist across conversations and survive restarts.
You can recall semantically relevant information from past sessions using natural language.
It tracks entities and their relationships, so you get lightweight graph reasoning.
Stale or low-importance memories are cleaned up automatically, so the store doesn't grow forever.

No external service to deploy. The only runtime dependency is one SQLite file.

Design decisions worth talking about

Three operations, one mental model

The API is deliberately small. HTTP, the Rust SDK, and the CLI all expose the same semantics, so there's no conceptual overhead:

# Store a fact with tags and an importance score
yq-nova remember "User is a Rust developer who prefers lightweight tools" --tag user-profile --importance 0.9

# Recall with natural language
yq-nova recall "user's technical background" --top-k 5

# Check what's in the store
yq-nova stats

Don't want an HTTP server? The CLI works standalone. Building a Rust app? Pull in yq-nova-core as a library and call it in-process.

Hybrid retrieval, not just vectors

An early version that only did vector similarity missed too much: exact keyword matches and graph relationships between entities don't show up in pure semantic search. So recall fuses three signals with RRF (Reciprocal Rank Fusion):

Semantic search (embedding similarity)
Keyword search (SQLite FTS5 full-text index)
Graph signals (entity-relation relatedness)

# Hybrid mode with graph enhancement
yq-nova recall "storage solutions related to SQLite" --mode hybrid --graph

Embeddings are pluggable: OpenAI-compatible endpoints by default, plus a built-in mock provider so you can develop and test fully offline.

Entities and relations: memory with context

Isolated memory entries aren't enough — pieces of information relate to each other. The project keeps an entity-relation graph with recursive BFS traversal. Store "React is a UI library" and "Vue is a UI library", and a recall can walk the graph to find neighboring concepts. That's context pure vector search can't give you.

SQLite is underrated

A lot of people write SQLite off as a toy, but with WAL mode, composite indexes, and FTS5 it's genuinely enough for a single-node memory layer — and the operational cost is close to zero. Persistence, transactions, and schema migrations are all solved problems, so I didn't have to reinvent any of them. This is also what makes the "zero external dependencies" promise hold up.

What v0.2.0 added

v0.2.0 shipped on August 6th, and it closed most of the gap between "works on my machine" and "usable in production":

Embedded SDK mode (EmbeddedNova) — use it in-process without spinning up an HTTP server
Local ONNX inference via FastEmbed, so you don't need an OpenAI API key to get vectors
API token auth middleware on the HTTP server
SQLite vector index backed by sqlite-vec's HNSW
Integration tests plus Criterion benchmarks (KNN, graph traversal, embedding)
Docker image and docker-compose for one-command startup
A small Python client (yq_nova)

# Run the server in Docker, persisting data to /data
docker run -p 7999:7999 \
  -v yq-nova-data:/data \
  -e YQ_NOVA_EMBEDDING__DEFAULT_PROVIDER=mock \
  yq-nova serve

Auth, OpenTelemetry tracing, and benchmarks are the "invisible" features — but they're exactly what you need before trusting something in production, so I prioritized them in v0.2.

The honest part

The project is new. It's been open source since August 3rd, and today it has zero stars and an issue tracker that only I talk to. I'm the only maintainer, and there are 18 commits so far. I'm not writing this to claim I built something impressive — I'm writing it because I hit a real problem (agent memory) that I think the "lightweight + local + single file" approach genuinely solves, and I want more people who feel the same pain to find it.

If you're building agents and have opinions about memory, or you try it and think something is designed wrong, please open an issue. What I'd most like to know:

How do you handle agent memory today, and what hurts the most about it?

Your answers will directly shape what I build next — v0.3 is in active development, and I'd rather prioritize based on real scenarios than my own guesses.

If the project is useful to you, or the direction sounds interesting, a star is the easiest way to help.

Repo: github.com/YQteam-dyq/yq-nova-agent

I'm YQteam-dyq on GitHub — happy to chat about agent memory, Rust, or anything in between.