engram

Languages: English | 简体中文

A text-only conversational agent with a Planner → Manager → Executor pipeline (LangGraph), optional Neo4j + Graphiti memory graph, and a React + Vite frontend. Secrets live in .env, not in code.

Engram (neuroscience): the physical trace of a memory in the brain—aligned with “dialogue agent + persistent memory graph.”

Screenshots

| Chat (streaming + sessions) | Memory graph (Neo4j / vis-network) | |------------------------------|-------------------------------------| | | |

---

Features

• Agent workflow: Planner (JSON mode structured plan) routes work to role-based executors; Manager schedules steps; executors call the LLM (streaming for replies).
• Chat UI: SSE streaming, session list, history restored from the server after refresh.
• Memory graph: Optional Graphiti episodes + Neo4j; vis-network page embeddable from the frontend.
• Persistence: DATABASE_URL or default SQLite at backend/data/engram.db.
• Extensible roles: executors_config.yaml + optional Python executor classes.

Requirements

• Backend: Python 3.11+ recommended, uv
• Frontend: Node 18+ / npm
• Optional: Neo4j for the memory graph; OpenAI-compatible LLM API

Repository layout

engram/
├── docs/static/screenshots/ # UI screenshots (README)
├── backend/                 # FastAPI, uv
│   ├── main.py              # Entry, port 5000 by default
│   ├── config.py            # Loads .env
│   ├── executors_config.yaml
│   ├── core/                # planner, manager, base_executor, state
│   ├── executors/           # registry + custom executors
│   ├── tools/               # @tool definitions → ALL_TOOLS
│   ├── tools_lib/           # TOOL_REGISTRY, get_tools_by_names
│   ├── graph/               # LangGraph workflow
│   ├── services/            # agent SSE, Graphiti, session store
│   ├── routes/              # /api/chat, /api/kg/*, sessions
│   ├── models/              # SQLAlchemy (conversations / messages)
│   └── templates/           # kg_graph.html (vis-network)
└── frontend/                # React (Vite), port 3000
    └── src/pages/           # ChatPage, MemoryGraphPage

Quick start

Backend

cd engram/backend
cp .env.example .env
# Edit .env: LLM_API_KEY, LLM_BASE_URL, LLM_MODEL, etc.

uv sync
# Production-style (no auto-reload on file changes)
uv run python main.py
# Dev hot reload:
#   UVICORN_RELOAD=1 uv run python main.py
#   # or: uv run uvicorn main:app --reload --port 5000

• API base: http://localhost:5000
• OpenAPI: http://localhost:5000/docs

Frontend

cd engram/frontend
npm install
npm run dev

• App: http://localhost:3000 (Vite proxies /api to localhost:5000 in dev)

Conversation & session HTTP API

| Method | Path | Description | |--------|------|-------------| | GET | /api/sessions | sessions (ids) + conversations (session_id, title, updated_at) | | GET | /api/sessions/{session_id}/messages | Full message list for reload/hydration | | DELETE | /api/sessions/{session_id} | Delete server-side session + messages |

If DATABASE_URL is unset, SQLite is used automatically; history still persists.

Environment variables (backend/.env)

| Variable | Description | Required | |----------|-------------|----------| | LLM_API_KEY | API key | Yes | | LLM_BASE_URL | OpenAI-compatible base URL | Yes | | LLM_MODEL | Chat model name | Yes | | GRAPHITI_LLM_MODEL | Model for Graphiti extraction (default gpt-4o) | No | | GRAPHITI_EMBEDDING_MODEL | Embedding model name | No | | NEO4J_URI | e.g. bolt://localhost:7687 (empty disables graph writes) | No | | NEO4J_USER | Default neo4j | No | | NEO4J_PASSWORD | Password | No | | USER_ID | Graphiti group_id (default 1) | No | | DATABASE_URL | SQLAlchemy URL; empty → ./data/engram.db | No | | HOST / PORT | Bind address (default 0.0.0.0:5000) | No | | UVICORN_RELOAD | 1 / true to enable reload with python main.py | No |

Database URL examples

| Engine | DATABASE_URL | Extra dependency | |--------|----------------|------------------| | SQLite (default) | (omit) | — | | PostgreSQL | postgresql+psycopg2://user:pass@host:5432/db | uv add psycopg2-binary | | MySQL | mysql+pymysql://user:pass@host:3306/db | uv add pymysql |

Custom executors

Tool functions (agent_platform-style: code-first presets)

1. Declare @tool functions under backend/tools/ and register them via tools/__init__.py (_TOOL_MODULES).
2. In tools_lib/__init__.py, define named sets the same way as GENERAL_TOOLS / RESEARCHER_TOOLS in agent_platform:

GENERAL_TOOLS = get_tools_by_names(["get_current_time", "calculate"])
TOOL_PRESETS = {"general": GENERAL_TOOLS, "empty": EMPTY_TOOLS, ...}

3. Python executors: implement get_tools() → return GENERAL_TOOLS (see executors/example_executor.py).
4. YAML-only executors: set tool_preset: general (or empty, analyst, …) instead of listing every tool name.

Optional tools: [name, ...] in YAML still overrides presets / class get_tools() when you need an explicit exception.

Use tools_lib.list_registered_tool_names() and list_tool_presets() for debugging.

A. YAML-only (no code)

Edit backend/executors_config.yaml (optional tools as above). Restart the backend. The Planner reads role_key values from the registry.

B. Python class

1. Add e.g. backend/executors/researcher.py implementing BaseExecutor (role_name, system_prompt, get_tools()), or rely on YAML tools to inject shared tools without custom get_tools.
2. Register in YAML:

- role_key: researcher
  name: Researcher
  desc: Tasks that need search or structured gathering
  python_class: executors.researcher.ResearcherExecutor

Restart the backend.

HTTP API summary

POST /api/chat

SSE stream. Body:

{ "query": "Hello", "session_id": "uuid-here" }

Events include: user_message, todo_list, summary, tool_call, tool_result, answer_delta, answer, error, end.

GET /api/kg/page

HTML page for the memory graph (e.g. iframe). Uses USER_ID as default group_id when not overridden.

GET /api/kg/graph

JSON nodes/edges for the graph viewer.

---

Languages: English | 简体中文