Knowledge Graph
The knowledge graph is the core of Memory. It stores objects (nodes) and relationships (edges) in a typed, versioned, searchable graph.
Concepts
Section titled “Concepts”| Concept | Description |
|---|---|
| Object | A typed node in the graph (e.g. a Decision, Person, Requirement) |
| Relationship | A directed, typed edge between two objects (e.g. depends_on, authored_by) |
| Type | The schema that defines valid properties for an object or relationship |
| CanonicalID | Stable ID for an object across versions — use this to reference an object |
| VersionID | The ID of a specific version of an object (changes on every edit) |
| Branch | An isolated copy of the graph for safe editing; see Branches |
Object Types
Section titled “Object Types”Types are defined by your project’s installed template packs or custom type definitions. Common built-in types include:
Decision— architectural or strategic decisionsRequirement— product or technical requirementsPerson— individuals mentioned in documentsMeeting— meeting records with participants and outcomesRisk— identified risks with severity and mitigation
List available types for your project:
GET /api/type-registry/projects/{projectId}Creating Objects
Section titled “Creating Objects”memory graph objects create \ --type Decision \ --properties '{"title": "Use PostgreSQL", "status": "approved", "rationale": "Existing expertise"}' \ --project my-project
# With a stable key for idempotent operations (skip if already exists):memory graph objects create \ --type Decision \ --key "decision-use-postgresql" \ --properties '{"title": "Use PostgreSQL", "status": "approved"}' \ --project my-project
# --upsert creates-or-updates by key:memory graph objects create \ --type Decision \ --key "decision-use-postgresql" \ --properties '{"title": "Use PostgreSQL", "status": "approved"}' \ --upsert --project my-projectPOST /api/graph/objectsContent-Type: application/json
{ "type": "Decision", "properties": { "title": "Use PostgreSQL as primary database", "status": "approved", "rationale": "Team expertise and existing infrastructure" }, "labels": ["architecture", "database"]}Response includes both id (version) and canonical_id (stable reference).
Object fields
Section titled “Object fields”| Field | Description |
|---|---|
type |
Object type name (must exist in the type registry) |
properties |
Key-value map of typed properties per the type schema |
labels |
Free-form string tags for filtering and organization |
status |
Optional status flag (e.g. draft, approved, archived) |
name |
Human-readable title shown in the UI and ranked first in search |
ref |
Read-only display reference (# + last 12 hex of the canonical ID); never used for writes |
canonical_id / entity_id |
Stable canonical UUID — the addressable handle for reads, writes, and relationships (id is the version id) |
key |
Internal dedup/upsert identity; not a display label |
Creating Relationships
Section titled “Creating Relationships”POST /api/graph/relationshipsContent-Type: application/json
{ "type": "depends_on", "src_id": "<canonical_id of source object>", "dst_id": "<canonical_id of target object>", "properties": { "note": "Must be resolved before deployment" }}Relationships are directed: src → dst. Use type to describe the semantic of the edge.
Bulk creating objects and relationships
Section titled “Bulk creating objects and relationships”For more than a handful of objects, use the batch commands instead of one API call per node:
# Objects only: a JSON array of {type, name, description, properties}memory graph objects create-batch --file objects.json
# Objects + relationships: a subgraph with _ref/src_ref/dst_ref placeholdersmemory graph objects create-batch --file subgraph.json
# Relationships only: a JSON array of {type, from, to}memory graph relationships create-batch --file relationships.jsonBoth commands accept --branch <name-or-uuid> to write into a graph branch
instead of the main graph. Objects are chunked to the server’s per-call limit
(500 for a subgraph, 100 per bulk item), and each row reports its own error
instead of failing the whole batch.
create-batch on objects also reads the JSONL seed layout written by
memory blueprints dump — pass the dump root, a seed/ directory, or a single
.jsonl file. Records are upserted by key and relationship srcKey/dstKey
endpoints are resolved after the objects are written, so dump → edit → import
into a branch is a complete migration loop:
memory blueprints dump ./migrationmemory graph objects create-batch --file ./migration --branch migration-reviewSee Branches § Bulk importing a dump into a branch.
Updating Objects
Section titled “Updating Objects”PATCH /api/graph/objects/{id}Content-Type: application/json
{ "properties": { "status": "superseded", "supersededBy": "Use CockroachDB" }}Every update creates a new version row. The previous version is preserved in history.
Searching
Section titled “Searching”Hybrid search (recommended)
Section titled “Hybrid search (recommended)”Combines keyword, semantic, and graph structure in a single ranked result:
memory query "decisions about database architecture" --project my-projectPOST /api/graph/search{ "query": "decisions about database architecture", "types": ["Decision"], "limit": 20}Full-text search
Section titled “Full-text search”GET /api/graph/objects/fts?q=postgresql&types=DecisionVector (semantic) search
Section titled “Vector (semantic) search”POST /api/graph/objects/vector-search{ "query": "scalability trade-offs", "topK": 10}Filter by type, label, or status
Section titled “Filter by type, label, or status”GET /api/graph/objects/search?type=Decision&status=approved&labels=architectureViewing Object History
Section titled “Viewing Object History”Every change is versioned. Retrieve the full revision history:
GET /api/graph/objects/{id}/historyRestore a previous version:
POST /api/graph/objects/{id}/restore{ "versionId": "<old-version-id>" }Traversal and Expansion
Section titled “Traversal and Expansion”Get all edges for an object
Section titled “Get all edges for an object”GET /api/graph/objects/{id}/edgesExpand a subgraph from a starting node
Section titled “Expand a subgraph from a starting node”POST /api/graph/expand{ "objectId": "<canonical_id>", "depth": 2, "relationshipTypes": ["depends_on", "authored_by"]}Traverse by relationship path
Section titled “Traverse by relationship path”POST /api/graph/traverse{ "startId": "<canonical_id>", "direction": "outbound", "maxDepth": 3}Find similar objects
Section titled “Find similar objects”GET /api/graph/objects/{id}/similar?limit=5Bulk Operations
Section titled “Bulk Operations”POST /api/graph/objects/bulk # create multiple objectsPOST /api/graph/relationships/bulk # create multiple relationshipsPOST /api/graph/objects/bulk-update-status # update status on many objects at onceDeleting Objects
Section titled “Deleting Objects”Deletion is soft — the object is marked deleted_at but preserved in history.
DELETE /api/graph/objects/{id}To restore:
POST /api/graph/objects/{id}/restoreAnalytics
Section titled “Analytics”GET /api/graph/analytics/most-accessed # objects viewed most recentlyGET /api/graph/analytics/unused # objects with no recent access