Agentic semantic layer for codebases
npm install floemaAgentic 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.
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.
``bash`
npm install -g floema
Or use directly:
`bash`
npx floema init
`bash`
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
`bash`
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"
`bashSearch for flows
floema search auth
Core Concepts
$3
A Flow is the fundamental unit in Floema. It represents a path that logic takes through your code:
typescript
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
}
`$3
Where a flow begins - exported functions, route handlers, event listeners:
typescript
interface EntryPoint {
file: string; // "src/auth/login.ts"
line: number; // 42
symbol: string; // "handleLogin"
input?: string; // "LoginRequest"
}
`$3
Significant operations along the flow:
typescript
interface Step {
file: string;
line: number;
symbol: string;
kind: 'call' | 'branch' | 'assignment' | 'await' | 'return';
}
`$3
Where the flow terminates:
typescript
interface ExitPoint {
file: string;
line: number;
kind: 'return' | 'throw' | 'external-call' | 'side-effect';
output?: string; // Return type
}
`CLI Reference
$3
Initialize Floema in the current directory.
bash
floema init
`$3
Add or update a flow.
| Flag | Required | Description |
|------|----------|-------------|
|
| 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) |$3
Search for flows using full-text search. Lists all flows if no query provided.
`bash
floema search authentication
floema search # List all flows
`$3
View detailed information about a specific flow.
bash
floema view auth-login:handleLogin
`$3
Render a flow visualization.
| Flag | Default | Description |
|------|---------|-------------|
|
| ascii | Output format: ascii, mermaid, json |`bash
ASCII art for terminal
floema render user-login --format asciiMermaid for documentation
floema render user-login --format mermaidJSON for tooling
floema render user-login --format json
`Output Formats
$3
┌──────────────────────────────────────────────────────────┐
│ 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 │
└──────────────────────────────────────────────────────────┘
$3
markdown
`mermaid
flowchart TD
subgraph user_login["user-login"]
entry["🚀 handleLogin
src/auth/login.ts:42"]
step0["📞 validateCredentials
src/auth/validate.ts:15"]
entry --> step0
step1["⏳ findUser
src/db/users.ts:23"]
step0 --> step1
step2["📞 createSession
src/auth/session.ts:8"]
step1 --> step2
exit["✅ return
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.
- 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 informationThe semantic layer evolves with the codebase through agent interaction, capturing genuine understanding rather than parsed syntax.
Integration
$3
Floema works great with Claude Code. Add slash commands or hooks to automatically maintain flows as you work.
$3
Any tool that can execute shell commands can use Floema's CLI to search and view flows.
Development
`bash
Install dependencies
npm installBuild
npm run buildRun tests
npm testDevelopment mode
npm run dev
``MIT
---
Floema: Because understanding should flow.