Research notes
Long-form briefs that informed roadmap decisions. Each file captures a moment in time: the question, the market scan, the cross-check against the product’s positioning, and the concrete recommendation that landed in the roadmap (or did not).
These are not ADRs. ADRs record a decision that was taken and
its consequences (docs/adr/). Research briefs record the
landscape that informed the decision: they cite sources, dissent
freely, and become outdated. Once a brief stops shaping the product,
it stays here as a historical receipt; it is not edited to track new
reality.
Naming convention
YYYY-MM-DD-<slug>.md
YYYY-MM-DDis the date the brief was finalised, not when the research started.<slug>is kebab-case, scope-first:v0.3-multi-context-developer,mcp-spec-2026-q3,embeddings-backend-benchmark.- One file per brief; do not bundle topics.
Document structure (skeleton)
Each brief follows the same outline so they remain comparable. New
briefs copy _template.md:
- Metadata header (date, author, scope, status, inputs).
- Executive summary: 3-4 sentences, no longer.
- Context and premisses: what triggered the brief; what stays off-limits (e.g. “v0.5 semantic layer is out of scope here”).
- Market scan: sectioned by question, each section ending in a one-line “what this means for Synapse”.
- Cross-check: what the market scan validates / challenges / adds versus the team’s prior hypotheses.
- Positioning: where this product fits versus named competitors; the moat to defend.
- Recommendation: the theme proposed, the priorities, what is explicitly not in scope.
- Disruptive bets: non-obvious ideas worth tracking even if they fall out of the current cycle.
- Ticket sketch (provisional IDs, blocks, sizes. Sketch) not issues until milestone is opened.
- Risk register: severities + mitigations.
- Open decisions: questions still requiring human direction.
- References: every external link cited above.
Index
| Date | Brief | Status |
|---|---|---|
| 2026-05-25 | v0.3: Auditable AI second brain (multi-context devs) | shipped v0.3.0; milestone #5 closed 18/18 |
| 2026-05-25 | v0.4: Refinement & extensibility | shipped v0.4.0 2026-05-27; milestone #6 closed 18/18 (12 core + 6 stretch) |
| 2026-06-02 | v0.4 closure & roadmap review | accepted; input to README §Status refresh (b37a418) and to the v0.5 brief |
| 2026-06-02 | v0.5: Semantic layer & second-brain enrichment | accepted 2026-06-02; 23 issues filed in milestone #7; SYN-89 spike + ADR-008 shipped 640116e |
| 2026-06-02 | Vector storage options vs sqlite-vec | accepted; confirms sqlite-vec for v0.5; vectorlite registered as v0.7+ upgrade path; LanceDB/SurrealDB rejected as v0.5 migrations |
| 2026-06-14 | Agent-memory field comparison | draft; validates supersession/provenance/trust/flat-vector bets; recommends trust-in-ranking, contradiction→gate, batched embedding, proposal contract, invariant eval harness |
| 2026-07-14 | Market positioning and Febasi substrate | historical draft; exclusivity/demand hypotheses qualified by 2026-10-12 design; issues #303–306 reused |
| 2026-10-12 | Typed decisions and trust | accepted evaluation protocol; local NLI/Jev not benchmarked; ADR-049–053 and implementation issues |
When a brief informs a milestone, link the milestone here in the Status column once it is opened.