Core Concepts

NeuralRepo is built around a few core concepts. Understanding them will help you get the most out of the platform.

Ideas

An idea is the atomic unit in NeuralRepo. Every idea has:

Field	Description
Title	A short, descriptive name (required)
Body	Longer description or notes in Markdown (optional)
Status	Current stage in your workflow
Source	Where the idea was captured from
Tags	User-defined labels for categorization
Relations	Connections to other ideas
Links	External URLs and references

Ideas are designed to be lightweight. Capture first, organize later.

Status Workflow

Every idea is in exactly one of five statuses. The usual path runs left to right, but nothing enforces the order — any status can move to any other status.

captured → exploring → building → shipped
                                    ↺
               (any status) ⇄ shelved

Status	Meaning
`captured`	Just recorded — hasn’t been evaluated yet
`exploring`	Actively thinking about or researching this idea
`building`	Implementation is underway
`shipped`	The idea has been realized and delivered
`shelved`	Parked for later — not abandoned, just not active

The web dashboard provides a kanban board view where you can drag and drop ideas between status columns.

Sources

The source field records where an idea was originally captured. It is set automatically and cannot be changed after creation.

Source	Origin
`web`	Created in the web dashboard
`cli`	Created via the `nrepo` CLI
`claude-mcp`	Created by Claude AI through MCP
`siri`	Created via Siri Shortcuts
`email`	Created by sending an email to `idea@neuralrepo.com`
`api`	Created via the REST API directly, and by the AI agent’s own tools
`shortcut`	Created via an Apple Shortcut (non-Siri)
`ios`	Created in the native NeuralRepo iOS app

Sources are useful for filtering and understanding your capture habits. You can filter by source in the web dashboard and in the API. A source is chosen by the client that creates the idea, so a REST API caller may set any of these values on itself.

Relations

Relations create typed, directional connections between ideas. Every relation has a source idea, a target idea, and a type.

Type	Meaning	Example
`related`	General association	”Auth service” ↔ “OAuth provider research”
`parent`	Hierarchical grouping	”Mobile app” → “Push notifications feature”
`blocks`	Dependency	”Design system” blocks “Dashboard redesign”
`inspires`	One idea led to another	”Competitor analysis” inspires “Freemium pricing model”
`duplicate`	Same idea captured twice	Auto-detected or manually set
`supersedes`	Replaces an older idea	”Auth v2” supersedes “Auth v1”

Relations are directional — the source and target matter. For example, “A blocks B” means A must be completed before B can proceed. The related type is the exception; it is treated as bidirectional.

Some relations are created for you: related links come from similarity scoring, and giving an idea a parent_id creates a parent relation. Creating relations by hand — in the web app, the CLI, the API, or MCP — requires Pro; free accounts see the graph read-only.

Links

Links attach external resources to an idea. Each link has a type and a URL.

Type	Use Case
`url`	Any web URL — articles, docs, references
`claude-chat`	Link to a Claude conversation that relates to the idea
`github-repo`	Link to a GitHub repository
`github-issue`	Link to a specific GitHub issue or PR

An idea can have multiple links. Links help bridge the gap between ideation and execution — connect your idea to the code, conversation, or research that supports it.

Links are URLs only — every link type stores an address, not a file. (The API also accepts a fifth type, attachment, but nothing in the product uploads files today.)

Duplicate Detection

NeuralRepo uses vector similarity to detect potential duplicates. Detection is asynchronous — it runs after the idea is saved, never before:

Saving an idea queues it; the queue worker generates a vector embedding of title and body
The embedding is compared against your five nearest ideas, skipping shelved ones
A match above the dedup threshold (default 0.75) records a pending duplicate detection
You resolve it by merging or dismissing, from the Duplicates or Review view, the CLI, or the API

Duplicate detection is a Pro feature, but it runs for everyone: detections are recorded in the background on the free plan and simply not shown, so they are all waiting for you the moment you upgrade. Marking two ideas as duplicates by hand needs Pro too, because it means creating a relation.

Idea Graph

The idea graph is the network formed by all your ideas and their relations. NeuralRepo visualizes this as an interactive mind map in the web dashboard.

The mind map lets you:

See clusters of related ideas at a glance
Discover hidden connections between projects
Identify blocking dependencies
Navigate between ideas by clicking nodes

The mind map lives in the web dashboard under the Mind Map tab. Free-tier users get view-only access; editing the graph (dragging, linking, status changes) and the AI agent require Pro.

AI Agent

The AI agent is a conversational assistant built into the web app. You can ask it to search your ideas, create new ones, discover connections, brainstorm variations, summarize clusters, score ideas, and draft documents — all in natural language.

The agent is available in two places:

Agent — a full split-pane view with a chat panel and an artifact canvas
Mind Map chat panel — a floating overlay on the mind map where tool results animate directly onto the graph

The agent supports five models: Anthropic’s Sonnet, Haiku, and Opus via BYOK, plus two Workers AI models — GPT-OSS 120B (the default) and Qwen 30B — that need no API key.

See the AI Agent section for complete documentation.

Start Capturing

Now that you understand the concepts, head to the Quick Start to begin capturing ideas.

Explore the API

Build custom integrations using the REST API with full access to ideas, relations, and links.