DEV Community: Meronq

We built a product around context cost and never measured our own tools

Meronq — Sun, 30 Aug 2026 11:46:58 +0000

Meronq is an engineering-intelligence layer: it keeps a model of your project — components, decisions, evidence — and serves it to AI assistants over MCP. Context cost is the whole premise. We have an ADR that prices understanding against tokens. Our handshake tool sends a vitality-focused slice, 21 entities out of 176, precisely so a session does not pay for the entire graph.

Then we measured what the other tools returned.

memory_sync — the tool whose useful answer is "synced, here is what changed" — was returning 84,484 bytes on a real project. The entire Canonical Engineering Model plus the entire project scan. About 21,000 tokens to confirm a sync.

project_list, which answers "which projects can I work on", returned 46,190 bytes. The local registry had grown to 240 entries; 227 of them pointed at temp directories that no longer existed. Every call shipped all of them.

That is the uncomfortable part: none of this was discovered by a user complaint or a benchmark. It was sitting in our own instrumentation the whole time — access_events.response_bytes, a column we wrote and never read.

The fix is deliberately boring

Return counts by default. memory_sync, project_scan and github_sync share one code path. It now returns graph counts, what the sync changed, warnings, and a hint. The full payload is one argument away:

	before	after
`memory_sync` (Unity project)	85,061 B	3,528 B
`memory_sync` (our monorepo)	137,358 B	1,521 B
`project_list`	46,190 B	2,377 B

Nothing is lost. The graph is in SQLite either way, semantic search reaches it, and detail="full" still returns everything.

Put a ceiling on the shared response helper. Every result now passes a 32,000-byte limit. One detail mattered more than the number: an oversized object is replaced by a notice carrying its actual size, not truncated. Half a JSON object is not JSON, and handing an agent an unparseable fragment is worse than telling it plainly that the response was too large and how to narrow it. Oversized strings keep their head, which is usually the useful part of a log.

The ceiling also has an escape hatch. A caller who explicitly asks for full detail raises it rather than being overruled. A limit that argues with an explicit request is a bug, not a safeguard.

Stop shipping dead rows. project_list lists what exists on disk and counts the rest. The cause of the pile-up turned out to be our own test suite: project initialization registered into the real ~/.meronq/projects.json whenever no session was passed, so every full test run left rows behind in the developer's own registry. It takes an isolated registry home now.

What did not ship, and why

We bundle a multilingual e5-small model for offline semantic search. The obvious next step is to use it for selection — pick the entities that best cover the graph instead of the hottest ones. A maximal-marginal-relevance pass over the stored vectors already does better on paper: seven entity types in a twenty-item budget instead of three.

It is not enabled, because of what we feed the model. The embedded text is name + summary + type + layer, and component summaries are formulaic — "Package: packages/x". The model reads the template, not the meaning. Clustering at cosine 0.95 cheerfully merged 64 distinct Unity modules into one group, and four unrelated packages of ours into another. Fix the input before trusting the output.

One instrumentation gap is also still open: rows written outside the MCP dispatcher — our handshake's own presence row, and every desktop sidecar call — carry no response size. That is how 970 handshake rows ended up with 11 measurements, and why this took so long to notice.

The lesson we actually take from this

Having the right principle, the right ADR and the right instrumentation is not the same as looking at the number. We had all three for months. The tool that violated the principle hardest was the one nobody thought to check, because it "just syncs".

If your product has a cost you care about, put one measurement of it somewhere you cannot avoid reading.

Read the full post on meronq.pages.dev · Source on GitHub

Sprint 21 closed: keyword-first search, meaning when the string misses

Meronq — Wed, 19 Aug 2026 11:24:26 +0000

Until this sprint, memory_search was a contiguous SQL LIKE. A question that shared no literal substring with the stored entity — a Russian paraphrase of an English ADR title, a reordered identifier — returned nothing. Assistants then opened files they did not need.

Sprint 21 keeps the keyword path as the fast default and adds a bundled, offline embedding fallback when LIKE is empty (ADR-0020).

Keyword first, meaning when it misses

