Skip to content
職人
職人

# 職人 Shokunin

Multi-strategy AI memory with 62 expert skills. Your context persists between sessions. Zero servers. No API calls. One command.

62 skills 6 runtimes Open source

    bash <(curl -sL https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install.sh)

View on GitHub Browse all 62 skills → Read the technical overview

## What it does

Your AI agent forgets between sessions. Vector search alone misses exact keywords and can't filter by date. Shokunin fixes all three.

### Multi-strategy recall

ChromaDB vector search combined with BM25 keyword matching, temporal date-range filters, and reciprocal rank fusion. Pure Python. Zero dependencies.

### Session management

`session list` shows recent sessions with metadata. `session continue` loads full context (decisions, files, commands parsed automatically). No more guessing which session to resume.

### MCP auto-logging

Every MCP tool call logged to sessions/<id>.jsonl. 9 tools across 6 AI coding runtimes. Works in OpenCode, Claude Code, Cursor, Windsurf, Cline, and Continue. Zero agent coordination needed.

Built on 99+ memory entries, 62 expert skills, 9 MCP tools, 25+ CI checks, and 6 AI runtimes.

## Architecture

Seven layers. Clear boundaries. No server processes. Everything runs on your machine.

Config ~/.config/opencode/ provider setup, MCP servers, agents, commands Instructions ~/AGENTS.md + CLAUDE.md global rules, session startup workflow Update ~/.shokunin/shokunin.json declarative manifest, drift detection Orchestration ~/.shokunin/scripts/ session wrapping, healthchecks, cleanup Memory ~/.shokunin/memory/ ChromaDB, MCP server, auto-log JSONL Skills ~/.config/opencode/skills/ 62 SKILL.md, automatic activation Infrastructure ~/.shokunin/backups/ backups, logs, database files

## Session management

### List

`session list 3` shows recent sessions with date, project, entries, and summary. The agent runs it automatically at startup so you can pick where to continue.

### Continue

`session continue <id>` loads the full session. Parses text from session_end entries to extract decisions, files modified, and commands. Even if saved as one blob.

### Auto-log

Every MCP tool call (`store_context`, `search_context`, `save_message`) writes to `sessions/<id>.jsonl` automatically. No agent coordination needed.

## MCP tools

Nine tools across six AI coding runtimes. All tools auto-logged to JSONL.

store_context — save text with type, tags, project, session_id
search_context: vector similarity search with project/tag filters
multi_search_context — vector + BM25 + temporal filter + RRF fusion (v4.2.1)
consolidate_memories — group old entries by project with keyword extraction
list_sessions — list recent sessions with metadata (v4.2.2)
continue_session — load full session context with parsed decisions/files (v4.2.2)
save_message — record individual message in session JSONL transcript
verify_file_path — verify file/directory exists with metadata (v4.2.2)
get_session_summary — summarize all entries in a given session
OpenCode
Claude
Cursor
Cline
Continue
Windsurf

## Comparison with Hindsight

Hindsight (vectorize-io/hindsight) leads memory benchmarks (91.4% LongMemEval). We took the ideas that make sense for a local tool and left the enterprise dependencies.

Aspect | Shokunin | Hindsight
--- | --- | ---
Storage | ChromaDB (file, 30 MB) | PostgreSQL + pgvector
Search strategies | 2 (vector + BM25) + temporal | 4 (semantic, BM25, graph, temporal)
Result fusion | Reciprocal Rank Fusion | RRF + cross-encoder rerank
LLM dependency | None for memory ops | Required per retain() call
Install | 1 shell script | Docker or pip + PostgreSQL
Offline | Full (no network) | Partial (needs LLM API)
MCP auto-log | Built-in | Not available
Session mgmt | list/continue/save + text parsing | Not available

## Skills

62 skills across 10 domains. Powered by Emil Kowalski (Sonner 13M+ weekly downloads, Linear), Paul Bakaus (ex-Google, ex-Disney, ex-Unity), and Leon Lin + blueemi. Each skill is a real engineering guide with Before/After tables, exact specs, pre-flight checklists, and cited sources.

### Infrastructure

docker, kubernetes, terraform, ci-cd, db-admin

### Backend

auth-architect, api-forge, db-sculptor, error-handler

### Frontend

component-forge, responsive-engine, motion-craft, landing-craft, aesthetic-web, ui-ux-pro-max, emil-design-eng, impeccable, taste, taste-soft, taste-minimalist

### Mobile

flutter, react-native

### Quality

test-commander, performance-profiler, code-review, comprehensive-review, cross-review, zen-review, zen-comprehensive-review

### Content & Business

communication, content-marketing, business-proposals, seo-geo, translate-craft, documentation

### Documents

kami (PDF), portfolio-auto, kagen (AI images)

### Productivity

git-workflow, windows-powershell, runbook-gen, strategy, design, finance, legal-counsel, whendone-plus

### AI Agents

agent-browser, agent-tools, find-skills, skill-creator, research, humanize

### System

memory, chromadb, shokunin-update, init, efficient-coding, senior-engineer, plan, playwright, neon-postgres, web-security

Every skill follows the same v4.0 structure: YAML frontmatter for auto-discovery, sub-commands (design / audit / optimize), exact specifications (100-160ms for button press, hash passwords with Argon2id memory=19456), Before/After review tables, error handling tables, pre-flight production checklists, banned patterns, and cited sources. The motion-craft skill, for example, is 20 KB covering Emil Kowalski's exact easing curves, duration tables by element type, and a mandatory review format.

## Benchmarks

Measured on 15 queries (3 iterations x 5 queries) against 120+ real ChromaDB entries. The multi-strategy returns real-world sessions 60% of the time that vector-only misses completely.

100% Any relevant hit Both strategies
60% Real session hits vs 0% vector-only
1.4s Avg latency +13.8% overhead

The multi-strategy finds real sessions that vector-only never returns.

While the synthetic probe hit rate is lower (40% vs 100%), BM25 correctly prioritizes semantically richer real entries above the probe. 100% of queries return at least one relevant result.

Real session hits
0%
60%
Any relevant hit
100%
100%
Probe hit rate
100%
40%
Avg latency
1293ms
1471ms
Vector-only Multi-strategy
Embedding: all-MiniLM-L6-v2 (22M, 384-dim) · BM25: k1=1.5, b=0.75 · Fusion: RRF k=60 Full methodology and reproduction steps

## FAQ

Does it work offline?

Yes. Everything runs locally. No cloud dependency, no API calls per memory operation, no telemetry.

What runtimes are supported?

OpenCode, Claude Code, Cursor, Cline, Continue.dev, and Windsurf. MCP templates included for each.

Do I need an NVIDIA API key?

No. OpenCode Go is the default provider and works without any key. NVIDIA is optional.

How is this different from Hindsight?

Shokunin is local-first (no servers, no Docker). Hindsight is enterprise (better benchmarks, heavier infrastructure). They solve overlapping problems at different scales.

How do I install?

Full install (Windows): `irm https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install.ps1 | iex`. Linux: `bash <(curl -sL https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install.sh)`.
Skills-only (no ChromaDB): `irm https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install-skills.ps1 | iex`