nyron-ai 0.1.3

Graph-based AI memory system with Neo4j, recall scoring, and conflict analysis

Neur0 (nyron-ai)

Neur0 is a graph-based AI memory system designed for long-term personalization. It uses Neo4j to build isolated user subgraphs, resolves memory conflicts using semantic analysis, ranks retrieved memories using recall scoring, and keeps short-term context utilizing MongoDB.

---

Features

• Graph-Based Memory: Build highly structured, isolated memory subgraphs for individual users.
• Semantic Conflict Resolution: Automatically detect when new facts contradict existing memories and mark old facts as conflicted. -Recall Scoring: Rank memories dynamically based on a combination of semantic similarity, recency, and reinforcement (access frequency). -Short-Term Context: Manage short-term context and resolve pronouns/references using MongoDB. -OpenAI Integration: Cleanly extract facts and embeddings using OpenAI models. -Built-in API Server: Instantly run a FastAPI server using the CLI to add, search, and manage memories via HTTP requests.

---

Prerequisites

• Python: >=3.9
• Neo4j Database: A running instance (e.g. Neo4j Desktop, AuraDB, or Docker).
• MongoDB (Optional): Required if you want to enable the short-term memory store.
• OpenAI API Key: Required for fact extraction, query resolution, and embeddings.

---

Installation

You can install Neur0 from PyPI:

pip install nyron-ai

For local development and testing, clone the repository and run:

pip install -e .

---

Quickstart

1. Configure Environment Variables

Create a .env file in your project root with your database credentials and API keys:

OPENAI_API_KEY=your-openai-key
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password

# Optional: MongoDB for short-term memory
MONGO_URI=mongodb://localhost:27017
MONGO_DB=neur0

2. Python Code Usage

Here is how to initialize the memory client, save a memory, and query it:

import asyncio
from neuro import (
    MemoryClient,
    Neo4jGraphStore,
    MongoStore,
    OpenAIProvider,
    OpenAIEmbeddingProvider,
)

async def main():
    # 1. Initialize Stores
    graph_store = Neo4jGraphStore(
        uri="bolt://localhost:7687",
        username="neo4j",
        password="password",
    )
    graph_store.initialize()

    # Optional MongoDB short-term store
    mongo_store = MongoStore(uri="mongodb://localhost:27017", db_name="neur0")
    await mongo_store.initialize()

    # 2. Setup AI Providers
    llm = OpenAIProvider(api_key="your-api-key", model="gpt-4o-mini")
    embedder = OpenAIEmbeddingProvider(api_key="your-api-key", model="text-embedding-3-small")

    # 3. Create Memory Client
    memory = MemoryClient(
        graph_store=graph_store,
        llm=llm,
        embedder=embedder,
        short_term_store=mongo_store,
    )

    # 4. Save a Memory
    user_id = "user_128r"
    result = await memory.add(
        user_id=user_id,
        message="I studied computer science at Cambridge University.",
    )
    print("Saved facts:", result["saved_count"])

    # 5. Search memories
    search_results = await memory.search(
        user_id=user_id,
        query="Where did I go to college?",
    )
    for res in search_results:
        fact = res["fact"]
        print(f"Fact: {fact.subject} {fact.predicate} {fact.object}")
        print(f"Recall Score: {res['recall_score']}")

    # Clean up connections
    graph_store.close()
    mongo_store.close()

if __name__ == "__main__":
    asyncio.run(main())

---

Running the API Server

Neur0 includes a built-in command line utility to start a FastAPI backend.

Simply run:

neuro-api

The API will start running at http://localhost:8000.

Available Endpoints

• POST /add_memory: Add a new user message, extract facts, and handle conflicts.

  {
    "user_id": "user_128r",
    "message": "I study computer science at Cambridge."
  }
  

• POST /search_memory: Search and retrieve relevant memories.

  {
    "user_id": "user_128r",
    "query": "Where do I study?",
    "limit": 5
  }
  

• DELETE /delete_subgraph/{user_id}: Delete all graph nodes and memories for a specific user.

---

License

MIT License.