Exact id / name / summary hits are unchanged. Only an empty keyword result runs cosine over that project's vectors. There is no Hugging Face fetch at runtime: intfloat/multilingual-e5-small (int8 ONNX, 384-d) is vendored next to the process, one model per process, one memory.db per project. Unchanged entities are not re-embedded.

The number this sprint claimed to move, on a fixed bilingual suite with zero substring overlap:

Path	Recall
Keyword `LIKE`	0
Bundled e5 fallback	1.0

Ranking that matches meaning, not heat

On a live ~170-entity graph, e5 compresses almost every row into cosine 0.76–0.82. Adding vitality (up to +9) on top of that range returned the hottest components — the project node at strength 423 — instead of Sprint 21. Semantic fallback now ranks cosine first, keeps neighbours within 0.02 of the best hit, and uses vitality only as a tie-break.

Routine chore / ci / lockfile commits stay on the keyword path. feat / fix / ADR-touching commits remain eligible, with a small cosine penalty so a sprint or ADR of similar meaning wins the near-tie. ADR entities now carry a Context (else Decision) paragraph, so the embed-string is no longer title-only.

Dogfood query «найти знания когда точное совпадение строки ничего не даёт»: Sprint 21 first, sprint tasks next, important fix(scanner) commits still present, version bumps gone.

Licence and packaging

Meronq is Apache-2.0. The bundled model is MIT (intfloat); transformers.js is Apache-2.0. End users do not download e5 from Hugging Face. Developers clone once and run pnpm --filter @meronq/embeddings vendor-model. If weights are missing, search degrades to keywords without failing the session.

Desktop copies the model into installer resources. @huggingface/transformers stays external to the sidecar — a packaged build that cannot resolve the WASM module remains keyword-only. MCP and pnpm dev use the local vendored weights. That installer gap is the next sprint.

Principle

Keep the exact match when it exists. When it does not, look up meaning locally — and do not let heat or a version bump outrank the decision.

Read the full post on meronq.pages.dev · Source on GitHub

Sprint 20 closed: tools that answer questions, and traces that prove they do

Meronq — Sun, 09 Aug 2026 21:04:03 +0000

Until this sprint, Meronq's product tools introduced themselves the way connectors do: by naming the system they talk to. github_sync, memory_search, project_build. Accurate labels — and the wrong unit for a host assistant that is trying to finish a job.

Sprint 20 flips the surface to the question each tool answers, leaves a trace on every call, and finally writes into the two CEM layers that Sprint 19 left empty on purpose.

Tools by intent

Product tool descriptions are now questions. Handshake next_steps name the tool to call next, not a vague suggestion. The ListTools payload grew — 12245 → 13285 bytes — because question-form copy is longer; consolidation stays deferred. We measured before and after instead of guessing.

memory_search gained a layer filter so the closed CEM axis is reachable from chat, not only from the Temperature Map chips.

The empty layers get writers

project_build and project_test used to throw their outcomes away. They now persist bounded CEM entities:

Tool	Entity	Layer
`project_build`	`build_result`	`artifact`
`project_test`	`test_run`	`validation`

Retention is the latest ten of each kind. Results survive CEM rebuild and are excluded from the archive sweep.

Instrumentation that can prove it

Every product tool records an access event when a project is resolvable — not only handshake and memory_search. The MCP initialize clientInfo is threaded into that context, so later focus-steering work can answer which assistant asked.

Init and cold Connect

Initialize an empty folder seeds foundation docs and scan/syncs so Tasks and the map show a sprint immediately.
Cold Connect — a repo with docs but no .meronq store — materializes the store and scan/syncs without inventing docs into a foreign tree.

Still open

Sprint 21 takes semantic retrieval: keyword-first memory_search with a bundled embedding fallback. Focus steering waits on real per-client access histograms from this sprint's substrate.

Read the full post on meronq.pages.dev · Source on GitHub

Sprint 17 closed: desktop distribution on R2 + in-app updates

Meronq — Thu, 30 Jul 2026 18:34:18 +0000

Sprint 17 is closed. Meronq Desktop can be downloaded from the website and updated in-app via signed Tauri updater artifacts on Cloudflare R2 (ADR-0016).

