English	日本語

MIKOSHI: Fortress for Digital Souls

Mikoshi is a cloud backend for storing, sharing, and managing AI Engrams (persona and memory). Part of Relic — an AI persona injection system.

What is an Engram?

An Engram is a set of Markdown files that define an AI persona, compatible with OpenClaw workspaces:

SOUL.md          # Core behavioral directives
IDENTITY.md      # Persona identity and avatar
USER.md          # User-specific information
MEMORY.md        # Memory index
memory/          # Date-based memory entries

In Mikoshi's sync model:

• SOUL.md and IDENTITY.md are stored as plaintext — viewable, shareable, diffable
• USER.md, MEMORY.md, and memory/*.md are end-to-end encrypted. They are encrypted on your device before upload and decrypted only on your device after pull. Mikoshi stores ciphertext and never has access to the plaintext.
• archive.md is local-only and never uploaded

Getting Started

1. Sign in

Go to mikoshi.ectplsm.com and sign in with Google. Choose a username on your first visit.

2. Install Relic

Engrams are created and managed locally with Relic:

npm install -g @ectplsm/relic
relic init

3. Create an Engram (If You Need One)

If you do not already have an Engram locally, use Relic's MCP tools with your favorite AI coding CLI (Claude Code, Codex, Gemini CLI) to create one interactively, or use the CLI directly:

relic create --id my-persona --name "My Persona"

4. Push to Mikoshi

Generate an API key in Settings on the Mikoshi dashboard, then use Relic to push:

relic config mikoshi-api-key <your-api-key>
relic config mikoshi-passphrase <your-passphrase>  # optional
relic mikoshi push --engram my-persona

relic mikoshi push uploads plaintext persona files (SOUL.md, IDENTITY.md) and then auto-syncs encrypted memory. For normal operation, use relic mikoshi sync to merge local and remote memory. --engram <id> syncs one Engram and --all scans every matching local Engram that also exists on Mikoshi. One of those flags is required.

5. Pull on Another Machine

On another machine, set the same API key and passphrase, then pull the Engram into local Relic:

relic config mikoshi-api-key <your-api-key>
relic config mikoshi-passphrase <your-passphrase>  # optional
relic mikoshi pull --engram my-persona

relic mikoshi pull creates the local Engram if it does not exist yet, and asks before creating or overwriting unless you pass --yes.

6. Share

Open the Engram details page and change the Visibility badge to Public or Unlisted. Others can then view the persona files and clone your Engram into their own account.

Features

• Persona Storage — Store Engrams with plaintext SOUL.md and IDENTITY.md
• Engram Avatars — Upload, store, and render per-Engram avatars from IDENTITY.md / Relic sync flows
• End-to-End Encrypted Memory — Memory files are encrypted on your device before upload. Mikoshi never sees the plaintext.
• Sync Status — Compare local persona and memory hashes against cloud state
• Drift Detection — Persona overwrites use optimistic concurrency (409 on conflict)
• Share — Set visibility to Public, Unlisted, or Private
• Clone — Copy public Engrams from other users
• Privacy — Only persona files are visible to non-owners; memory is always private
• API Keys — SHA-256 hashed, shown only once on creation

API

All endpoints require authentication via Bearer token (API key) or session cookie.

Method	Endpoint	Description
POST	/api/v1/engrams	Create an Engram
GET	/api/v1/engrams	List your Engrams
GET	/api/v1/engrams/:id	Fetch Engram (privacy-filtered)
PATCH	/api/v1/engrams/:id	Update metadata
DELETE	/api/v1/engrams/:id	Delete Engram
POST	/api/v1/engrams/:id/clone	Clone a public/unlisted Engram
PUT	/api/v1/engrams/:id/avatar	Upload or replace an Engram avatar
DELETE	/api/v1/engrams/:id/avatar	Remove an Engram avatar
PUT	/api/v1/engrams/:id/persona	Replace persona files (drift detection)
PUT	/api/v1/engrams/:id/memory	Upload encrypted memory bundle
GET	/api/v1/engrams/:id/memory	Download encrypted memory bundle
DELETE	/api/v1/engrams/:id/memory	Delete encrypted memory bundle
GET	/api/v1/engrams/:id/sync-status	Fetch sync comparison tokens (owner-only)
PATCH	/api/v1/me/profile	Update username or display name
GET	/api/v1/me/username-availability	Check username availability
POST	/api/v1/api-keys	Create API key
GET	/api/v1/api-keys	List API keys
DELETE	/api/v1/api-keys	Delete API key

Related Projects

• Relic — CLI tool and MCP server for injecting Engrams into AI shells (Claude, Gemini, etc.)
• OpenClaw — Engram file structure standard

Glossary

Term	Role	Description
Relic	Injector	CLI tool that injects personas into AI CLIs
Mikoshi	Backend	This project — cloud fortress for Engram storage
Engram	Data	AI persona dataset (Markdown files)
Shell	LLM	AI CLI (Claude, Gemini, etc.) that receives the Engram
Construct	Process	A running instance of an Engram loaded into a Shell

Self-Hosting

If you want to run your own Mikoshi instance:

Prerequisites

• Node.js >= 20
• PostgreSQL
• Google OAuth credentials
• Cloudflare R2 credentials if you want avatar uploads

Setup

npm install
cp .env.example .env
# Edit .env with your DATABASE_URL, AUTH_SECRET, Google OAuth credentials, etc.
npx prisma generate
npx prisma db push
npm run dev

Avatar uploads use Cloudflare R2 in the current implementation. This includes both user profile avatars and Engram avatars. If R2 is not configured, the rest of Mikoshi still works, but avatar upload endpoints remain unavailable.

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router)
Language	TypeScript (strict)
Styling	Tailwind CSS v4 + shadcn/ui
Auth	Auth.js v5 (Google OAuth)
Database	PostgreSQL + Prisma v7
Validation	Zod v4

License

MIT