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.

Backlog.md Backend

1. Set the backend type to Backlog.md:

em config set backend backlog --global

2. Configure backlog path (optional, defaults to ./backlog):

em config set backlog.path /path/to/project/backlog

3. Initialize Backlog.md in your project (if not already done):

cd /path/to/project
# Install backlog.md CLI if needed
npm i -g backlog.md
# Initialize the project
backlog init "My Project"

Note: The Backlog.md backend reads and writes markdown files directly in the backlog/tasks/ folder. The backlog CLI is not required for entity-manager operations - it only uses the markdown file format.

Entity IDs: Use Backlog.md format (e.g., task-10, task-42) when referencing entities. You can also use numeric IDs (e.g., 10, 42) and they will be automatically normalized.

Status Mapping:

• open → "To Do"
• in_progress → "In Progress"
• closed → "Done"

Dependencies: Use em link add with blocked_by type to create dependencies between tasks:

em link add task-10 task-5 --type blocked_by

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)

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

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.

Redis Backend

1. Set the backend type to Redis:

em config set backend redis --global

2. Configure Redis connection (optional, defaults shown):

# Redis server host
em config set redis.host localhost

# Redis server port
em config set redis.port 6379

# Redis database number
em config set redis.db 0

# Redis password (if authentication is required)
em config set redis.password your-redis-password --global

3. Ensure Redis server is running:

# Start Redis (command varies by OS and installation method)
redis-server

# Or with Docker
docker run -d -p 6379:6379 redis:latest

Note: Redis backend uses UUIDs as entity IDs. Data is stored in-memory by default and will be lost on Redis restart unless persistence is configured in Redis.

Performance: Redis provides sub-millisecond read/write operations, making it ideal for high-performance scenarios, caching, or distributed systems.

Persistence: Configure Redis persistence (RDB snapshots or AOF) in redis.conf if you need data to survive restarts.

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