# Sensei

### AI That Remembers How to Teach You

Claude is smart enough to be a great mentor. It just doesn't know who it's talking to.

**Sensei** gives Claude memory about *you* — your skill level, what you've learned, and what you're building.

```
You: "How do I handle errors in useEffect?"

Claude: [Checks Sensei]
        → Knows you understand promises, are learning React hooks
        → Knows you're building a fintech app with Supabase

Claude: "Since you're comfortable with try/catch from your async work,
        the pattern in useEffect is similar. For your Supabase queries..."
```

No more "First, let me explain what useEffect is..." every single time.

---

## Quick Start

### 1. Add to Claude Code

Add this to your Claude Code MCP settings (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "sensei": {
      "command": "npx",
      "args": ["-y", "@sensei-mcp/sensei"]
    }
  }
}
```

### 2. Add the System Prompt

Copy the contents of [PROMPT.md](./PROMPT.md) into your Claude Project's custom instructions.

This tells Claude *how* to use Sensei effectively.

### 3. Start Learning

That's it. Claude now remembers who you are.

---

## What Sensei Tracks

### Skills

Three levels. Simple.

| Level | Meaning |
|-------|---------|
| `unknown` | Never discussed |
| `learning` | Covered basics, still developing |
| `solid` | Uses independently, understands well |

### Learning History

What Claude has taught you, so it can reference past explanations:

```
2025-01-14: explained "useEffect cleanup" (react-hooks)
2025-01-13: explained "async/await" (javascript)
```

### Project Context

What you're building:

```
Project: fintech-app
Stack: React, TypeScript, Supabase
Notes: "REST API with row-level security"
```

### Prerequisites

Before explaining X, Claude checks if you know the prerequisites:

```
useEffect requires:
├── react-hooks (concept of hooks)
├── closures (effects close over state)
└── side-effects (what effects are for)
```

### Preferences

How you like explanations:

```
style: concise | detailed | example-heavy
languages: ["typescript", "python"]
```

---

## Tools Reference

| Tool | Purpose |
|------|---------|
| `sensei_get_context` | Get everything: skills, history, project, preferences |
| `sensei_get_skills` | Get skill levels |
| `sensei_set_skill` | Update a skill level |
| `sensei_log_learned` | Record that a concept was taught |
| `sensei_get_history` | Get learning history |
| `sensei_get_prerequisites` | Check prerequisites for a concept |
| `sensei_get_project` | Get project context |
| `sensei_set_project` | Update project context |
| `sensei_get_preferences` | Get explanation preferences |
| `sensei_set_preferences` | Update preferences |

---

## Privacy

- **All local.** Data stored in `~/.sensei/sensei.db`
- **No cloud.** No accounts. No telemetry.
- **Your data.** Export or delete anytime.

---

## Development

```bash
# Clone
git clone https://github.com/your-username/sensei
cd sensei

# Install
npm install

# Build
npm run build

# Run locally
node dist/index.js
```

### Project Structure

```
sensei/
├── src/
│   ├── index.ts          # MCP server entry
│   ├── db/               # SQLite database layer
│   │   ├── init.ts       # Database initialization
│   │   ├── skills.ts     # Skills CRUD
│   │   ├── history.ts    # History CRUD
│   │   ├── project.ts    # Project context
│   │   └── preferences.ts
│   └── tools/            # MCP tool handlers
│       ├── index.ts      # Tool registration
│       ├── handlers.ts   # Tool implementations
│       └── prerequisites.ts
├── knowledge/
│   └── prerequisites.json  # Concept prerequisite graph
├── PROMPT.md             # System prompt for Claude
└── README.md
```

---

## Contributing

The most valuable contributions are to the **prerequisite graph**.

```bash
# Edit knowledge/prerequisites.json
# Add your domain expertise

{
  "kubernetes-pods": ["docker", "containers", "yaml"],
  "graphql-resolvers": ["graphql-schema", "async-await"]
}
```

---

## Why "Sensei"?

先生 (sensei) — "one who comes before"

A teacher who remembers where you've been and guides where you're going.

---

## License

MIT

---

<p align="center">
  <strong>Sensei: AI That Remembers How to Teach You</strong>
</p>