Floema

Agentic semantic layer for codebases

Floema creates a navigable mental model of your code. Instead of drowning AI agents in raw source files, Floema provides structured flows - the paths logic takes through your codebase.

Named after the plant tissue (phloem) that carries nutrients through living systems, Floema carries understanding through code.

Why Floema?

AI agents struggle with large codebases. They either:

• Get overwhelmed by too much context
• Miss crucial connections by seeing too little
• Waste tokens re-discovering the same patterns

Floema solves this by externalizing the agent's understanding into a queryable semantic layer.

Installation

npm install -g floema

Or use directly:

npx floema init

Quick Start

1. Initialize in your project

cd your-project
floema init

This creates a .floema/ directory with:

• events.jsonl - Append-only event log (git-trackable)
• floema.db - SQLite database with full-text search

2. Add flows

floema add \
  --name "user-login" \
  --entry-file "src/auth/login.ts" \
  --entry-line 42 \
  --entry-symbol "handleLogin" \
  --entry-input "LoginRequest" \
  --exit-file "src/auth/login.ts" \
  --exit-line 87 \
  --exit-kind "return" \
  --exit-output "AuthResponse" \
  --description "Authenticates user credentials and returns session token"

3. Search and view

# Search for flows
floema search auth

# View a specific flow
floema view auth-login:handleLogin

# Render visualization
floema render auth-login:handleLogin --format mermaid

Core Concepts

Flows

A Flow is the fundamental unit in Floema. It represents a path that logic takes through your code:

interface Flow {
  id: string;           // Unique identifier
  name: string;         // Human-readable name
  entry: EntryPoint;    // Where the flow starts
  steps: Step[];        // Operations along the path
  exit: ExitPoint;      // Where the flow ends
  description?: string; // What this flow does
}

Entry Points

Where a flow begins - exported functions, route handlers, event listeners:

interface EntryPoint {
  file: string;    // "src/auth/login.ts"
  line: number;    // 42
  symbol: string;  // "handleLogin"
  input?: string;  // "LoginRequest"
}

Steps

Significant operations along the flow:

interface Step {
  file: string;
  line: number;
  symbol: string;
  kind: 'call' | 'branch' | 'assignment' | 'await' | 'return';
}

Exit Points

Where the flow terminates:

interface ExitPoint {
  file: string;
  line: number;
  kind: 'return' | 'throw' | 'external-call' | 'side-effect';
  output?: string;  // Return type
}

CLI Reference

floema init

Initialize Floema in the current directory.

floema init

floema add

Add or update a flow.

| Flag | Required | Description | |------|----------|-------------| | --name | Yes | Flow name | | --entry-file | Yes | Entry point file path | | --entry-line | Yes | Entry point line number | | --entry-symbol | Yes | Entry point symbol name | | --entry-input | No | Input type signature | | --exit-file | Yes | Exit point file path | | --exit-line | Yes | Exit point line number | | --exit-kind | Yes | Exit kind: return, throw, external-call, side-effect | | --exit-output | No | Output type signature | | --steps | No | Steps as JSON array | | --description | No | Flow description | | --id | No | Custom flow ID (auto-generated if omitted) |

floema search [query]

Search for flows using full-text search. Lists all flows if no query provided.

floema search authentication
floema search          # List all flows

floema view <flow-id>

View detailed information about a specific flow.

floema view auth-login:handleLogin

floema render <flow-id>

Render a flow visualization.

| Flag | Default | Description | |------|---------|-------------| | --format | ascii | Output format: ascii, mermaid, json |

# ASCII art for terminal
floema render user-login --format ascii

# Mermaid for documentation
floema render user-login --format mermaid

# JSON for tooling
floema render user-login --format json

Output Formats

ASCII

┌──────────────────────────────────────────────────────────┐
│                    Flow: user-login                      │
├──────────────────────────────────────────────────────────┤
│  ENTRY                                                   │
│    handleLogin                                           │
│    src/auth/login.ts:42                                  │
│    input: LoginRequest                                   │
│                                                          │
│                            ↓                             │
│                                                          │
│  STEPS                                                   │
│    [call] validateCredentials                            │
│      src/auth/validate.ts:15                             │
│    [await] findUser                                      │
│      src/db/users.ts:23                                  │
│    [call] createSession                                  │
│      src/auth/session.ts:8                               │
│                                                          │
│                            ↓                             │
│                                                          │
│  EXIT                                                    │
│    [return]                                              │
│    src/auth/login.ts:87                                  │
│    output: AuthResponse                                  │
└──────────────────────────────────────────────────────────┘

Mermaid

```mermaid
flowchart TD
    subgraph user_login["user-login"]
        entry["🚀 handleLogin<br/>src/auth/login.ts:42"]
        step0["📞 validateCredentials<br/>src/auth/validate.ts:15"]
        entry --> step0
        step1["⏳ findUser<br/>src/db/users.ts:23"]
        step0 --> step1
        step2["📞 createSession<br/>src/auth/session.ts:8"]
        step1 --> step2
        exit["✅ return<br/>src/auth/login.ts:87"]
        step2 --> exit
    end
```

Architecture

Floema uses an event-sourced architecture:

┌─────────────┐     ┌──────────────────┐     ┌─────────────┐
│   CLI       │────▶│  events.jsonl    │────▶│  floema.db  │
│  Commands   │     │  (Event Log)     │     │  (SQLite)   │
└─────────────┘     └──────────────────┘     └─────────────┘
                           │
                           ▼
                    Git-trackable
                    Audit history

• events.jsonl: Append-only log of all flow changes. Git-trackable, auditable.
• floema.db: SQLite database rebuilt from events. Fast queries with FTS5 full-text search.

Agent-Driven Philosophy

Floema is designed to be agent-driven. Rather than static analysis, flows are created and updated by AI agents as they work:

1. floema init - Agent initializes the semantic layer
2. floema add - Agent adds flows as it understands code
3. floema search - Agent searches for relevant context
4. floema view - Agent retrieves focused information

The semantic layer evolves with the codebase through agent interaction, capturing genuine understanding rather than parsed syntax.

Integration

Claude Code

Floema works great with Claude Code. Add slash commands or hooks to automatically maintain flows as you work.

Other AI Tools

Any tool that can execute shell commands can use Floema's CLI to search and view flows.

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Development mode
npm run dev

License

MIT

Floema: Because understanding should flow.