What shipped

No launcher — distribute and update the Desktop app itself.
Public R2 CDN (*.r2.dev) — versioned installers, latest/ aliases, and latest.json for the updater.
Website /download/ — Windows installers (macOS when artifacts land).
In-app Check for updates — tauri-plugin-updater against the R2 manifest.
Publish path — GitHub Actions on desktop-v* tags, plus local publish-to-r2.mjs when Actions cannot start.

Dogfood notes

First publish is Windows 0.1.0. macOS CDN packs, custom domain, and OS notarization stay deferred.

Read the full post on meronq.pages.dev · Source on GitHub

Sprint 16 closed: memory soft sync and Temperature Map UX

Meronq — Thu, 30 Jul 2026 13:27:00 +0000

Sprint 16 is closed. Desktop memory refresh no longer depends on knowing memory_sync by name, and the Temperature Map is easier to navigate when heat and focus matter.

What shipped

Soft sync policy — handshake remains primary; Desktop adds debounced soft sync on window focus / visibility plus an explicit Refresh Memory control (POST /api/memory-sync). No git-triggered sync.
Open GitHub counts — handshake / agents / CLI report true open issues and open PRs after closed issues and merged PRs stayed in the CEM snapshot (ADR-0013).
Temperature Map UX — clickable Relations list to focus related nodes; Show archived + Expand/Pack without remounting the graph or jumping scroll; focus ranking by BFS from selection, then strength/score, then heat.

Principle

Memory should stay warm while you work. Refresh follows Connect/handshake, Desktop focus, and an explicit button — not a hidden MCP ritual.

Cloud edge stays Workers-seeded. Desktop distribution and updater move to Sprint 17.

Read the full post on meronq.pages.dev · Source on GitHub

Sprint 14 closed: Memory Temperature Map

Meronq — Wed, 29 Jul 2026 18:09:29 +0000

Sprint 14 closed: Memory Temperature Map

Date: 2026-07-29

Author: Meronq team

Tags: sprint-14, memory, desktop, adr-0013, knowledge-vitality, temperature-map

Sprint 14 is closed. Knowledge Vitality is now visible in Meronq Desktop as a force-directed CEM graph — hot, warm, cold, and archived — with session-local Expand / Pack dials that never mutate shared SQLite (ADR-0013).

Desktop Temperature Map: vitality-colored nodes, semantic edges, and a continuous heat-relief field. Click the image for the full recap.

What shipped

MemoryStore.getGraphSnapshot — ranked subgraph with containment layers, plus derived semantic edges (part_of, evidenced_with) so the map is not only a sun of contains through the project node.
Sidecar GET /api/memory-graph — Desktop loads the temperature graph after Connect.
Temperature Map — vis-network layout with a continuous heat-relief background, multi-select, edge labels only for the selection, and a persistent mount so clicks do not remount physics.
Expand / Pack — session focus budget + estimated focus bytes; selection pulls 1-hop neighbors into focus without rewriting team memory.

Principle

Sprint 12: real work leaves a signal.

Sprint 13: measure memory health — and understanding with control values.

Sprint 14: see the temperature of that memory, and steer attention locally.

MCP wrappers named memory_expand / memory_pack remain follow-up; the Desktop dials are the product vocabulary for the same viewport model.

Canonical: https://meronq.pages.dev/blog/2026-07-29-sprint-14-closed-memory-temperature-map/

Sprint 9 closed: Desktop MVP

Meronq — Mon, 06 Jul 2026 04:21:00 +0000

Sprint 9 is closed.

The goal was to ship the first desktop shell over Meronq's existing packages — a native window that connects a project, shows its handshake and memory, and manages the product MCP server. Sprint 8 explored productization; Sprint 9 turned the desktop track into running code.

What Sprint 9 delivered

Tauri 2 scaffold in apps/desktop — native window wrapping the web UI
Project folder picker → sets MERONQ_PATH for the connected project
Handshake and memory stats UI — vision, sprint, ADRs, and memory counts
MCP server lifecycle — start/stop with live status

The desktop is a shell over existing packages (@meronq/server-core, @meronq/memory, @meronq/mcp-server), consistent with ADR-0008.

