Skip to main content
Entities are the core nodes in your knowledge graph. Each entity represents a concept, document, or piece of information stored as a markdown file.

​
Resolve Entity Identifier

Resolve a string identifier (external_id, permalink, title, or path) to entity info. 
curl -X POST https://api.basicmemory.com/v2/projects/{project_id}/knowledge/resolve \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": "specs/search",
    "strict": false
  }'

​
Request Body

​
identifier
string
required
The identifier to resolve (external_id, permalink, title, or file path)
​
source_path
string
Optional source path for context-aware resolution (prefers notes closer to source)
​
strict
boolean
default:"false"
If true, disables fuzzy search fallback and requires exact match

​
Response

​
external_id
string
Entity external UUID (stable identifier)
​
entity_id
integer
Internal entity ID
​
permalink
string
Entity permalink
​
file_path
string
File path relative to project root
​
title
string
Entity title
​
resolution_method
string
How the entity was resolved: external_id, permalink, title, path, or search

​
Get Entity by ID

Retrieve a complete entity by its external UUID. 
curl https://api.basicmemory.com/v2/projects/{project_id}/knowledge/entities/{entity_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Path Parameters

​
project_id
string
required
Project external UUID
​
entity_id
string
required
Entity external UUID

​
Response

​
external_id
string
Entity external UUID
​
title
string
Entity title
​
permalink
string
URL-friendly identifier
​
file_path
string
File path relative to project root
​
note_type
string
Entity classification (e.g., “note”, “person”, “spec”)
​
content_type
string
MIME type (e.g., “text/markdown”, “image/png”)
​
content
string
File content (for text files)
​
observations
array
List of observations (facts) about this entity
​
relations
array
List of relations to other entities
​
created_at
string
ISO 8601 timestamp
​
updated_at
string
ISO 8601 timestamp

​
Create Entity

Create a new entity in the knowledge graph. 
curl -X POST https://api.basicmemory.com/v2/projects/{project_id}/knowledge/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My New Note",
    "directory": "notes",
    "note_type": "note",
    "content": "# My New Note\n\nThis is the content."
  }'

​
Request Body

​
title
string
required
Entity title (becomes filename)
​
directory
string
required
Directory path relative to project root
​
note_type
string
default:"note"
Entity classification (converted to snake_case)
​
content
string
File content (markdown for text files)
​
content_type
string
default:"text/markdown"
MIME type of content
​
entity_metadata
object
Optional metadata dictionary

​
Query Parameters

​
fast
boolean
default:"true"
If true, defers indexing to background tasks for faster response

​
Response

Returns the created entity with HTTP status 201 Created.
​
external_id
string
Generated UUID for the new entity
​
permalink
string
Generated permalink
See Get Entity for full response schema.

​
Update Entity

Update an existing entity by external UUID (upsert behavior). 
curl -X PUT https://api.basicmemory.com/v2/projects/{project_id}/knowledge/entities/{entity_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Title",
    "directory": "notes",
    "note_type": "note",
    "content": "# Updated Title\n\nUpdated content."
  }'

​
Path Parameters

​
entity_id
string
required
Entity external UUID

​
Request Body

Same as Create Entity request body.

​
Query Parameters

​
fast
boolean
default:"true"
If true, defers indexing to background tasks

​
Response

Returns HTTP status 200 OK if entity was updated, or 201 Created if entity was created.

​
Edit Entity

Edit an existing entity using operations like append, prepend, or find/replace. 
curl -X PATCH https://api.basicmemory.com/v2/projects/{project_id}/knowledge/entities/{entity_id} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "append",
    "content": "\n\nNew content to append."
  }'

​
Request Body

​
operation
string
required
Edit operation: append, prepend, find_replace, or replace_section
​
content
string
required
Content to insert or replace with
​
section
string
Section name for replace_section operation
​
find_text
string
Text to find for find_replace operation
​
expected_replacements
integer
default:"1"
Expected number of replacements for find_replace (validation)

​
Query Parameters

​
fast
boolean
default:"true"
If true, defers indexing to background tasks

​
Response

Returns the updated entity.

​
Delete Entity

Delete an entity by external UUID. 
curl -X DELETE https://api.basicmemory.com/v2/projects/{project_id}/knowledge/entities/{entity_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

​
deleted
boolean
True if entity was deleted, false if entity didn’t exist (idempotent)

​
Move Entity

Move an entity to a new file location. 
curl -X PUT https://api.basicmemory.com/v2/projects/{project_id}/knowledge/entities/{entity_id}/move \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_path": "archive/old-note.md"
  }'

​
Request Body

​
destination_path
string
required
New file path relative to project root

​
Response

Returns the updated entity with new file path. The external_id remains stable.

​
Move Directory

Move all entities in a directory to a new location. 
curl -X POST https://api.basicmemory.com/v2/projects/{project_id}/knowledge/move-directory \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_directory": "drafts",
    "destination_directory": "archive/2026"
  }'

​
Request Body

​
source_directory
string
required
Source directory path
​
destination_directory
string
required
Destination directory path

​
Response

​
total_files
integer
Total number of files in source directory
​
successful_moves
integer
Number of files successfully moved
​
failed_moves
integer
Number of files that failed to move
​
moved_files
array
List of file paths that were moved
​
errors
array
List of errors for failed moves

​
Delete Directory

Delete all entities in a directory. 
curl -X POST https://api.basicmemory.com/v2/projects/{project_id}/knowledge/delete-directory \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "directory": "archive/old"
  }'

​
Request Body

​
directory
string
required
Directory path to delete

​
Response

​
total_files
integer
Total number of files in directory
​
successful_deletes
integer
Number of files successfully deleted
​
failed_deletes
integer
Number of files that failed to delete
​
deleted_files
array
List of file paths that were deleted
​
errors
array
List of errors for failed deletes

Build docs developers (and LLMs) love

Get started for freeTalk to us