EdgeMemory — LangGraph Memory-Enhanced AI Agent

Cross-platform LangGraph agent with local LLM/LoRA, RAG, and multi-backend memory

Overview

EdgeMemory is a memory-enhanced AI agent built on LangGraph, designed to run entirely on local hardware. It integrates multiple memory backends (Kuzu graph DB + LanceDB vector store) with on-device LLM inference (llama.cpp) and LoRA fine-tuning for truly personalized AI experiences.

Why EdgeMemory?

• 🛡️ Fully Local — No cloud dependency. Your conversations, memories, and data stay on your machine.
• 🧠 Deep Memory — Combines episodic events, semantic entities, preferences, procedures, and encrypted secrets across KuzuDB (graph) and LanceDB (vector).
• 🔥 Hot-Swap LoRA — Load/unload fine-tuned LoRA adapters at runtime without restarting the agent.
• 📊 LangGraph Orchestration — Modular graph nodes for intent routing, memory read/write, RAG retrieval, planning, and answer merging.
• 🌐 Web UI + CLI — Built-in web dashboard (FastAPI + static HTML) and CLI for local interaction.
• 🔌 Extensible — Provider-agnostic LLM client; swap in any OpenAI-compatible API or local model.

Architecture

User Input
    │
    ▼
┌─────────────────────────────┐
│  LangGraph Orchestration    │
│  ┌─────────┐  ┌──────────┐ │
│  │ Router  │→│ Intent   │ │
│  └─────────┘  └──────────┘ │
│       ↓              ↓      │
│  ┌─────────┐  ┌──────────┐ │
│  │ Memory  │  │ Planner  │ │
│  │ R/W     │  │          │ │
│  └─────────┘  └──────────┘ │
│       ↓              ↓      │
│  ┌─────────────┐  ┌───────┐│
│  │ RAG Retrieve│  │Answer ││
│  └─────────────┘  └───────┘│
└─────────────────────────────┘
    │              │
    ▼              ▼
┌────────┐  ┌──────────┐
│ KuzuDB │  │ LanceDB  │
│(Graph) │  │ (Vector) │
└────────┘  └──────────┘
    │
    ▼
┌────────────┐
│ llama.cpp  │
│ + LoRA     │
└────────────┘

Memory Backends

Backend	Type	Purpose
KuzuDB	Graph Database	Entities, relationships, events, procedures, preferences
LanceDB	Vector Store	Semantic search, document RAG, embedding retrieval
SQLite	Relational	Chat history, fine-tune jobs, checkpoints

Memory Types

• Core Profile — User identity, basic facts (key-value)
• Episodic Events — Time-stamped events with participants and topics
• Semantic Entities — People, places, things with typed relationships
• Preferences — User likes/dislikes with confidence scoring
• Procedures — Multi-step process templates
• Encrypted Secrets — AES-GCM encrypted sensitive information with double-confirmation reveal flow

Quick Start

Prerequisites

• Python 3.10+
• CUDA-capable GPU (recommended) or CPU with 8GB+ RAM
• Windows, Linux, or macOS

Installation

# Clone the repository
git clone https://github.com/YOUR_USERNAME/EdgeMemory.git
cd EdgeMemory

# Create virtual environment
python -m venv .venv
# Windows
.\.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Download Models

1. Download a GGUF model (e.g., Qwen2.5-7B-Instruct-Q4_K_M.gguf) and place in models/
2. (Optional) Download embedding model for vector search

Configuration

Copy and edit the sample config:

cp edge_agent.yaml.sample edge_agent.yaml

Edit edge_agent.yaml to set model paths, ports, and memory settings.

Launch

# Full application (Web UI + Qt + API)
python edge_agent_main.py

# CLI-only mode
python core/src/main.py

# Build LanceDB index
python core/src/build_index.py

Access the web UI at http://localhost:8080.

Project Structure

EdgeMemory/
├── core/src/           # Main source code
│   ├── nodes/          # LangGraph nodes (router, intent, planner, memory, answer...)
│   ├── rag/            # LanceDB retriever
│   ├── memory/         # KuzuDB ingest, snapshot, contract
│   ├── llm/            # Local LLM client (llama.cpp wrapper)
│   ├── vector_store/   # LanceDB store + index builder
│   ├── db/             # Chat logger, SQLite persistence
│   ├── workers/        # Async tasks (embedding, ingest, finetune, summarize)
│   ├── tools/          # CLI utilities (clean, sync)
│   └── utils/          # Config, paths, watchdog, LoRA state, resource guard
├── apps/               # Qt desktop client
├── frontend/           # Web frontend assets
├── TTS/                # Text-to-speech integration
├── tools/              # Additional tooling
├── edge_agent_main.py  # Main entry point
└── edge_agent.yaml     # Configuration

Configuration Reference

Key settings in edge_agent.yaml:

# LLM server settings
llama_server:
  host: localhost
  port: 8080
  model_path: models/your-model.gguf

# Embedding server
embedding:
  host: localhost
  port: 8081
  model_path: models/embedding-model.gguf

# Memory backends
memory:
  kuzu_path: artifacts/kuzu_db
  lancedb_path: artifacts/lancedb

# LoRA
lora:
  enabled: false
  adapter_path: models/lora-adapter.gguf

Dependencies

• LangGraph — Agent orchestration framework
• llama.cpp — Local LLM inference (via llama-server)
• KuzuDB — Embedded graph database for structured memory
• LanceDB — Embedded vector database for semantic search
• FastAPI — REST API + WebSocket server
• PySide6 — Qt desktop client (optional)

Roadmap

• Docker Compose one-click deployment
• Multi-user session support
• Memory visualization dashboard
• Plugin system for custom memory types
• Remote LLM provider support (OpenAI-compatible API)

Contributing

See CONTRIBUTING.md for guidelines.

License

Apache 2.0 — See LICENSE for details.