Skip to content

README.md

Latest commit

 

History

History
301 lines (217 loc) · 8.88 KB

README.md

File metadata and controls

301 lines (217 loc) · 8.88 KB

Canvas Learning System

AI-Powered Learning Platform for Obsidian Canvas
Transform passive learning into active understanding using the Feynman Technique

Obsidian Plugin Python 3.9+ TypeScript MIT License

Contributors

Overview

Canvas Learning System transforms passive learning into an active learning process. With 12-14 specialized AI Agents collaborating, it guides you from confusion to mastery through the Feynman Learning Method.

Problems We Solve

  • Passive Consumption - Reading/watching without active engagement
  • Illusion of Competence - Familiarity mistaken for true understanding
  • Lack of Personalization - One-size-fits-all learning approaches
  • No Systematic Verification - No objective way to measure understanding

Our Solution

  • Visual Learning - Color-coded knowledge nodes on Obsidian Canvas
  • Forced Output - Dedicated explanation spaces (yellow nodes)
  • Personalized Guidance - 14 specialized AI Agents
  • Systematic Verification - 4-dimension scoring system
  • Knowledge Graph - Visual map that grows with your understanding

Features

Color-Coded Learning System

Color Code Meaning
Red 1 Unknown concept - needs learning
Yellow 6 User explanation space - your understanding
Purple 3 Partial understanding - needs deepening
Green 2 Fully mastered
Blue 5 AI-generated content

14 Specialized AI Agents

Decomposition Agents

  • basic-decomposition - Break complex topics into 3-7 guiding questions
  • deep-decomposition - Create deep verification questions
  • question-decomposition - Generate breakthrough questions

Explanation Agents

  • oral-explanation - Professor-style 800-1200 word oral explanations
  • clarification-path - 1500+ word systematic explanations
  • comparison-table - Structured comparison tables for similar concepts
  • memory-anchor - Vivid analogies and memory anchors
  • four-level-explanation - Progressive 4-level explanations
  • example-teaching - Complete problem tutorials with solutions

Assessment Agents

  • scoring-agent - 4-dimension understanding assessment
  • verification-question - Deep understanding verification questions

Review System (FSRS)

  • Intelligent review based on Ebbinghaus forgetting curve
  • Auto-generated review Canvas
  • Progress tracking dashboard

Installation

Prerequisites

  • Obsidian v1.0+
  • Python 3.9+ (for backend)
  • Node.js 18+ (for development)

Obsidian Plugin Installation

Method 1: From Release (Recommended)

  1. Download the latest Release
  2. Extract main.js and manifest.json
  3. Create folder .obsidian/plugins/canvas-review-system/ in your Vault
  4. Copy the files to that folder
  5. Enable the plugin in Obsidian Settings > Community Plugins

Method 2: Manual Build

cd canvas-progress-tracker/obsidian-plugin
npm install
npm run build
# Copy main.js and manifest.json to your Vault's plugins folder

Backend Service Installation

# Clone repository
git clone https://github.com/oinani0721/canvas-learning-system.git
cd canvas-learning-system/backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Start service
uvicorn app.main:app --host 0.0.0.0 --port 8000

Docker Deployment (Neo4j + Memory System)

Prerequisites

  • Docker Desktop installed and running
  • Ports available: 7478 (Neo4j HTTP), 7691 (Neo4j Bolt), 8001 (Backend API)
  • Memory: ≥1GB available for Neo4j container
  • Mac 用户需原生安装 Ollama: brew install ollama && brew services start ollama

Step 1: Configure Environment

# 从项目根目录开始
cp .env.example .env

Edit .env with the following critical settings:

# ⚠️ 必填项
NEO4J_PASSWORD=your_secure_password_here
CANVAS_BASE_PATH=/path/to/your/obsidian/vault

Note: Root .env is the single source of truth. docker-compose.yml reads variables from it automatically. You do NOT need to edit docker-compose.yml or backend/.env separately.

Step 2: Start Services

docker-compose up -d

Step 3: Verify Deployment

# Validate environment variables
scripts/validate-env.sh

# Neo4j Browser
curl http://localhost:7478

# Backend health check
curl http://localhost:8001/api/v1/health

Troubleshooting

Problem Cause Solution
Connection timeout Wrong port in NEO4J_URI Set NEO4J_URI=bolt://localhost:7691 in backend/.env
Auth failure Password mismatch Only set NEO4J_PASSWORD in root .env
Vault files not found CANVAS_BASE_PATH not set Set it in root .env to your vault parent directory
Backend can't write vault Vault mounted read-only Set VAULT_MOUNT_MODE=rw in root .env (default)
Ollama not reachable (Mac) Docker can't reach host Ollama Ensure OLLAMA_HOST=http://host.docker.internal:11434

Quick Start

  1. Create a new Canvas - Create a .canvas file in Obsidian
  2. Add red nodes - Write concepts you don't understand
  3. Right-click to invoke Agent - Select appropriate Agent for decomposition/explanation
  4. Explain in yellow nodes - Use your own words to explain the concept
  5. Use scoring Agent - Get 4-dimension understanding assessment
  6. Watch colors change - Red > Purple > Green

Project Structure

canvas-learning-system/
├── canvas-progress-tracker/
│   └── obsidian-plugin/          # Obsidian Plugin (TypeScript)
│       ├── src/                  # Source code
│       ├── main.js               # Build output
│       └── manifest.json         # Plugin manifest
├── backend/
│   ├── app/
│   │   ├── api/v1/endpoints/     # REST API endpoints
│   │   ├── services/             # Business logic
│   │   └── models/               # Data models
│   └── requirements.txt
├── src/agentic_rag/              # LangGraph RAG system
├── docs/                         # Documentation
│   ├── prd/                      # Product requirements
│   └── architecture/             # Architecture design
└── specs/                        # OpenAPI specifications

Tech Stack

Component Technology
Frontend TypeScript, Obsidian Plugin API
Backend Python 3.9+, FastAPI
AI Claude API (Anthropic)
Memory System Graphiti + Neo4j
Vector Store LanceDB
Deployment Docker, Docker Compose

Recent Updates

Memory System Health Checks

  • /api/v1/health/neo4j - Neo4j connection status with async driver support
  • /api/v1/health/storage - Unified storage health (LanceDB + Neo4j)
  • Automatic retry with configurable timeouts for slow first connections

Canvas Metadata Management (Story 38.1)

  • Backend metadata API for canvas subject mapping
  • Configurable subject resolver with YAML-based mapping
  • Canvas info view in Obsidian plugin settings

Bug Fixes

  • LanceDB data isolation: Fixed path calculation that caused index/query to use different databases
  • Backend process cleanup: Fixed orphaned uvicorn processes on Obsidian exit (execSync + taskkill)
  • Graphiti client: Unified connection architecture with proper error handling

API Documentation

After starting the backend service:

Development

# Plugin development
cd canvas-progress-tracker/obsidian-plugin
npm run dev

# Backend development
cd backend
uvicorn app.main:app --reload

# Run tests
cd backend && pytest
cd canvas-progress-tracker/obsidian-plugin && npm test

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

License

MIT License - See LICENSE for details.

Acknowledgements

  • Obsidian - Powerful knowledge management tool
  • Feynman Learning Method researchers

"If you can't explain it simply, you don't understand it well enough." - Richard Feynman