Kage Sensei

Kage Sensei is a TypeScript monorepo for AI coding memory and project-aware mentoring. It contains two related tools:

• kage: a CLI memory layer for AI coding tools, powered by MemWal on Walrus.
• sensei: a project-aware mentor with a CLI and web interface, also backed by MemWal and Walrus.

The tools share the same goal: keep useful project knowledge available across AI coding sessions.

What Is Implemented

• Compression-first memory storage for Kage (@kage-sensei/compression):
  • gzip compression with reversible fallback
  • local CCR metadata store
  • relevance scoring and token budget fitting
  • deterministic context alignment for cache-friendly prefixes
• Kage local learning loop:
  • kage learn mines local session failures
  • writes generated guidance blocks to CLAUDE.md and AGENTS.md
  • stores learned rules in ${KAGE_LESSONS_DIR:-/home/kage/lessons}/lessons.json
• Kage MCP server:
  • stdio transport for local MCP clients
  • Streamable HTTP transport for remote MCP clients
  • tools: kage_remember, kage_recall, kage_context, kage_stats, kage_learn, kage_learn_start, kage_learn_poll, kage_learn_results, kage_export, kage_suggest, kage_analyze, kage_fetch_sessions, kage_cleanup
  • kage_recall/kage_context return CCR-backed memories to stay consistent with kage_stats
• Sensei Web MCP endpoint:
  • POST /mcp (initialize + message)
  • GET /mcp (resume SSE stream)
  • DELETE /mcp (terminate session)
• Sensei Web auth and secure upload:
  • POST /api/auth/login (returns JWT)
  • POST /api/auth/change-password (requires JWT)
  • POST /api/sessions/upload (requires JWT + x-api-key)
  • POST /api/sync-project (requires JWT, accepts local source ZIP for Learn V2)
  • GET /api/stats and GET /api/learn-history for dashboard metrics
  • GET /login and GET /dashboard (Tailwind-based developer dashboard)
• The Bridge local sync path:
  • packages/cli/sync.js zips a local project's src/ directory
  • uploads it to the cloud Sensei API
  • runs Kage Learn V2 server-side
  • stores the resulting project lessons in Walrus via MemWal
• Landing app:
  • standalone Astro + Tailwind marketing site at apps/landing
  • includes branded OG/favicons and legal pages (/privacy, /terms)
  • ready for static deploy to Vercel/Netlify

Projects

Kage

Kage stores and retrieves long-term developer memory for tools such as Codex, Claude Code, and OpenCode.

Main commands:

• kage remember: save a memory.
• kage recall: search saved memories.
• kage context: print context for an AI coding session.
• kage why: retrieve reasoning behind a previous decision.
• kage stats: show compression and storage savings.
• kage mcp serve --stdio|--http: expose Kage over MCP.
• kage learn: mine local failures into reusable project rules.
• kage cleanup: detect legacy remote memories missing from CCR and optionally migrate them.

See kage/README.md for the full Kage guide.

Sensei

Sensei is a project-aware mentor that stores project memory, ingests repositories, and answers questions using remembered project context.

The Sensei CLI supports:

• sensei note: store a project memory.
• sensei load: ingest a git repository into memory.
• sensei ask: ask the mentor about the project.
• sensei recall: search project memory directly.
• sensei context: print context for AI tools.
• sensei team: manage team access.

Sensei also includes a web app with a Hono API server and React/Vite client.

