Agentic AI · GraphRAG
Second Brain
Project purpose
An AI knowledge assistant that combines semantic retrieval and knowledge-graph relationships to answer questions using information extracted from personal notes.
- LangGraph
- ChromaDB
- Neo4j
- FastAPI
- LangSmith
Retrieval
2 paths · ChromaDB semantics and Neo4j relationships
Persistence
3 stores · PostgreSQL, ChromaDB, Neo4j
Evaluation scope
31 cases · LangSmith LLM judge
The engineering problem
A project decision might live in one note and its rationale in another. Keyword search can miss the rationale if the two notes use different terms. Vector similarity can recover related wording, but tells you little about whether one entity depends on another. Second Brain indexes both the text and its relationships so an answer can draw on several connected notes.
System architecture
Conceptual flow
Knowledge ingestion
React sends the note to FastAPI. One LLM analysis extracts the title, topic, atomic note, entities, and relationships. The backend commits PostgreSQL, then indexes ChromaDB and Neo4j with the same note ID. Gold arrows show the order of backend writes, not store-to-store requests; these writes are not one atomic transaction.
- Note processing
- Writes and note ID
Conceptual execution sequence
- React sends the note to FastAPI at /add-note.
- The LLM produces an atomic note and extracts the title, topic, entities, and relationships.
- PostgreSQL commits the original note and its structured fields. The backend reads the new note ID.
- The backend embeds the atomic note and indexes it in ChromaDB under the note ID.
- The backend writes the note, entities, and relationships to Neo4j using that same ID.
Conceptual flow
GraphRAG question answering
This walkthrough follows the retrieval route. LangGraph fans out to ChromaDB for semantic passages and Neo4j for relationships. The graph calls Python search functions directly. Both results feed the answer prompt, and FastAPI returns the response to React.
- Request
- Semantic search
- Graph traversal
- Response
Conceptual execution sequence
- The question travels from React to the FastAPI chat endpoint.
- LangGraph plans search queries and selects the retrieval route.
- The search functions query ChromaDB for similar passages and Neo4j for connected entities.
- The agent combines the two sets of retrieval results into context for the answer.
- The model generates an answer using that retrieved context.
- FastAPI returns the answer to React.
VersionE implementation
Follow the note ID
The backend commits a PostgreSQL row, then attempts ChromaDB and Neo4j indexing with the same note ID. These source-grounded examples show the API contract and indexing pattern. A later indexing failure can leave the committed row in place.
Ingest a note
POST /add-note
{ "content": "<note text>" }
Result fields
id, title, content, topic,
atomic_note, entities, relationsThe API commits the original text and generated title and topic in PostgreSQL. ChromaDB indexes the shorter atomic note under the resulting ID.
Connect its entities
MERGE (n:Note {id: $id})
MERGE (ent:Entity {name: $name})
MERGE (n)-[:MENTIONS]->(ent)These are the graph’s key operations. Note IDs and entity names let Neo4j reuse nodes. Distinct spellings can still create separate entities, and typed links such as DEPENDS_ON connect them.
How the graph connects notes
This schema example uses synthetic labels to show two notes mentioning a shared entity and a typed relationship between entities.
Agentic retrieval
Two ways to find context
Semantic search
ChromaDB compares the query embedding with note embeddings. Different wording can lead to a passage with a similar meaning.
Graph retrieval
Neo4j starts with title or text matches, follows MENTIONS edges, and collects entity names and outgoing relationship types.
In VersionE, LangGraph calls the Python vector and graph search functions directly. A separate awab branch contains MCP server prototypes and a client notebook; they are outside this runtime path.
Engineering decisions
LangGraph orchestration
The planner breaks a question into search queries. A routing node chooses between retrieval and direct generation, so questions that need stored knowledge can take the search path.
Hybrid GraphRAG
On the retrieval route, each planned query searches ChromaDB and Neo4j. Their results enter the same document state before answer generation. Direct generation is also a possible route.
Retrieval tool interfaces
VersionE calls Python vector and graph search functions directly. The separate awab branch contains FastMCP vector and graph servers and a client notebook; they are not on the VersionE graph path.
Multi-store indexing
The backend commits the PostgreSQL record first, then writes the vector and graph representations using its note ID. That shared ID ties the records together. A secondary write can still fail after the original note is saved.
Evaluation
A 31-case LangSmith dataset pairs questions with reference answers. The runner sends each question, generated answer, and reference to an LLM judge; its feedback is a review signal, not a verified accuracy result.
Evaluation
Reviewing answers with LangSmith
The VersionE dataset seed defines 31 question–answer cases drawn from the notes: factual lookups, questions that combine notes, reasoning tasks, and questions the notes cannot answer.
- The dataset supplies a question and reference answer.
- The LangGraph application generates an answer.
- The judge receives the question, generated answer, and reference.
- The judge returns scores and a reason; LangSmith records the feedback.
- Correctness
- Does the answer agree with the reference on the facts?
- Relevance
- Does it address what the question asks?
- Hallucination assessment
- Does it introduce claims unsupported by the reference?
- Conciseness
- Does it convey the necessary information without repetition?
The judge prompt does not receive retrieved passages or the dataset’s source-note IDs. Its reference-based scores need human interpretation; the repository contains the evaluation method, not a published aggregate result.
Technology stack
- Frontend
- React
- Backend
- Python, FastAPI
- Orchestration
- LangGraph
- Semantic index
- ChromaDB
- Knowledge graph
- Neo4j
- Note storage
- PostgreSQL
- Runtime retrieval
- Direct Python search functions
- MCP prototypes
- Vector and graph servers on the separate awab branch
- Evaluation & tracing
- LangSmith
Implementation references
- Note ingestion and chat routes
backend/routes/notes_routes.py - LangGraph planner and retrieval
Langgraph_agent/langgraph_agent.py - Neo4j indexing and traversal
ai/neo4j.py - 31-case evaluation dataset
seed/seed_langsmith.py - LangSmith evaluation runner
Langgraph_agent/run_eval.py - Vector MCP server prototype
awab branch · mcp/vector_mcp/server.py - Graph MCP server prototype
awab branch · MCP/neo4j-mcp/server.py - MCP client notebook
awab branch · ai/agent.ipynb