https://github.com/foo290/neurotrace
A private repository for neurotrace project
https://github.com/foo290/neurotrace
ai artificial-intelligence chatbot generative-ai graph-da graph-retrieval graphdatabase knowledge-graph langchain llm llm-inference llm-memory ml neo4 rag rag-pipeline retriv
Last synced: 6 months ago
JSON representation
A private repository for neurotrace project
- Host: GitHub
- URL: https://github.com/foo290/neurotrace
- Owner: foo290
- Created: 2025-05-28T12:50:41.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-07-15T15:11:35.000Z (7 months ago)
- Last Synced: 2025-07-15T15:25:24.824Z (7 months ago)
- Topics: ai, artificial-intelligence, chatbot, generative-ai, graph-da, graph-retrieval, graphdatabase, knowledge-graph, langchain, llm, llm-inference, llm-memory, ml, neo4, rag, rag-pipeline, retriv
- Language: Python
- Homepage: https://foo290.github.io/neurotrace/
- Size: 1.37 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Neurotrace
[](https://pypi.org/project/neurotrace/)
A hybrid memory library designed for LangChain agents, providing dual-layer memory architecture with short-term buffer memory and long-term hybrid RAG system capabilities.
## Overview
Neurotrace provides persistent, intelligent memory for conversational agents that improves over time and enables contextual understanding and recall. It combines vector-based and graph-based RAG (Retrieval Augmented Generation) systems to provide deeper and more accurate contextual reasoning.
## 🎯 Key Features
- **Dual-Layer Memory Architecture**
- Short-term buffer memory for immediate context
- Long-term hybrid RAG system for persistent storage
- **Real-time Processing**
- Real-time recall during conversations
- Intelligent storage and compression
- **Rich Message Structure**
- Custom metadata-rich message formats
- Support for filtering and semantic tracing
- **Hybrid Retrieval System**
- Combined vector and graph-based RAG
- Enhanced contextual reasoning capabilities
## Graph db integration (Graph RAG)
## 🎯 Target Users
- Developers building AI agents with LangChain
- Researchers exploring memory augmentation in LLMs
- Enterprises deploying context-aware AI assistants
## Quick Start
### Installation
```bash
pip install neurotrace
```
### Complete Example
A complete, runnable example is available in `examples/agent_example.py`. This example demonstrates:
- Setting up a Neurotrace agent with both short-term and long-term memory
- Configuring vector and graph storage
- Implementing an interactive conversation loop
- Monitoring memory usage
To run the example:
```bash
# First set up your environment variables
export NEO4J_URL=bolt://localhost:7687
export NEO4J_USERNAME=neo4j
export NEO4J_PASSWORD=your_password
export GOOGLE_API_KEY=your_google_api_key
# Then run the example
python examples/agent_example.py
```
### Required Environment Variables
```bash
NEO4J_URL=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
GOOGLE_API_KEY=your_google_api_key # For Gemini LLM
```
## Technical Documentation
### Core Schema
The `neurotrace.core.schema` module defines the fundamental data structures used throughout the project.
### Message
The core Message class represents a single message in the system:
```python
from neurotrace.core.schema import Message, MessageMetadata, EmotionTag
message = Message(
role="user", # Can be "user", "ai", or "system"
content="Hello!", # The message text content
metadata=MessageMetadata(
source="chat",
emotions=EmotionTag(sentiment="positive")
)
)
```
Key features of Message:
- Auto-generated UUID for each message
- Automatic timestamp on creation
- Type-safe role validation
- Rich metadata support via MessageMetadata
### Message Components
#### EmotionTag
Represents the emotional context of a message:
```python
from neurotrace.core.schema import EmotionTag
emotion = EmotionTag(
sentiment="positive", # Can be "positive", "neutral", or "negative"
intensity=0.8 # Optional float value indicating intensity
)
```
#### MessageMetadata
Contains additional information and context about a message:
```python
from neurotrace.core.schema import MessageMetadata, EmotionTag
metadata = MessageMetadata(
token_count=150, # Number of tokens in the message
embedding=[0.1, 0.2, 0.3], # Vector embedding for similarity search
source="chat", # Source: "chat", "web", "api", or "system"
tags=["important", "follow-up"], # Custom tags
thread_id="thread_123", # Conversation thread identifier
user_id="user_456", # Associated user identifier
related_ids=["msg_789"], # Related message IDs
emotions=EmotionTag(sentiment="positive"), # Emotional context
compressed=False # Compression status
)
```
Each field in MessageMetadata is optional and provides specific context:
- `token_count`: Used for tracking token usage
- `embedding`: Vector representation for similarity search
- `source`: Indicates message origin
- `tags`: Custom categorization
- `thread_id`: Groups messages in conversations
- `user_id`: Links messages to users
- `related_ids`: Connects related messages
- `emotions`: Captures emotional context
- `compressed`: Indicates if content is compressed
### Usage
```python
"""
A complete example of implementing a Neurotrace-powered agent with both short-term and long-term memory.
"""
import os
from dotenv import load_dotenv
from langchain.agents import AgentType, initialize_agent
from langchain.vectorstores import Chroma
from langchain_community.graphs import Neo4jGraph
from langchain_google_genai import ChatGoogleGenerativeAI, GoogleGenerativeAIEmbeddings
from neurotrace.core.hippocampus.memory_orchestrator import MemoryOrchestrator
from neurotrace.core.memory import NeurotraceMemory
from neurotrace.core.schema import Message
from neurotrace.core.tools.memory import memory_search_tool, save_memory_tool
from neurotrace.core.tools.system import get_system_tools_list
def setup_agent():
"""Initialize and configure the Neurotrace agent with memory components."""
# Load environment variables
load_dotenv()
# Initialize LLM
llm = ChatGoogleGenerativeAI(model="gemini-2.5-flash", temperature=0.3)
# Setup short-term memory
memory = NeurotraceMemory(max_tokens=100, llm=llm)
# Setup vector store
embedding_model = GoogleGenerativeAIEmbeddings(model="models/embedding-001")
vectorstore = Chroma(embedding_function=embedding_model, persist_directory=".chromadb")
# Setup graph database
graph_store = Neo4jGraph(
url=os.environ.get("NEO4J_URL", "bolt://localhost:7687"),
username=os.environ.get("NEO4J_USERNAME", "neo4j"),
password=os.environ.get("NEO4J_PASSWORD", "password"),
)
# Initialize Memory Orchestrator
mem_orchestrator = MemoryOrchestrator(
llm=llm,
vector_store=vectorstore,
graph_store=graph_store,
)
# Setup memory tools
mem_save_tool = save_memory_tool(memory_orchestrator=mem_orchestrator)
mem_search_tool = memory_search_tool(memory_orchestrator=mem_orchestrator)
# Initialize Agent
agent = initialize_agent(
tools=[mem_search_tool, mem_save_tool, *get_system_tools_list()],
llm=llm,
agent=AgentType.CHAT_CONVERSATIONAL_REACT_DESCRIPTION,
memory=memory,
verbose=True,
)
return agent, memory
def run_agent():
"""Run the agent in an interactive conversation loop."""
agent, memory = setup_agent()
print("Neurotrace Agent Ready. Type 'exit' to quit.")
while True:
user_input = input("\nYou: ")
if user_input.strip().lower() == "exit":
break
# Process user input
response = agent.invoke({"input": user_input})
output = response["output"]
print("Agent:", output)
# Save conversation to memory
user_msg = Message(role="human", content=user_input)
ai_msg = Message(role="ai", content=output)
# Debug Memory State
print("\n-- Memory State --")
print("STM Messages:", len(memory._stm.get_messages()))
print("STM Tokens:", memory._stm.total_tokens())
print("------------------\n")
if __name__ == "__main__":
run_agent()
```