Skip to content

fenil210/MemoraAI

BranchesTags

Repository files navigation

AI Knowledge Graph Memory System

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.

Why This Exists

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

Use Cases

  • 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

System Flow

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."                                           │
└──────────────────────────────────────────────────────────────────────┘

Technology Stack

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

Graph Structure

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

Prerequisites

  • Python 3.10 or higher
  • Neo4j Desktop (free)
  • Google Gemini API key (free tier available)

Installation

1. Install Neo4j Desktop

Download from https://neo4j.com/download/

  1. Create new Project
  2. Add Local DBMS
    • Name: ai-memory-graph
    • Password: Set secure password
    • Version: Latest 5.x
  3. Start database (verify green status)

2. Setup Python Environment

cd ai-memory-graph
python -m venv venv

# Windows
venv\Scripts\activate

# Mac/Linux
source venv/bin/activate

pip install -r requirements.txt

3. Configure Environment

# Windows
copy .env.example .env

# Mac/Linux
cp .env.example .env

Edit .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/

4. Run Application

python main.py

Usage

Adding Memory

Store 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

Searching Memory

Find specific entities:

Select option: 2
> Alice

Searching...
1. Alice (person)
   - software engineer

Querying with Context

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.

Statistics

View system statistics:

Select option: 5

Memory Statistics:
Total Entities: 12
Total Relations: 8

Project Structure

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

Key Components

Memory Manager

Orchestrates the entire flow: accepts input, coordinates extraction, manages storage, and handles retrieval.

Entity Extractor

Uses Gemini to parse natural language and extract structured entities and relationships with confidence scores.

Graph Database

Manages Neo4j operations: CRUD for entities/relations, search, multi-hop traversal, and temporal queries.

LLM Client

Wrapper for Gemini API with structured output parsing and error handling.

Data Model

Entity Node

{
    "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"
}

Relationship Edge

{
    "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"
}

Testing

Run unit tests:

pytest tests/

Run with coverage:

pytest --cov=core tests/

Troubleshooting

Neo4j Connection Failed

  • Verify database is running (green status in Neo4j Desktop)
  • Check password in .env matches database password
  • Ensure port 7687 is available
  • Try restarting Neo4j Desktop

Gemini API Error

  • Verify API key is valid at https://ai.google.dev/
  • Check for extra spaces in .env file
  • Ensure API key has no usage limits exceeded
  • Verify internet connection

Import Errors

  • Activate virtual environment
  • Reinstall dependencies: pip install -r requirements.txt
  • Check Python version: python --version (must be 3.10+)

Performance Considerations

  • 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

Security Notes

  • Store .env file 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

Future Enhancements

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

Cloud Deployment

For production deployment on GCP:

  1. Replace Neo4j Desktop with Neo4j Aura (managed)
  2. Deploy application on Cloud Run
  3. Store logs in Cloud Storage
  4. Use Secret Manager for credentials
  5. Configure Cloud Logging and Monitoring

License

MIT License

Contributing

Contributions are welcome. Please:

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request with clear description

Support

For issues and questions:

  • Check this README and troubleshooting section
  • Review application logs
  • Verify all prerequisites are met
  • Check Neo4j and Gemini API status

About

A graph-native long-term memory substrate for AI systems. Connects conversations, documents, and context into a unified knowledge graph for persistent reasoning and retrieval.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages