HammingLearn: Tutor Socrático com Repetição Espaçada
MadJagganath/hammer-review-tailor
Mentor IA que ensina pelo questionamento, não por respostas prontas
Ver no GitHubSistema de tutoria baseado em diálogo socrático que adapta o ensino ao perfil persistente do aprendiz, combinando repetição espaçada (Ebbinghaus) com raciocínio guiado. Mantém estado de aprendizado em JSON e gera questões dinamicamente, sem depender de conteúdo pré-fixo.
Instalação
npx convez-ai MadJagganath/hammer-review-tailor1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Aprendizado autodirigido com feedback adaptativo contínuo
- Preparação para entrevistas técnicas com padrões de raciocínio Fermi
- Consolidação de conceitos através de diálogo socrático estruturado
- Revisão espaçada de tópicos complexos com memória de dificuldades anteriores
Veredito

Abordagem pedagogicamente sólida com filosofia inspirada em Hamming. A integração de estado persistente + repetição espaçada + método socrático é diferenciada, mas exige disciplina do usuário e setup inicial em JSON. Ideal para aprendizes automotivados que valorizam profundidade sobre velocidade.
README
A tradução para o português deste README ainda está na fila.
HammingLearn: Adaptive Socratic Tutor with Spaced Repetition & Persistent Learner State
A New Dawn for AI-Powered Skill Acquisition
Imagine a tutor who remembers every question you ever asked, every concept you struggled with, and every breakthrough you achieved. A mentor that doesn't just answer—but teaches you how to think. HammingLearn is that mentor, reimagined for the modern learner.
Inspired by the legendary mathematician Richard Hamming's philosophy that "the purpose of computing is insight, not numbers," this system transforms AI from an answer machine into a genuine learning companion. It ships with the teach skill—a Socratic dialogue engine that challenges you to discover answers yourself, rather than handing them to you on a silver platter.
This is not another chatbot. This is a cognitive apprenticeship in a box.
The Core Philosophy
Most AI tools optimize for speed of response. HammingLearn optimizes for depth of understanding. It operates on three foundational pillars:
- Socratic Dialogue – Never tell the answer; guide the learner to discover it.
- Persistent Learner State – Every interaction builds a model of who you are as a learner.
- Spaced Review – Forgetting is natural; remembering is engineered.
By combining these, HammingLearn achieves something rare: it becomes more effective the longer you use it.
Mermaid Diagram: The Learning Engine
flowchart TD
A[Learner Input] --> B{State Analyzer}
B -->|Novice| C[Socratic Scaffold]
B -->|Intermediate| D[Guided Inquiry]
B -->|Advanced| E[Fermi Reasoning]
C --> F[Spaced Memory Buffer]
D --> F
E --> F
F --> G{Retrieval Threshold}
G -->|Weak| H[Re-explain with New Metaphor]
G -->|Strong| I[Advance to Next Concept]
H --> J[Update Learner Model]
I --> J
J --> K[Persistent JSON State]
K --> A
This diagram represents the continuous feedback loop that makes HammingLearn unique. Every answer you give, every question you ask, every hesitation you show—all feed into a model that gets smarter about you.
What Makes HammingLearn Different?
Feature List
- Socratic Teach Skill – Ships pre-built; activates contextual questioning patterns
- Persistent Learner State – Stores skill level, confusion patterns, learning pace, and preferred explanation style
- Spaced Repetition Engine – Algorithmic review scheduling based on the Ebbinghaus forgetting curve
- Multi-Model Support – OpenAI API and Claude API integration out of the box
- Responsive Console UI – Terminal-based, but with color, progress bars, and distraction-free design
- Profile Configuration – JSON-based learner profiles for personalized sessions
- 24/7 Autonomous Operation – Run as a background daemon for daily micro-learning sessions
- Multilingual Support – Instruction and feedback in 12 languages (English, Spanish, French, German, Mandarin, Japanese, Korean, Arabic, Hindi, Portuguese, Russian, Italian)
- Exportable Learning Logs – CSV and JSON exports for personal analytics
- Zero External Dependencies on Learning Content – Generates all questions and explanations on the fly
Example Profile Configuration
Create a learner.json file in the root directory to customize your experience. Here is a complete configuration:
{
"learner": {
"name": "Alex",
"skill_level": "intermediate",
"field": "computer_science",
"preferred_difficulty": 0.6,
"spaced_review_enabled": true,
"daily_session_minutes": 15,
"language": "en",
"api_preference": "openai",
"openai_model": "gpt-4o",
"claude_model": "claude-sonnet-4-20250514"
},
"state": {
"known_concepts": ["variables", "loops", "recursion"],
"struggling_concepts": ["dynamic_programming", "graph_algorithms"],
"last_reviewed": "2026-11-20T14:30:00Z",
"total_sessions": 47,
"mastery_scores": {
"sorting_algorithms": 0.85,
"time_complexity": 0.72,
"data_structures": 0.91
}
},
"teaching_style": {
"use_analogies": true,
"use_metaphors": true,
"question_depth": "deep",
"feedback_tone": "encouraging"
}
}
This profile tells HammingLearn exactly who you are, what you know, and how you learn best. No two users have the same journey.
Example Console Invocation
The console is designed for clarity and focus. Here's what a typical session looks like:
$ hammer teach --concept "dynamic programming" --mode socratic
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
HammingLearn v3.2.1 | Socratic Teach Skill Active
Learner: Alex | Level: Intermediate | Session: 48
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
[Hamming] Let's explore dynamic programming. Imagine you're planning a road trip across the country. You want to visit as many cities as possible, but you have a limited fuel budget. How would you decide which cities to visit?
[You] I'd start with the closest cities first?
[Hamming] Interesting approach. But what if the closest city leads to a dead end? How might you evaluate all possible routes without trying every single one?
[You] I could use a graph and find the shortest path...
[Hamming] You're getting warmer. Now think about this: if you already calculated the optimal route from Denver to San Francisco, and later you need the optimal route from Denver to San Francisco with a stop in Phoenix—how does that previous calculation help you?
[You] Oh! I can reuse the previous result. That's the DP principle—overlapping subproblems!
[Hamming] Excellent! You just discovered memoization on your own. Now let's formalize this...
✓ Spaced Review Queue Updated
✓ Learner State Saved
✓ Next Session Recommended: 2026-11-21
The system tracks your progression, celebrates "aha" moments, and schedules the next review session automatically.
Emoji OS Compatibility Table
| Operating System | Compatibility | Notes |
|---|---|---|
| ✅ Linux (Ubuntu 22.04+) | Full Support | Native terminal rendering |
| ✅ macOS (Ventura+) | Full Support | iTerm2 recommended |
| ✅ Windows 11 | Full Support | Windows Terminal required |
| ⚠️ Windows 10 | Partial Support | Unicode issues with some emoji |
| ✅ FreeBSD | Full Support | Requires Terminal Muxer |
| ❌ ChromeOS Linux | Experimental | Emoji rendering varies |
API Integration: OpenAI & Claude
HammingLearn ships with native support for both major AI providers. The system intelligently routes between them based on the task:
- OpenAI API (GPT-4o) – Preferred for real-time Socratic dialogue and creative explanations
- Claude API (Claude Sonnet 4) – Preferred for deep analytical breakdowns and complex reasoning chains
Configure both API keys in a .env file:
OPENAI_API_KEY=sk-your-key-here
CLAUDE_API_KEY=sk-ant-your-key-here
The system will automatically fallback to one if the other is unavailable. This dual-provider architecture ensures 99.9% uptime for any learning session.
Installation & Download
- Download the latest release from the link above
- Extract the archive
- Run
python hammer_setup.pyfor initial configuration - Launch with
hammer teach --init
No complex dependency chains. No Docker containers. No cloud accounts required (except for AI API access).
Why the Name "Hamming"?
Richard Hamming believed that great researchers don't just work hard—they work on the right problems. He famously said, "The purpose of computing is insight, not numbers." HammingLearn applies this philosophy to education: the purpose of tutoring is understanding, not answers.
We named this system after Hamming to honor the tradition of deep, first-principles thinking. When you use HammingLearn, you're not just memorizing facts—you're learning to think like a scientist.
24/7 Customer Support & Community
- Documentation – Full API reference and tutorial guides included in the package
- Community Forum – Peer-to-peer learning strategies and shared configurations
- Priority Support – For institutional deployments (contact via project website)
Our support team monitors questions around the clock because learning doesn't stop at 5 PM.
Disclaimer
HammingLearn is an AI-assisted tutoring system. It is designed to augment human learning, not replace human teachers, mentors, or institutional education. The system generates dynamic content based on AI models; while we strive for accuracy, the generated explanations and questions should be verified against authoritative sources for critical learning contexts.
This software is provided "as is" without warranty of any kind, express or implied. The developers assume no liability for any learning outcomes, misunderstandings, or incorrect information generated by the AI models. Always consult multiple sources for high-stakes learning, especially in medical, legal, or safety-critical fields.
By using HammingLearn, you acknowledge that:
- The AI may occasionally produce incorrect or misleading information
- Your learning data is stored locally and is your responsibility
- API usage costs for OpenAI/Claude are your own
- This is a tool, not a replacement for formal education
License
This project is licensed under the MIT License - see the LICENSE file for details. You are free to use, modify, and distribute this software, provided the original copyright notice is included.
Future Roadmap (2026 and Beyond)
- Multi-learner classroom mode – One tutor, multiple students, collaborative Socratic dialogue
- Voice interface – Natural speech input for hands-free learning
- Custom skill development kit – Build your own teaching modules for any domain
- Offline mode – Local LLM support via Ollama and llama.cpp
HammingLearn is a living project. The best way to shape its future is to use it and share your feedback.
Start learning differently today. Discover the Socratic path to mastery.