Study Copilot: Building an AI Agent That Reasons Over Prerequisites With FalkorDB

What you’ll build

Study Copilot is a graph-grounded learning assistant built with Python, FastAPI, FalkorDB, and Cypher.

It helps a learner answer a practical question: “What should I study next?”

Instead of returning a generic list of resources, it checks the learner’s progress, prerequisites, skill gaps, available time, connected resources, and quizzes. It then recommends an actionable next step and explains why that step is ready.

The project also supports confirmation-gated actions, such as creating a study plan, updating progress, marking a resource complete, and recording a quiz attempt.

Why I built it

Students are surrounded by courses, articles, quizzes, and notes, but the difficult question is often simple: what should I do next?

A flat resource list cannot reliably account for prerequisites, weak areas, progress, and available time. I built Study Copilot to turn those connections into an explainable next action.

Why a graph changes the answer

Imagine a learner asks:

“What should I study next in 30 minutes?”

A traditional recommendation system might suggest Recursion because it looks relevant and fits the available time.

Study Copilot checks the learning graph first:

• Recursion has a prerequisite: Data Structures
• The learner’s Data Structures mastery is below 0.7
• Therefore, Recursion is blocked
• Data Structures is recommended instead

The recommendation is not based only on similarity. It is based on the learner’s actual prerequisite path.

The problem

A recommendation is only useful when it is relevant and actionable. Study Copilot retrieves a learner’s graph context before deciding.

It can:

• Recommend the next topic
• Create a study plan
• Update progress
• Record a quiz attempt
• Mark a resource complete
• Retrieve a connected quiz for practice

State-changing actions require explicit confirmation.

FalkorDB as the learning graph

The graph contains User, Topic, Progress, SkillGap, Resource, Quiz, StudyPlan, and StudyPlanItem nodes.

Key relationships include:

• HAS_PROGRESS
• FOR_TOPIC
• PREREQUISITE_OF
• HAS_RESOURCE
• HAS_QUIZ
• CONTAINS

FalkorDB is useful here because the important question is not only “which topic is similar?” but also “which topics can this learner safely study now?”

A graph can directly traverse prerequisite chains, progress records, skill gaps, resources, and quizzes. That makes the recommendation easier to explain and easier to audit.

MATCH (u:User {id:$user_id})-[:HAS_PROGRESS]->(p:Progress)-[:FOR_TOPIC]->(t:Topic)
MATCH (candidate:Topic)
WHERE candidate.estimated_minutes <= $minutes
  AND NOT EXISTS {
    MATCH (pre:Topic)-[:PREREQUISITE_OF]->(candidate)
    WHERE NOT EXISTS {
      MATCH (u)-[:HAS_PROGRESS]->(mp:Progress)-[:FOR_TOPIC]->(pre)
      WHERE mp.mastery >= 0.7
    }
  }
RETURN candidate
ORDER BY candidate.difficulty

This query finds topics the learner is ready to study by checking that every prerequisite has at least 0.7 mastery. It then ranks eligible topics by difficulty, making the recommendation explainable and grounded in the learner’s graph context.

Agent architecture

The browser calls FastAPI. The agent asks StudyRepository for user context and next topics, then creates a structured decision.

ActionService stages mutations and executes them only after approval. The repository sends parameterized Cypher to FalkorDB.

This keeps retrieval, decision logic, safety, and persistence separated without requiring an external LLM key for the demo.

For actions that change learning records, the agent asks for confirmation. Approval executes the update; rejection leaves the graph unchanged.

Graph-grounded explainability

The latest version does not return only a topic name.

For every recommendation, the agent can return:

• The recommended topic
• Why it is ready now
• The learner’s mastery level
• Available study time
• The prerequisite relationship path
• Connected resources and quizzes
• Blocked topics and the reason they are blocked

For example, the UI can show:

Recommended: Data Structures

Why:
- Python Functions mastery: 0.82
- Python Functions is a prerequisite for Data Structures
- Data Structures fits the available study time
- Data Structures has a connected skill gap

Blocked:
- Recursion
- Reason: Data Structures mastery is below 0.7

This turns a recommendation into evidence a learner can inspect.

Feature walkthrough

1. Ask, What should I study next? to see a graph-grounded recommendation.
2. Ask, Create a study plan, then approve the pending action.
3. Ask, Update my progress, Mark this resource complete, or Record a quiz attempt, and approve the mutation.
4. Ask, Generate practice questions, to retrieve the connected quiz for the recommended topic.

The UI exposes the retrieved context and action result so the user can see why the agent chose its recommendation.

Running it locally

The fastest way to run the complete demo is with Docker.

cp .env.example .env
docker compose up --build

This starts FalkorDB, seeds the sample learning graph, and serves the UI at:

http://localhost:8000

The API documentation is available at:

http://localhost:8000/docs

The demo uses a deterministic agent by default, so it runs without an external LLM API key.

What I learned

Connected data changes the agent’s role from answer generation to evidence-based decision making.

FalkorDB makes prerequisite traversal and relationship inspection natural, while confirmation gates provide a practical safety boundary for actions that change learner records.

Limitations and next steps

The demo uses deterministic intent routing and an in-memory pending-action store.

Future work would add authenticated users, persistent audit events, richer question content, and an optional production LLM provider.

Repository

Study Copilot on GitHub

Demo

Watch the demo:

Study Copilot demo video