A production-ready, graph-native long-term memory system for AI applications. Automatically extracts entities and relationships from conversations, maintains temporal context in Neo4j, and enables intelligent multi-hop reasoning for enhanced AI responses.
Traditional LLMs are stateless and forget everything after each conversation. This system provides:
- Persistent Memory: Store and recall information across sessions
- Relationship Intelligence: Understand connections between entities
- Temporal Tracking: Know when information was learned and updated
- Multi-hop Reasoning: Answer complex questions requiring multiple context pieces
- Audit Trail: Complete history of all stored conversations
- Personal AI assistants that remember user preferences and history
- Customer support systems that maintain context across interactions
- Research tools that build knowledge graphs from documents
- Team collaboration bots that track project relationships
- Any AI application requiring long-term contextual memory
CONVERSATION INGESTION PIPELINE
════════════════════════════════════════════════════════════════════════
┌──────────────────────────────────────────────────────────────────────┐
│ Input: "Alice is a software engineer at Google working with Bob" │
└──────────────────────┬───────────────────────────────────────────────┘
│
▼
┌────────────────────┐
│ memory_manager.py │
│ add_memory() │
└─────────┬──────────┘
│
├──► Generate conversation_id: conv_20241012_102030
│
▼
┌────────────────────┐
│ entity_extractor.py│
│ extract_from_text()│
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Gemini API Call │
│ (LLM Processing) │
└─────────┬──────────┘
│
▼
┌──────────────┴──────────────┐
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Extracted │ │ Extracted │
│ Entities: │ │ Relations: │
│ │ │ │
│ - Alice:person │ │ - Alice→Google │
│ - Google:org │ │ [WORKS_AT] │
│ - Bob:person │ │ - Alice→Bob │
│ │ │ [WORKS_WITH] │
└────────┬─────────┘ └────────┬─────────┘
│ │
└──────────────┬──────────────┘
│
▼
┌────────────────────┐
│ graph_db.py │
│ Neo4j Operations │
└─────────┬──────────┘
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
┌────────────────┐ ┌────────────┐ ┌──────────────┐
│ MERGE Entity │ │ MERGE │ │ CREATE │
│ Nodes │ │ Relation │ │ JSON Log │
│ │ │ Edges │ │ │
│ SET props, │ │ SET props, │ │ conversations│
│ observations, │ │ confidence,│ │ /conv_*.json │
│ timestamps │ │ timestamps │ │ │
└────────┬───────┘ └──────┬─────┘ └──────┬───────┘
│ │ │
└────────────────┼───────────────┘
│
▼
┌─────────────────┐
│ Neo4j Graph │
│ Database │
│ │
│ (Alice)─WORKS_AT→(Google) │
│ │ │
│ └─WORKS_WITH→(Bob) │
└─────────────────┘
QUERY & RETRIEVAL PIPELINE
════════════════════════════════════════════════════════════════════════
┌──────────────────────────────────────────────────────────────────────┐
│ Query: "What does Alice do?" │
└──────────────────────┬───────────────────────────────────────────────┘
│
▼
┌────────────────────┐
│ memory_manager.py │
│ chat_with_context()│
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ graph_db.py │
│ search_entities() │
└─────────┬──────────┘
│
├──► Extract terms: ["Alice"]
│
▼
┌────────────────────┐
│ Cypher Query: │
│ MATCH (e:Entity) │
│ WHERE name │
│ CONTAINS "Alice" │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Found: Alice │
│ Type: person │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ graph_db.py │
│get_entity_context()│
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ Multi-hop Query: │
│ MATCH path= │
│ (e)-[*1..2]-(c) │
└─────────┬──────────┘
│
▼
┌──────────────┴──────────────┐
│ │
▼ ▼
┌──────────────────┐ ┌──────────────────┐
│ Entity Details: │ │ Connections: │
│ │ │ │
│ Name: Alice │ │ - Google (org) │
│ Type: person │ │ via WORKS_AT │
│ Facts: │ │ - Bob (person) │
│ - software │ │ via WORKS_WITH │
│ engineer │ │ │
└────────┬─────────┘ └────────┬─────────┘
│ │
└──────────────┬──────────────┘
│
▼
┌────────────────────┐
│ Format Context: │
│ │
│ "Alice is a │
│ software engineer│
│ connected to │
│ Google and Bob" │
└─────────┬──────────┘
│
▼
┌────────────────────┐
│ llm_client.py │
│generate_response() │
└─────────┬──────────┘
│
├──► Send: Query + Context
│
▼
┌────────────────────┐
│ Gemini API Call │
│ (LLM Generation) │
└─────────┬──────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────┐
│ Response: "Alice is a software engineer at Google who works with │
│ Bob on various projects." │
└──────────────────────────────────────────────────────────────────────┘
| Component | Technology | Purpose |
|---|---|---|
| Graph Database | Neo4j Desktop | Entity and relationship storage with native graph operations |
| LLM | Google Gemini API | Entity extraction and context-aware response generation |
| Backend | Python 3.10+ | Application logic and orchestration |
| Graph Driver | neo4j-driver | Python interface to Neo4j database |
| Storage | JSON files | Conversation audit logs |
NEO4J KNOWLEDGE GRAPH REPRESENTATION
════════════════════════════════════════════════════════════════════════
┌─────────────────────┐
│ Dr. Smith │
│ Type: person │
│ ───────────── │
│ - leads AI div │
│ - oversees proj │
└──────────┬──────────┘
│
│ MANAGES
│
┌────────────────┼────────────────┐
│ │ │
│ │ │
┌─────────▼────────┐ │ ┌────────▼─────────┐
│ Alice │ │ │ Bob │
│ Type: person │ │ │ Type: person │
│ ────────────── │ │ │ ────────────── │
│ - software eng │ │ │ - senior res │
│ - specializes │◄──────┼──────┤ - collaborates │
│ in NLP │ WORKS_WITH │ with Alice │
└────┬────────┬────┘ │ └─────┬────────────┘
│ │ │ │
WORKS_AT│ │WORKS_ON │ │WORKS_ON
│ │ │ │
┌────▼────┐ │ ┌────────▼────────────▼────────┐
│ Google │ │ │ Neo4j Integration Project │
│Type:org │ │ │ Type: project │
│─────────│ │ │ ────────────────────────── │
│- tech co│ │ │ - builds scalable memory │
└─────────┘ │ │ - budget: 2M │
│ │ - status: active │
│ └───────────────────────────────┘
│
│
┌────────▼────────┐
│ Knowledge │
│ Graph System │
│ Type: project │
│ ───────────── │
│ - uses Neo4j │
│ - for AI mem │
└─────────────────┘
RELATIONSHIP TYPES:
───────────────────
WORKS_AT : Employment relationship
WORKS_WITH : Collaboration relationship
WORKS_ON : Project involvement
MANAGES : Management hierarchy
COLLABORATES_ON : Joint work on specific items
NODE PROPERTIES:
────────────────
name : Entity identifier
entity_type : Category (person, organization, project, etc.)
observations : Array of facts/attributes
created_at : Timestamp of first mention
last_updated : Timestamp of latest update
EDGE PROPERTIES:
────────────────
type : Relationship category
confidence : Score (0.0-1.0)
created_at : When relationship was established
valid_from : Temporal validity start
valid_to : Temporal validity end (null = current)
source_conv : Originating conversation ID
- Python 3.10 or higher
- Neo4j Desktop (free)
- Google Gemini API key (free tier available)
Download from https://neo4j.com/download/
- Create new Project
- Add Local DBMS
- Name:
ai-memory-graph - Password: Set secure password
- Version: Latest 5.x
- Name:
- Start database (verify green status)
cd ai-memory-graph
python -m venv venv
# Windows
venv\Scripts\activate
# Mac/Linux
source venv/bin/activate
pip install -r requirements.txt# Windows
copy .env.example .env
# Mac/Linux
cp .env.example .envEdit .env file:
GEMINI_API_KEY=your_gemini_api_key
NEO4J_PASSWORD=your_neo4j_password
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_DATABASE=neo4j
Get Gemini API key: https://ai.google.dev/
python main.pyStore information in the knowledge graph:
Select option: 1
> Alice is a software engineer at Google working on AI projects with Bob.
Processing...
Success!
Entities created: 4
Relations created: 3
Conversation ID: conv_20241012_102030
Find specific entities:
Select option: 2
> Alice
Searching...
1. Alice (person)
- software engineer
Ask questions that use stored memory:
Select option: 3
> What does Alice do?
Response:
Alice is a software engineer at Google who works on AI projects with Bob.
View system statistics:
Select option: 5
Memory Statistics:
Total Entities: 12
Total Relations: 8
ai-memory-graph/
├── config/
│ └── settings.py # Configuration and environment management
├── core/
│ ├── llm_client.py # Gemini API client wrapper
│ ├── graph_db.py # Neo4j database operations
│ ├── entity_extractor.py # Entity and relation extraction
│ └── memory_manager.py # High-level orchestration layer
├── utils/
│ └── helpers.py # Utility functions and logging
├── data/
│ └── conversations/ # JSON conversation logs
├── tests/
│ └── test_basic.py # Unit tests
├── main.py # CLI interface
├── requirements.txt # Python dependencies
├── .env.example # Environment template
└── README.md # Documentation
Orchestrates the entire flow: accepts input, coordinates extraction, manages storage, and handles retrieval.
Uses Gemini to parse natural language and extract structured entities and relationships with confidence scores.
Manages Neo4j operations: CRUD for entities/relations, search, multi-hop traversal, and temporal queries.
Wrapper for Gemini API with structured output parsing and error handling.
{
"name": "Alice",
"entity_type": "person",
"observations": ["software engineer", "works on AI"],
"created_at": "2024-10-12T10:30:00",
"last_updated": "2024-10-12T10:30:00"
}{
"type": "WORKS_WITH",
"confidence": 0.95,
"created_at": "2024-10-12T10:30:00",
"valid_from": "2024-10-12T10:30:00",
"valid_to": null,
"source_conversation": "conv_20241012_102030"
}Run unit tests:
pytest tests/Run with coverage:
pytest --cov=core tests/- Verify database is running (green status in Neo4j Desktop)
- Check password in
.envmatches database password - Ensure port 7687 is available
- Try restarting Neo4j Desktop
- Verify API key is valid at https://ai.google.dev/
- Check for extra spaces in
.envfile - Ensure API key has no usage limits exceeded
- Verify internet connection
- Activate virtual environment
- Reinstall dependencies:
pip install -r requirements.txt - Check Python version:
python --version(must be 3.10+)
- Entity searches use indexed lookups (O(log n))
- Relationship traversal limited to 2 hops by default
- Search results limited to 10 entities
- Conversation logs stored as separate JSON files
- Store
.envfile securely (never commit to version control) - Use strong Neo4j passwords
- Rotate Gemini API keys periodically
- Sanitize user input before storage
- Review conversation logs for sensitive data
Potential improvements for production deployment:
- Vector embeddings for semantic search
- Entity resolution and deduplication
- Importance scoring and memory pruning
- Multi-user support with authentication
- REST API for programmatic access
- Cloud deployment (GCP, AWS, Azure)
- Batch processing for document ingestion
- Export/import functionality
For production deployment on GCP:
- Replace Neo4j Desktop with Neo4j Aura (managed)
- Deploy application on Cloud Run
- Store logs in Cloud Storage
- Use Secret Manager for credentials
- Configure Cloud Logging and Monitoring
MIT License
Contributions are welcome. Please:
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request with clear description
For issues and questions:
- Check this README and troubleshooting section
- Review application logs
- Verify all prerequisites are met
- Check Neo4j and Gemini API status