Core Concepts

The mental model behind NeuralSnap. Understand these building blocks and everything else — the API, integrations, the graph — clicks into place.

Neural Snapshots

A Neural Snapshot is the atomic unit of knowledge in NeuralSnap. It's a structured thought-crystal that captures not just what you think, but why you think it, how to apply it, and how to challenge it. Every snapshot contains up to 16 fields:

Property	Type	Description
`name`*	string	Short title — the idea in ≤10 words.
`type`*	enum	Category: Belief, Model, Rule, Conviction, or Principle.
`core`*	string	The core insight in one sentence. The 'so what?'
`one_liner`	string	A punchy, tweetable summary of the insight.
`story`	string	The origin story — how you arrived at this knowledge.
`moment`	string	The specific moment or event that crystallised the insight.
`emotion`	string	The dominant emotion tied to this knowledge (e.g. surprise, frustration, clarity).
`source`	string	Where it came from — a book, conversation, meeting, experience.
`trigger_pattern`	string	The situation or cue that activates this knowledge.
`method`	string	How to apply the insight — the playbook.
`steps`	string[]	Concrete action steps to execute the method.
`filter`	string	When this insight does NOT apply — boundary conditions.
`challenge`	string	The strongest counter-argument or alternative view.
`break_test`	string	What evidence would make you abandon this belief?
`risks`	string	What could go wrong if you follow this blindly?
`proof`	string	Evidence, data, or examples supporting the insight.
`confidence`	number	How sure you are (0–1). Updated as evidence accumulates.
`significance_score`	number	How important this is to your thinking (0–1).
`tags`	string[]	Free-form labels for organisation and filtering.

Only 3 fields are required

You can create a snapshot with just name, type, and core. The remaining fields enrich the snapshot and improve search quality, but they're optional — especially useful when the crystallization pipeline fills them in automatically.

Brains

A Brain is a collection of snapshots owned by a single user. When you create an account a default brain is provisioned automatically — all snapshots you create are stored there unless you specify otherwise.

Ownership: Each brain belongs to exactly one user. Snapshots inside a brain are private by default.
Default brain: Created on signup. The API uses it implicitly if no brain ID is supplied.
Collections: Use tags and snapshot types to organise knowledge inside a brain — no sub-folder hierarchy needed.

Crystallization Pipeline

The crystallization pipeline turns unstructured text into structured Neural Snapshots in three phases. You send raw text to the POST /crystallize endpoint and get back fully-formed snapshots — no manual structuring required.

Raw Text

Extract

Decompose text into atomic claims

Synthesize

Merge related claims into coherent insights

Crystallize

Structure each insight into a 16-field snapshot

Snapshots

Extract — The input text is decomposed into discrete, atomic claims. Each claim captures a single idea or assertion.
Synthesize — Related claims are merged and de-duplicated into coherent insights. Redundancy is removed, context is preserved.
Crystallize — Each synthesised insight is structured into a full 16-field Neural Snapshot, complete with method, challenge, confidence scores, and tags.

Semantic Search

NeuralSnap converts every snapshot into a high-dimensional vector embedding at creation time. When you search, your query is also embedded and compared against your snapshot vectors using cosine similarity.

	Keyword Search	Semantic Search
Matching	Exact token overlap	Meaning-based similarity
Synonyms	❌ Miss them	✅ Handled automatically
Typos	❌ Break results	✅ Largely resilient
Example	"video marketing" won't find "short-form content"	"video marketing" matches "short-form content" by meaning

Embeddings are generated server-side — you don't need to manage vectors yourself. Just call the search endpoint with a natural-language query.

Snapshot Types

Every snapshot is categorised into one of five types. The type influences how the crystallization pipeline structures the output and helps you filter and reason about your knowledge.

BeliefA subjective conviction about how the world works, shaped by personal experience.

ModelA mental framework or system for understanding a domain — a "how it works" map.

RuleA prescriptive guideline — something you follow, or think others should.

ConvictionA strongly-held, evidence-backed position you're willing to act on.

PrincipleA foundational truth that guides decisions across contexts.

Confidence & Significance

Two numeric scores — both ranging from 0 to 1 — let you quantify how sure you are and how much the idea matters.

Confidence

How sure are you? A confidence of 0.5 means "it's a hunch"; 0.95 means "I'd bet money on it". Confidence should evolve — increase it when you find supporting evidence, decrease it when you encounter counter-arguments. The break_test field captures what would push it towards zero.

Significance Score

How much does it matter? A minor observation might score 0.2; a career-defining insight could score 0.95. Significance helps you prioritise — filter your brain to surface high-impact knowledge first, and let the low-significance notes stay in the background until you need them.

Both scores are optional. If you omit them, the crystallization pipeline will estimate values automatically based on the source text.

Quickstart

Crystallization Guide