Entity Manager

An entity manager for LLMs.

Purpose

Entity Manager is a tool designed to enable LLMs to work efficiently with structured data in a directed graph format. It addresses two key use cases:

1. External Data Source Integration

Entity Manager can interact with external data sources such as GitHub issues, Beads, Notion, Jira, Linear, and more. It maintains a local synchronized copy that LLMs can quickly interact with without repeatedly calling remote APIs. This provides:

• Fast local queries: No latency from API calls
• Reduced API rate limits: Minimize external service usage
• Offline capability: Work with cached data when services are unavailable
• Unified interface: Single API across different backends

2. LLM Collaboration on Complex Projects

The main purpose of Entity Manager is to enable multiple LLM agents to collaborate effectively on large, complex projects. It addresses a critical challenge in AI-assisted development: ensuring only one agent works on a requirement at a time while properly tracking dependencies.

Without such a system:

• Multiple agents might work on the same requirement simultaneously
• Dependencies between requirements are hard to track
• Work coordination becomes chaotic as team size grows
• Progress visibility is limited

Entity Manager solves this by:

• Task creation and assignment: Create entities representing requirements and assign them to specific agents
• Dependency tracking: Use directed links (e.g., "blocked-by") to express relationships between requirements
• Status management: Track the state of each requirement (open, in-progress, closed)
• Collision prevention: Agents can query which tasks are assigned, avoiding duplicate work
• Progress visibility: See what's being worked on and what's blocked

Installation

uv tool install git+https://github.com/TomzxCode/entity-manager

Setup

Configuration can be stored in two locations:

• Local config: .entity-manager/config.yaml in the current directory (repository-specific)
• Global config: ~/.entity-manager/config.yaml in your home directory (user-wide)

By default, commands use local config with global fallback. Use the --global flag to explicitly target global config.

GitHub Backend

1. Set the backend type to GitHub (global):

em config set backend github --global

2. Configure GitHub repository (can be local or global):

# Local (repository-specific)
em config set github.owner your-username
em config set github.repository your-repo

# Or global (user-wide default)
em config set github.owner your-username --global
em config set github.repository your-repo --global

3. Set your GitHub token:

em config set github.token your-github-personal-access-token --global

Create a GitHub personal access token with repo scope at https://github.com/settings/tokens

Beads Backend

1. Set the backend type to Beads:

em config set backend beads --global

2. Configure project path (optional, defaults to current directory):

em config set beads.project_path /path/to/project

3. Install beads from https://github.com/steveyegge/beads and initialize in your project:

cd /path/to/project
bd init

Note: With beads backend, entity IDs use the beads hash format (e.g., bd-a1b2 instead of numeric IDs)

Notion Backend

1. Set the backend type to Notion:

em config set backend notion --global

2. Configure Notion integration:

# Set your Notion integration token
em config set notion.token your-notion-integration-token --global

# Set the database ID to use for entities
em config set notion.database_id your-database-id

3. Create a Notion integration and get your token at https://www.notion.so/my-integrations

4. Database Schema Requirements: Your Notion database should have the following properties:

• Name (Title) - Entity title
• Description (Rich Text) - Entity description
• Status (Status) - Entity status (open, in progress, closed, etc.)
• Labels (Multi-select) - Entity labels/tags
• Assignee (People) - Entity assignee
• Blocked By (Relation) - Links to blocking entities
• Blocking (Relation) - Links to blocked entities
• Parent (Relation) - Parent entity link
• Children (Relation) - Child entity links

Note: Notion backend uses page IDs (UUIDs with hyphens) as entity IDs.

Concepts

• Entity: A core object that holds data and metadata.
• Attributes: Key-value pairs that store information about an entity.
• Links: Relationships between entities, which can be of various types.

Usage

Create

em create "title"
em create "title" --description "description" --labels "type:bug,priority:0,status:open" --assignee alice

Read

em read 123

Update

em update 123 --title "new title"
em update 123 --description "new description"
em update 123 --labels "x,y,z"
em update 123 --status "open/in-progress/closed"
em update 123 --title "new title" --description "new description" --labels "x,y,z" --status "open/in-progress/closed"

Delete

em delete 123
em delete 123 456 789

List

em list --filter "status=open" --sort "property" --limit n

Link

em link add 123 456 789 --type "relation-type"
em link remove 123 456 789 --type "relation-type" --recursive
em link list 123 --type "relation-type"

# Displays the link tree of an entity
em link tree 123

# Finds and displays cycles in links
em link cycle

Configuration

Configuration supports both local (.entity-manager/config.yaml) and global (~/.entity-manager/config.yaml) scopes. Use --global to target global config, otherwise local config is used with global fallback.

# Sets a configuration setting
em config set key value           # Local
em config set key value --global  # Global

# Unsets a configuration setting
em config unset key           # Local
em config unset key --global  # Global

# Gets the value of a configuration setting
em config get key           # Local with global fallback
em config get key --global  # Global only

# Lists all configuration settings
em config list           # Merged local + global
em config list --global  # Global only