Architecture

Web UI (Vite)  →  Node sidecar (HTTP :39281)  →  <project>/.meronq/
                   · handshake (server-core)
                   · memory stats
                   · spawn mcp-server

Tauri 2 (src-tauri/) adds the native window and folder picker; the same UI runs in the browser for fast iteration without compiling Rust.

Two ways to run it

Web dev (browser, no Rust): pnpm --filter @meronq/desktop dev
Tauri native (Rust): pnpm --filter @meronq/desktop tauri:dev

Web dev mode boots the sidecar and Vite UI on http://localhost:1420 and builds the server-core / mcp-server dependencies automatically on first run.

Connect → inspect → run

Empty folder → Initialize (creates README, package.json, .meronq/local)
Existing repo → Connect (handshake + memory stats)
Start MCP → spawns meronq-mcp with MERONQ_PATH set to the connected project

Sprint 10 — Desktop polish and cloud spike

Native build verification (Windows/macOS), sidecar auto-start, memory search UI, and a cloud workspace API spike.

Follow along

Read the full post on meronq.pages.dev · Source on GitHub

Sprint 8 closed: Productization

Meronq — Thu, 02 Jul 2026 00:26:26 +0000

Sprint 8 is closed.

The goal was to turn prototypes into a usable product direction — desktop and cloud exploration, team workspace model, authentication, and billing — without over-building before validation.

What Sprint 8 delivered

Desktop app exploration — Tauri 2 direction, MVP scope, apps/desktop stub
Cloud backend exploration — optional sync, org admin, API boundaries
Team workspace model — Organization → Workspace → Project
Authentication model — local-only default, GitHub OAuth for teams, API keys for automation
Billing and pricing exploration — Local / Team / Enterprise tiers (no payment integration)

Canonical decisions live in ADR-0008.

New package: `@meronq/product`

Shared TypeScript types for product boundaries (exploration only — no cloud service yet):

Type	Role
`Organization`	Billing and SSO boundary
`Workspace`	Team grouping for projects
`ProjectLink`	Repo connection inside a workspace
`WorkspaceMember` / `WorkspaceRole`	Access control model
`BillingTier`	`local` · `team` · `enterprise`
`AuthMode`	`local_only` · `github_oauth` · `api_key`

Delivery phases (ADR-0008)

Now     CLI + MCP     Power users, IDE integration
Next    Desktop       Project picker, handshake, memory viewer
Later   Cloud         Optional team sync and org admin

Meronq stays local-first. Desktop is a shell over existing packages — not a parallel codebase.

Sprint 9 — Desktop MVP

Tauri scaffold, project folder picker, handshake and memory stats UI, MCP lifecycle status.

Follow along

Read the full post on meronq.pages.dev · Source on GitHub

Sprint 7 closed: Engineering Agents

Meronq — Wed, 01 Jul 2026 23:14:37 +0000

Sprint 7 is closed.

The goal was specialized engineering agents — architecture, code review, documentation, debugging, and onboarding — built on skills, memory, and MCP. Agents gather evidence and return structured briefings; they do not call external LLMs.

What Sprint 7 delivered

@meronq/agents — types, registry, context gathering, runner
Five built-in agents — architecture, code_review, documentation, debugging, onboarding
MCP + CLI — agent_list, agent_run, meronq agent run
Handshake — available_agents[] for discovery

Product MCP v1.2.0. Local MCP v1.18.0. agent_run is read-only in v0.

CLI

meronq agent list
meronq agent run onboarding
meronq agent run debugging --symptom "pnpm test fails"
meronq agent run code_review --pr 12

How it fits

Skills answer how (build, test, ADR). Agents answer when and why, with checklists, system guidance, and recommended skills.

Sprint 8 — Productization

Desktop app, cloud backend, team workspace, auth, and billing exploration.

Follow along

Read the full post on meronq.pages.dev · Source on GitHub

Sprint 6 closed: Skills and Workflows

Meronq — Wed, 01 Jul 2026 22:39:12 +0000

Sprint 6 is closed.

