1. Executive Summary

Shokunin is a local-first AI memory system and skills ecosystem that solves three critical problems: context loss between sessions, keyword-blind vector search, and stale memory claims. It provides persistent storage via ChromaDB, multi-strategy retrieval (vector + BM25 + temporal + RRF), and 62 curated engineering skills that auto-activate based on task context.

2. Problem Statement

Context Loss

AI coding agents forget everything between sessions. Every conversation starts from scratch — decisions, files modified, commands run, preferences discovered — all gone. The agent cannot recall what it did yesterday.

Keyword-Blind Retrieval

Vector similarity search alone misses exact keyword matches. When you search for api-forge or docker or a specific file path like src/auth/middleware.ts, vector search returns semantically similar but lexically different results. Pure BM25 doesn't understand synonyms or intent.

Stale Memory Claims

Memory entries are claims from a frozen point in time. A file path remembered three weeks ago may have been refactored out of existence. Without verification, the agent acts on stale information, creating bugs instead of solving them.

Vendor Lock-In

Enterprise memory solutions (Hindsight, MemGPT) require PostgreSQL, Docker, and cloud API calls. Developers working offline, on air-gapped machines, or with limited infrastructure cannot use them.

3. Architecture

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

4. Memory System

Entry Types

Every memory entry has a type, tags, project, and session ID. The type system enables filtered retrieval and claim verification:

Freshness Decay

v4.2.2 introduces exponential recency blending with a 30-day half-life:

final_score = (1 - freshness_boost) × vector_similarity + freshness_boost × e^(-days_since / 30)

At freshness_boost = 0, pure vector similarity. At freshness_boost = 1.0, pure recency. Default is 0.0 (no decay). This prevents stale claims from drowning out recent, accurate context.

Claim Verification

The verify_file_path MCP tool validates file paths from memory before the agent acts on them. Memory entries are treated as claims from a frozen point in time, not facts. The workflow:

1. Agent retrieves a memory entry mentioning a file path
2. Agent calls verify_file_path to check if the path still exists
3. If the path exists, mark with verified_at timestamp
4. If the path is gone, search newer memory or the codebase directly

Session Management

Three operations solve the "which session was I in?" problem:

• list — Show recent sessions with date, project, entry count, summary
• continue — Load full context from a session, parse decisions/files/commands from text
• auto-log — Every MCP tool call writes to sessions/<id>.jsonl automatically

5. MCP Tools Reference

Nine tools over JSON-RPC 2.0 on stdin/stdout. No HTTP, no cloud.

Protocol

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "multi_search_context",
    "arguments": {
      "query": "docker multi-stage build",
      "project": "myapp",
      "n_results": 5,
      "from_date": "2026-05-01"
    }
  }
}

Data Flow

AI Runtime → JSON-RPC → MCP Server (mcp-server.py)
                              │
                              ├──► ChromaDB (vector + metadata)
                              │      Storage: ~/.shokunin/memory/chroma_db/
                              │      Embedding: all-MiniLM-L6-v2 (384-dim)
                              │
                              ├──► Session JSONL (append-only)
                              │      ~/.shokunin/memory/sessions/<id>.jsonl
                              │
                              └──► Markdown fallback
                                     ~/.shokunin/memory/sessions/<id>.md

6. Skills

62 skills across 10 domains. Each is a real engineering guide with decision tables, error patterns, production checklists, anti-patterns, and cited sources. Not generic prompts — structured procedural knowledge.

7. Benchmarks

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

Configuration: Embedding: all-MiniLM-L6-v2 (22M, 384-dim). BM25: k1=1.5, b=0.75. Fusion: RRF k=60. Full methodology and reproduction steps.

8. Comparison with Hindsight

Hindsight (vectorize-io/hindsight) leads memory benchmarks (91.4% LongMemEval). Shokunin targets the local-first developer who needs zero infrastructure.

9. Runtime Compatibility

The core (skills, memory, scripts) is runtime-agnostic. Only MCP server configuration and instruction files differ.

10. Installation & Quick Start

Requirements

Windows Install

irm https://raw.githubusercontent.com/EliasOulkadi/shokunin/master/install.ps1 | iex

Linux Install

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

After Install

# Start OpenCode with memory capture
.\run-opencode.ps1

# List recent sessions
python ~/.shokunin/scripts/chroma-helper.py session list 3

# Search across all memory
python ~/.shokunin/scripts/chroma-helper.py recall "docker multi-stage"

# Validate memory system
.\memory-healthcheck.ps1

Shokunin v4.2.2 · MIT License · github.com/EliasOulkadi/shokunin · eliasoulkadi.github.io/shokunin