Sensitive routes are protected by JWT middleware for /api/* (except /api/health and /api/auth/login) and /dashboard.

Repository Layout

.
├── kage/          # Kage CLI package
│   └── packages/
│       └── compression/   # Shared compression module
├── apps/
│   └── landing/   # Astro landing page (static deploy)
├── packages/
│   └── cli/       # Local Bridge sidecar for source sync
├── sensei/
│   ├── cli/       # Sensei CLI package
│   └── web/       # Sensei web client and API server
├── Dockerfile
├── docker-compose.yml
├── .env.ec2.example
├── LICENSE
└── README.md

Prerequisites

• Node.js 22+ or Bun 1+
• pnpm
• MemWal credentials from memory.walrus.xyz

Sensei also needs an InferStack-compatible API key for mentor responses.

Quick Start

Kage

cd kage
pnpm install
cp .env.example .env
pnpm build
node dist/index.js --help

Sensei CLI

cd sensei/cli
pnpm install
cp .env.example .env
pnpm build
node dist/index.js --help

Sensei Web

cd sensei/web
pnpm install
pnpm dev:server

In another terminal:

cd sensei/web
pnpm dev:client

Docker Deployment

You can run Kage Sensei with one container (Sensei Web + Kage runtime) using Docker Compose.

Local / EC2 with Compose

cp .env.ec2.example .env.ec2
# fill credentials
ENV_FILE=.env.ec2 docker compose up --build -d

Health checks:

curl -s http://localhost:3000/health
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Docker Hub Image

Published image:

• bernieweb3/kage-sensei:latest

Pull and run:

docker pull bernieweb3/kage-sensei:latest
docker run --rm -p 3000:3000 --env-file .env.ec2 bernieweb3/kage-sensei:latest

For a full EC2 walkthrough, see docs/deploy/aws-ec2-docker-compose.md.

The runtime image keeps TypeScript source code at:

• /app/kage/src
• /app/sensei/web/server/src

This supports meta-learning demos where the deployed MCP server runs kage_learn against its own source. The image also includes unzip for Bridge sync uploads and sets KAGE_LEARN_ALLOWED_ROOTS=/app,/tmp.

MCP Direct Connection (No mcp-remote)

Kage Sensei uses MCP Streamable HTTP transport (POST /mcp, GET /mcp, DELETE /mcp), so you can connect directly without mcp-remote.

Codex config example:

[mcp_servers.kage-sensei]
url = "https://kage-sensei.hackon.team/mcp"

Remote initialize test:

curl -X POST https://kage-sensei.hackon.team/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

Kage Learn V2 Meta-Learning Test

After deploying the current Docker image, test that the MCP server can learn from its own source code:

Call kage_learn with projectDir="/app/kage/src", maxFiles=20, maxLessons=10, debug=true.
Then call kage_learn with projectDir="/app/sensei/web/server/src", maxFiles=20, maxLessons=10, debug=true.
Report files analyzed, lessons found, patterns detected, discovered .ts files, and metadata breakdown.

Expected behavior:

• The server discovers .ts source files under both runtime paths.
• Learn V2 checks heuristic patterns such as TODO density, console usage, long functions, duplicate code, hardcoded secrets, deep nesting, and magic numbers.
• Matching patterns return lessons and pattern metadata.

See docs/devlog/2026-06-19.md and the related Learn V2 foundation notes in docs/devlog/2026-06-18.md.

Bridge Local Project Sync

The Bridge lets a local project send source code to the cloud MCP server without making the cloud server access local files directly.

Server route:

• POST /api/sync-project

Accepted input:

• multipart/form-data
• file: ZIP archive containing source code
• projectName: project identifier
• gitUrl: repository URL or local

Required header:

• Authorization: Bearer <jwt-from-/api/auth/login>

The server extracts the ZIP to a per-request temp directory, validates archive paths before extraction, runs kageLearnV2, stores a project_sync memory in Walrus, returns scan/lesson counts and the MemWal job id, then removes the temp directory.

Default safety limits:

• ZIP size: 50MB via KAGE_SYNC_MAX_ZIP_BYTES
• Rate limit: 10 requests per 15 minutes via KAGE_SYNC_RATE_LIMIT_MAX and KAGE_SYNC_RATE_LIMIT_WINDOW_MS

Local CLI setup:

cd packages/cli
npm install

Sync a local project:

cd /path/to/local/project
KAGE_CLOUD_URL=https://kage-sensei.hackon.team \
KAGE_TOKEN=<jwt-token> \
node /path/to/kage-project/packages/cli/sync.js

The CLI reads Git metadata from .git/config, zips src/, skips generated directories, posts to /api/sync-project, and prints the server response.

Memory Consistency and Cleanup

kage_stats reads local CCR metadata (${KAGE_DATA_DIR}/ccr.json). If old remote-only memories exist in MemWal from earlier runs, they can create mismatches with recall results.

Use kage_cleanup to detect these legacy entries and optionally migrate them into fresh CCR-backed records:

cd kage
pnpm build
node dist/index.js cleanup --query E2E --limit 50
# optional migration:
node dist/index.js cleanup --query E2E --limit 50 --migrate-to-walrus

The command writes a report to ${KAGE_DATA_DIR:-/home/kage/data}/cleanup-report.json.

Secure Session Upload API

Upload session logs from external systems to feed kage_learn.

Route:

• POST /api/sessions/upload

Accepted inputs:

• application/json: body must be an array of session objects
• multipart/form-data: include one JSON file (field file recommended)

Required headers:

• Authorization: Bearer <jwt-from-/api/auth/login>
• x-api-key: <API_SECRET_KEY>

Stored path and filename format:

• ${KAGE_DATA_DIR:-/home/kage/data}/sessions/
• session-{timestamp}-{randomId}.json

Example flow:

# 1) Login
TOKEN=$(curl -sS -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password":"123456"}' | jq -r .token)

# 2) Upload sessions
curl -X POST http://localhost:3000/api/sessions/upload \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "x-api-key: ${API_SECRET_KEY}" \
  -d '[{"id":"session-1","events":[{"type":"message","text":"hello"}]}]'

Environment

Kage and Sensei use MemWal/Walrus credentials:

• MEMWAL_PRIVATE_KEY
• MEMWAL_ACCOUNT_ID
• MEMWAL_SERVER_URL
• MEMWAL_NAMESPACE for Kage, optional

Sensei uses additional project and model settings:

• SENSEI_PROJECT_ID
• INFERSTACK_API_KEY
• INFERSTACK_BASE_URL, optional
• INFERSTACK_MODEL, optional

Auth settings for Dashboard and protected API routes:

• JWT_SECRET (recommended for login/session token signing)
• JWR_SECRET (legacy alias accepted if JWT_SECRET is not set)
• ADMIN_PASSWORD_HASH (recommended in Render env)
• AUTH_ENCRYPTION_KEY (required only if you store rotated hash in encrypted file)
• API_SECRET_KEY (required for /api/sessions/upload)
• CLAUDE_API_KEY (for kage_fetch_sessions)
• OPENAI_API_KEY (for kage_fetch_sessions)
• COMPATIBLE_API_KEY and COMPATIBLE_BASE_URL (for compatible providers in kage_fetch_sessions)
• KAGE_HOME (default /home/kage)
• KAGE_DATA_DIR (default ${KAGE_HOME}/data)
• KAGE_LESSONS_DIR (default ${KAGE_HOME}/lessons)
• KAGE_ANALYZE_PER_FILE_TIMEOUT_MS (default 5000)
• KAGE_ANALYZE_TOTAL_TIMEOUT_MS (legacy fallback, default 600000)
• KAGE_TOTAL_TIMEOUT_MS (global MCP tool timeout, default 600000)
• KAGE_ANALYZE_MAX_FILES (default 50)
• KAGE_SYNC_MAX_FILES (default 50)
• KAGE_SYNC_MAX_LESSONS (default 20)
• KAGE_SYNC_TIMEOUT_MS (default 60000)
• KAGE_SYNC_UNZIP_TIMEOUT_MS (default 30000)
• KAGE_SYNC_MAX_ZIP_BYTES (default 52428800)
• KAGE_SYNC_RATE_LIMIT_MAX (default 10)
• KAGE_SYNC_RATE_LIMIT_WINDOW_MS (default 900000)

Generate admin password hash (default password is 123456):

cd sensei/web
pnpm auth:generate-hash

Do not commit real .env files. Use .env.example files as templates.

License

This project is licensed under the terms in LICENSE.