The goal was to introduce reusable procedural engineering knowledge — versioned Project Skills that offload deterministic workflows from LLM prompts into inspectable project code. See ADR-0006.

What Sprint 6 delivered

Every item on the roadmap is checked off:

Project Skill format — JSON schema with inputs, steps, safety, and evidence rules
project.build — run build via detected package manager
project.test — run test suite
adr.create — write a new ADR from template (title, optional context)
Workflow execution — sequential steps with fail-fast and structured results

Local MCP is now v1.16.0 with skill_list and skill_run. Product MCP and CLI expose the same skill surface.

New package: `@meronq/skills`

Module	Role
`listSkills()` / `getSkill()`	Built-ins + `.meronq/skills/*.skill.json` overrides
`runSkill()`	Execute steps through injected `SkillExecutionContext`
`buildAdrDraft()`	ADR numbering, slug, and markdown template

Built-in safety cannot be weakened by project overrides. Custom skills in v0 support create_adr steps only; command steps remain built-in exclusive.

Surfaces

meronq skill list
meronq skill run project.build
meronq skill run adr.create --title "My Decision" --context "Why we need this."

MCP tools: skill_list, skill_run. Handshake returns available_skills[] so assistants discover workflows without guessing shell commands.

Execution context lives in @meronq/server-core (createSkillContext) to avoid circular dependencies between skills and runtime.

Permission hardening

Post-sprint review added MERONQ_ALLOW_FILE_WRITE=true for skills that write files (e.g. adr.create) on the product MCP server. Runtime skills still require MERONQ_ALLOW_RUNTIME=true. Local MCP and CLI run skills without those gates for dogfooding and local use.

Pipeline

Intent (skill name + inputs)
  → getSkill / safety checks
  → createSkillContext (package manager, paths, runCommand)
  → sequential step execution
  → SkillRunResult (steps, output, action id)

Evidence recording into CEM/memory is planned; the schema is ready in skill definitions.

Sprint 7 — Agents

Sprint 7 goal: specialized engineering agents — architecture, code review, documentation, debugging, and onboarding — built on skills, memory, and MCP.

Procedures are now deterministic. Agents will decide when and why to invoke them.

Follow along

Sprint 5 made Meronq portable. Sprint 6 makes engineering procedures reusable across AI clients.

Read the full post on meronq.pages.dev · Source on GitHub

Sprint 5 closed: MCP Server

Meronq — Wed, 01 Jul 2026 22:38:25 +0000

Sprint 5 is closed.

The goal was to expose Meronq capabilities through MCP so AI assistants can use Meronq as a product tool layer — not only when developing Meronq itself. GitHub data and local memory from earlier sprints now ship through a dedicated product server with an explicit permission model.

What Sprint 5 delivered

Every item on the roadmap is checked off:

MCP tool surface — handshake, scan, memory, GitHub, runtime, and git read tools
Product server — apps/mcp-server v1.1.0 for any Meronq-enabled repository
Shared server core — @meronq/server-core (handshake, permissions, runtime, CEM sync)
Memory search — memory_search and memory_stats over SQLite
Safety model — runtime and network gates via environment variables

Local MCP refactored onto @meronq/server-core (v1.15.0) while keeping dogfooding tools: git write, social distribution, and extended allowlists.

Product vs local MCP

Surface	Use when
`apps/mcp-server`	Connecting assistants to your project
`apps/local-mcp`	Developing Meronq itself (social, git write, dogfooding)

Point either server at a repo with MERONQ_PROJECT_PATH (or MERONQ_PATH).

New package: `@meronq/server-core`

Shared logic extracted from local MCP:

Module	Role
`buildHandshake()`	Onboarding payload with CEM, memory, GitHub, sprint context
`buildAndSyncCem()`	Scan + optional GitHub fetch → SQLite
`ProjectRuntime`	Package manager and git command execution
`permissions`	`MERONQ_ALLOW_RUNTIME`, `MERONQ_ALLOW_NETWORK`, git write

Product MCP exposes 14 tools including memory_search, github_sync, project_build, and allowlisted commands. Git write stays off the product surface by design.

Permission model

