LiteAgent-Memory

LiteAgent-Memory is a prototype for the China Graduate OS Open Source Innovation Competition topic: low-overhead communication, state transfer, and shared memory for multi-agent collaboration.

The project compares three collaboration modes:

• text_mode: verbose natural-language message passing.
• protocol_mode: structured JSON AgentMessage passing.
• optimized: protocol mode plus state_ref, deterministic hash embedding, and SQLite shared memory.

Features

• Four-agent workflow: Planner, Retriever, Executor, Summarizer.
• JSON structured protocol and MessagePack codec comparison.
• Non-text state transfer through state_ref.
• SQLite shared memory with keyword, tag, and hash-embedding retrieval.
• Metrics: message count, char cost, token cost, state transfers, memory hits, latency, JSON bytes, MessagePack bytes.
• Shared-memory transport experiment using Python standard library.
• Dependency-free HTML dashboard generated into outputs/dashboard.html.
• openEuler-friendly baseline: Python 3.10+, SQLite, minimal dependencies.

Quick Start

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python run_demo.py
python run_experiment.py
pytest tests/ -v

Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python run_demo.py
python run_experiment.py
pytest tests/ -v

Demo

python run_demo.py

The demo shows registered agents, a protocol-mode run, generated state_ref, memory_id, and a second related task that hits shared memory.

Experiment

python run_experiment.py

Optional:

python run_experiment.py --tasks examples/continuous_tasks.json --repeat 3 --output outputs

Generated outputs:

• outputs/experiment_results.json
• outputs/experiment_results.csv
• outputs/metrics_summary.json
• outputs/metrics_summary.csv
• outputs/experiment_report.md
• outputs/dashboard.html
• outputs/metrics_chart.svg

Project Layout

agents/       Agent implementations
runtime/      Runtime, Router, Scheduler, CapabilityRegistry
protocol/     AgentMessage, JSON codec, MessagePack codec
state/        hash embedding, StateStore, state_ref
memory/       SQLite MemoryStore, MemoryRetriever
transport/    runtime transport, shared-memory byte channel
evaluation/   MetricsCollector, ExperimentRunner, dashboard generation
examples/     continuous task dataset
tests/        unit tests
docs/         design, deployment, report, demo script, defense notes

openEuler

Target platform: openEuler 24.03-LTS-SP3 x86_64. See docs/deployment.md for deployment steps.

Optional Integrations

DeepSeek API, local bge-m3 paths, MessagePack, shared-memory transport, and CodeAct sandbox hooks are documented in docs/optional_integrations.md. API keys must be supplied through environment variables and must not be committed.