Core Concepts

Apart Intelligence stores knowledge as a graph — nodes connected by edges, organized into domains, and viewed through workspaces. This page explains each concept and how they work together.

Nodes

A node is a single unit of knowledge. Every node has a type, a title, a content body (markdown), and a status that controls visibility.

Node Types

Type	Purpose	Example
`architecture`	How something is built	"Event-Driven Architecture"
`note`	What something does, or general knowledge	"Assignment Resolution"
`process`	How to do something	"Deployment Process"
`policy`	Rules and constraints	"Data Retention Policy"
`decision`	Why something was chosen	"Why PostgreSQL over MongoDB"
`module`	Source file summary (auto-generated)	Created by `ai map`
`function` / `method` / `class`	Code chunks (auto-generated)	Created by `ai map`

The first five types are human-curated. The last three are machine-generated by the codebase mapping feature.

Node Lifecycle

Every node follows a four-stage lifecycle:

Draft — newly captured, hidden from search by default
Reviewed — examined but not yet official
Approved — verified and visible in all search results
Archived — outdated, hidden from search but preserved

ai drafts                  # list pending items
ai status <id> approved    # approve for search
ai status <id> archived    # archive without deleting

Edges

Edges are typed, directed relationships between nodes. They encode structural connections that semantic search alone can't capture.

ai link <source-id> <target-id> --rel "depends-on"
ai link <source-id> <target-id> --rel "implements" --weight 0.8

Common Edge Types

Type	Meaning	Created by
`contains`	Structural hierarchy	`ai map`
`imports`	Code dependency	`ai map`
`documents`	Documentation link	Human
`implements`	Architecture → feature	Human
`depends-on`	Service/component dependency	Human

Tip

Don't over-link. Semantic search already finds related nodes without edges. Use edges for structural relationships that embeddings can't capture.

Domains

Domains are a hierarchical taxonomy for organizing nodes. They power workspace filtering — a workspace can include only nodes in specific domains.

ai domains seed            # populate default taxonomy
ai domains list            # show the tree
ai add "..." --domain architecture   # assign when creating

The default taxonomy includes broad categories like Technology, Products, Operations, and Strategy, each with subcategories. Use the subcategories that fit your needs — you don't need to use all of them.

Note

If you're agonizing over which domain to pick, the taxonomy is too granular for your use case. Pick the closest one — the embeddings handle semantic similarity regardless of domain assignment.

Workspaces

Workspaces are named filter presets that create focused views of the knowledge graph. They are consumption interfaces, not storage categories — the same node can appear in multiple workspaces if it matches their filters.

# Create a workspace
ai workspace create tasks-engineering \
  --description "Architecture and code for the Tasks service" \
  --domains "architecture,development" \
  --types "architecture,policy,module,function,method,class"

# Use it
ai workspace use tasks-engineering
ai search "assignment resolution"       # filtered to engineering context

# Or pass explicitly
ai context "deployment" --workspace tasks-ops

Recommended Pattern

Three workspaces per product/service:

Workspace	Domains	Types	Purpose
`{product}-engineering`	architecture, development	architecture, policy, module, function, method, class	Technical context including code
`{product}-product`	products, design	note, decision	Business features and decisions
`{product}-ops`	delivery, quality	process, policy	Operations and deployment

The engineering workspace includes code types so that searching for a concept returns both the documentation and the implementation. This is the key advantage of mapping code alongside business documentation.

Search

Search combines two strategies and merges results using Reciprocal Rank Fusion (RRF):

Semantic search— converts your query to a vector embedding and finds nodes with similar meaning, even when exact words don't match
Keyword search — PostgreSQL full-text search for precise term matches

The default blend is 60% semantic, 40% keyword. This means searching "deployment process" will find a node titled "Release Pipeline" (semantic match) alongside one containing the exact phrase (keyword match).

Context Assembly

Context assembly goes beyond search by following graph edges to discover related knowledge:

Finds seed nodes via hybrid search
Traverses edges from each seed (configurable depth)
Returns all discovered nodes with their connecting edges

This is how AI tools get comprehensive context — a query about "assignment resolution" finds not just that node, but the workflow engine it connects to, the task service that invokes it, and the data model it operates on.