How biubiutomato/tme-agent works
Project Type and Purpose
• This is an open-source research prototype called Task Memory Engine (TME).
• It implements two conceptually related but structurally distinct versions:
• v1: Tree + graph memory framework with slot-based task tracking.
• v2: Spatial memory system with DAG dependencies and memory-aware QA.
• The goal is to enable multi-step LLM-based agents to plan tasks, roll back or replace subtasks, and perform graph-based reasoning.
File Structure
• Top level
• run_case.py – driver that reads a JSON case and invokes TME.
• cases/ – JSON files defining user instruction sequences.
• .env.example – sample OpenAI API key config.
• v1/ – version 1 modules and examples.
• v2/ – version 2 modules.
• v1 directory
• executor.py – orchestrates LLM calls & memory updates.
• memory_tree.py – builds and maintains a hierarchical TaskMemoryTree.
• reasoning.py – graph-aware extensions & TRIM-like logic.
• example/ – sample form-filling scripts.
• v2 directory
• TaskMemoryStructure.py – spatial memory & DAG data structures.
• input_splitter.py – LLM-based instruction decomposer.
• intent_classifier_general.py – default intent classifier.
• intent_classifier_specific/ – specialized classifiers (e.g., cart).
• trim.py – Task Relation Inference Module.
Pull Key Insights from README
• Pipeline Stages: input parsing → decomposition → intent classification → memory update (tree or DAG) → rollback/replace support → memory-aware QA.
• External Dependency: OpenAI API (ChatGPT-4o model).
• Test Harness: run_case.py uses JSON cases, can switch between “general” vs “cart” modes.
a. Main Components
• Test Runner
• run_case.py
• cases/*.json
• Core Pipeline
1. Input Handler
2. Instruction Decomposer
• v1: reasoning.py
• v2: input_splitter.py
3. Intent Classifier
• General: intent_classifier_general.py
• Specific: intent_classifier_specific/intent_classifier_cart.py
4. Task Relation Inference (TRIM)
• v1: part of reasoning.py
• v2: trim.py
5. Memory Structure
• v1: memory_tree.py (TaskMemoryTree)
• v2: TaskMemoryStructure.py (spatial DAG)
6. Executor / Orchestrator
• v1: executor.py
• v2: orchestration code within run_case.py + module imports
7. Memory-Aware QA Module (final query stage)
• External Services
• OpenAI API
• Configuration & Utilities
• .env variables via python-dotenv
• Logging, error handling
b. Relationships & Data Flow
1. run_case.py reads a JSON case → identifies mode (general/cart) → loops through instructions.
2. Each instruction feeds into the Core Pipeline:
→ Decomposer breaks into substeps → Intent Classifier assigns relation type → TRIM refines dependencies → Memory Structure applies update/rollback → store updated memory.
3. Executor issues LLM calls (OpenAI API) at decomposer and QA stages.
4. Memory-Aware QA reads the in-memory graph/tree → forms final answer.
5. Results (updated memory state or QA output) are logged or printed.
c. Architectural Patterns & Principles
• Modular Pipeline: clear separation of concerns (decomposer, classifier, memory, QA).
• Graph & Tree Memory: v1 blends hierarchical and graph, v2 uses pure spatial/DAG.
• Externalized LLM Integration: all language reasoning via OpenAI API, isolated behind modules.
d. Key Technologies
• Python 3.x
• OpenAI Python SDK
• python-dotenv
• JSON test data