MERONQ_ALLOW_RUNTIME=true   → build, test, install/dev allowlist
MERONQ_ALLOW_NETWORK=true   → GitHub API refresh (or set GITHUB_TOKEN)

Read-only git tools (git_status, git_diff) work without extra flags. See MCP server guide for Cursor configuration.

Memory search

memory_search queries entities in .meronq/local/memory.db with optional type filters. Access events are recorded when results are returned — aligned with ADR-0005.

# MCP: memory_search { "query": "github", "limit": 10 }

Sprint 6 — Skills and Workflows

Sprint 6 goal: introduce reusable procedural engineering knowledge — project.build, project.test, and adr.create as versioned Project Skills callable from MCP and CLI.

The product MCP surface is live; Sprint 6 adds deterministic workflows on top of it.

Follow along

Sprint 4 connected GitHub. Sprint 5 makes project intelligence portable. Sprint 6 teaches assistants how to run repeatable engineering work.

Read the full post on meronq.pages.dev · Source on GitHub

Sprint 4 closed: GitHub Integration

Meronq — Wed, 01 Jul 2026 20:41:01 +0000

Sprint 4 is closed.

The goal was to connect Meronq to GitHub as the first external engineering system — reading metadata, issues, and pull requests, then translating that data into CEM and local memory.

What Sprint 4 delivered

Every item on the roadmap is checked off:

Repository metadata — stars, branch, description
Issues and PRs — GitHub REST API
CEM translation — issue:owner/repo#N, pull_request:owner/repo#N
Summaries — issue and PR text summaries
Doc draft — markdown from git log + GitHub

Local MCP v1.13.0 — github_sync, github_status, github_summarize, github_doc_draft.

New package: `@meronq/github`

scanProject → CEM → fetchGitHubSnapshot → appendGithubToCem → SQLite memory

Auth: GITHUB_TOKEN (PAT). Cache: .meronq/local/github-snapshot.json.

CLI

meronq github sync
meronq github status
meronq github summarize issue 3
meronq github doc

Sprint 5 — MCP Server

Expose Meronq as a product MCP surface with handshake, memory search, and permissions.

Follow along

Read the full post on meronq.pages.dev · Source on GitHub

DEV Community: Meronq

We built a product around context cost and never measured our own tools

The fix is deliberately boring

What did not ship, and why

The lesson we actually take from this

Sprint 21 closed: keyword-first search, meaning when the string misses

Keyword first, meaning when it misses

Ranking that matches meaning, not heat

Licence and packaging

Principle

Sprint 20 closed: tools that answer questions, and traces that prove they do

Tools by intent

The empty layers get writers

Instrumentation that can prove it

Init and cold Connect

Still open

Sprint 17 closed: desktop distribution on R2 + in-app updates

What shipped

Dogfood notes

Sprint 16 closed: memory soft sync and Temperature Map UX

What shipped

Principle

Sprint 14 closed: Memory Temperature Map

Sprint 14 closed: Memory Temperature Map

What shipped

Principle

Sprint 9 closed: Desktop MVP

What Sprint 9 delivered

Architecture

Two ways to run it

Connect → inspect → run

Sprint 10 — Desktop polish and cloud spike

Follow along

Sprint 8 closed: Productization

What Sprint 8 delivered

New package: @meronq/product

Delivery phases (ADR-0008)

Sprint 9 — Desktop MVP

Follow along

Sprint 7 closed: Engineering Agents

What Sprint 7 delivered

CLI

How it fits

Sprint 8 — Productization

Follow along

Sprint 6 closed: Skills and Workflows

What Sprint 6 delivered

New package: @meronq/skills

Surfaces

Permission hardening

Pipeline

Sprint 7 — Agents

Follow along

Sprint 5 closed: MCP Server

What Sprint 5 delivered

Product vs local MCP

New package: @meronq/server-core

Permission model

Memory search

Sprint 6 — Skills and Workflows

Follow along

Sprint 4 closed: GitHub Integration

What Sprint 4 delivered

New package: @meronq/github

CLI

Sprint 5 — MCP Server

Follow along

New package: `@meronq/product`

New package: `@meronq/skills`

New package: `@meronq/server-core`

New package: `@meronq/github`