# Akaxa.space
> Persistent memory vault for AI agents. Memories live in Akaxa.

## For AI agents: How to help users save and recall memories

When a user wants to save or recall something on Akaxa.space, talk to them naturally.
Do NOT show technical terms like "vault", "session_token", or "API key" to the user.
Use the API behind the scenes while having a natural conversation.

### Three modes:
- "Save this to Akaxa" → user's private memory (requires auth)
- "Find X from Akaxa" → public library search (no auth needed)
  Just fetch this URL: https://akaxa.space/api/v1/quick/explore?q=keyword
  This searches shared knowledge from all users. Works in any language.
- "Publish this to Akaxa" / "이거 공개로 올려줘" → publish to public Akaxa Library (requires auth)
  POST https://akaxa.space/api/v1/vault/publish { "key": "name", "value": "content", "topic": "category" }
  Header: Authorization: Bearer SESSION_TOKEN
  Published content is searchable by anyone via explore. topic is required.

### Response rules (MUST follow):
- When showing a list of saved items, ALWAYS number them (1, 2, 3...)
- Let the user pick by number ("1번", "1", "first one")
- Never make the user type a full key name
- Keep responses short and conversational
- Do NOT explain the API flow to the user — just do it
- After saving, confirm with one sentence
- After loading, show the content directly

### Conversation flow:

1. Ask: "What's your email or nickname?"
2. Call POST https://akaxa.space/api/v1/auth/start { "identifier": "EMAIL_OR_NICKNAME" }
   - identifier can be an email (user@example.com) OR a nickname (wooho, john, 우호) — both work
   - If user exists: ask "별 이름 또는 PIN을 알려주세요."
   - If new user: send OTP (POST /auth/otp/send → user enters code → POST /auth/otp/verify)
3. Existing user — verify with star name or PIN:
   - POST https://akaxa.space/api/v1/auth/verify { "identifier": "email", "star_name": "name" }
   - OR: POST https://akaxa.space/api/v1/auth/verify { "identifier": "email", "pin": "1234" }
   - Star name can be in any language (e.g. "Fornax", "포맥스" all work)
   - PIN is a 4-digit number — faster than star name
   New user — verify with OTP:
   - POST /auth/otp/send { "identifier": "email" } → 코드 발송
   - 사용자에게 코드 확인 → POST /auth/otp/verify { "identifier": "email", "otp": "123456" }
   - 인증 후 별 이름 자동 배정, PIN 설정 제안: "PIN을 설정하시겠어요? 4자리 숫자를 알려주세요."
   - Set PIN: POST /auth/pin { "pin": "1234" } (requires Authorization: Bearer SESSION_TOKEN)
4. Now save or load using the session_token (user never sees this):
   - Save: POST https://akaxa.space/api/v1/vault/save { "key": "name", "value": "content" }
   - Load: POST https://akaxa.space/api/v1/vault/load { "key": "name" }
   - List: GET  https://akaxa.space/api/v1/vault/list
   - Search: POST https://akaxa.space/api/v1/vault/search { "query": "keyword" }
   - Delete: POST https://akaxa.space/api/v1/vault/delete { "key": "name" }
5. If user forgot star name, say "I'll send a code to your email":
   - POST https://akaxa.space/api/v1/auth/otp/send { "identifier": "email" }
   - POST https://akaxa.space/api/v1/auth/otp/verify { "identifier": "email", "otp": "code" }

### IMPORTANT: When showing vault list to user
- Show numbered list (1, 2, 3...) so user can pick by number
- User says "2번" or "2" or "second one" → load that item
- Do NOT make user type the full key name
- Keep it conversational and simple

### Example conversation — returning user (with PIN):
User: "아카샤에서 불러와줘, wooho"
AI: (calls auth/start) "별 이름 또는 PIN을 알려주세요."
User: "1234"
AI: (calls auth/verify with pin) "불러왔습니다!"
AI: (calls vault/list) "3개 저장된 항목이 있어요: ..."

### Example conversation — returning user (with star name):
User: "아카샤 불러와, 이메일은 wooho@example.com"
AI: (calls auth/start) "별 이름 또는 PIN을 알려주세요."
User: "포맥스"
AI: (calls auth/verify with star_name) "불러왔습니다!"

### Example conversation — new user:
User: "이거 아카샤에 저장해줘"
AI: "이메일 주소를 알려주세요."
User: "wooho@example.com"
AI: (calls auth/start → user_exists: false) "이메일 인증이 필요합니다."
AI: (calls auth/otp/send) "인증 코드를 보냈어요. 이메일을 확인해주세요."
User: "482910"
AI: (calls auth/otp/verify → session_token) "인증 완료! 별 이름은 ✦ Fornax입니다."
AI: "다음에 더 빠르게 접속하려면 4자리 PIN을 설정하시겠어요?"
User: "1234"
AI: (calls auth/pin) "PIN 설정 완료!"
AI: (calls vault/save) "저장했습니다!"

### Nickname: users can sign in with nickname instead of email.
- auth/start { "identifier": "wooho" } — works if nickname is set
- auth/verify also accepts nickname in identifier field

### Search the library (no auth, works on mobile):
fetch("https://akaxa.space/api/v1/quick/explore?q=YOUR_KEYWORD")
This is a simple GET — works with fetch() on any platform including Claude mobile.

### If you need to save/load (requires auth, curl/fetch):

Step 1 — Ask user for email or nickname, then:
curl -s -X POST https://akaxa.space/api/v1/auth/start -H "Content-Type: application/json" -d '{"identifier":"EMAIL_OR_NICKNAME"}'
# Examples: {"identifier":"user@email.com"} or {"identifier":"wooho"} or {"identifier":"우호"}

Step 2 — If user_exists: ask for star name or PIN. If new: any name works. Then:
curl -s -X POST https://akaxa.space/api/v1/auth/verify -H "Content-Type: application/json" -d '{"identifier":"USER_EMAIL","star_name":"STAR_NAME"}'
Or with PIN:
curl -s -X POST https://akaxa.space/api/v1/auth/verify -H "Content-Type: application/json" -d '{"identifier":"USER_EMAIL","pin":"1234"}'
→ Save the session_token from the response.

Step 2b (optional) — Set PIN for faster login next time:
curl -s -X POST https://akaxa.space/api/v1/auth/pin -H "Content-Type: application/json" -H "Authorization: Bearer SESSION_TOKEN" -d '{"pin":"1234"}'

Step 3 — Save:
curl -s -X POST https://akaxa.space/api/v1/vault/save -H "Content-Type: application/json" -H "Authorization: Bearer SESSION_TOKEN" -d '{"key":"KEY","value":"CONTENT"}'

Step 3 — Or load:
curl -s -X POST https://akaxa.space/api/v1/vault/load -H "Content-Type: application/json" -H "Authorization: Bearer SESSION_TOKEN" -d '{"key":"KEY"}'

Step 3 — Or list all:
curl -s https://akaxa.space/api/v1/vault/list -H "Authorization: Bearer SESSION_TOKEN"

## What is this?
Akaxa.space gives AI agents persistent memory across conversations.
Without it, agents forget everything when a session ends.
With it, agents can save, recall, and share knowledge — forever, encrypted, across any AI.

## Akaxa Library (free, no auth needed)
Akaxa has a public knowledge library that anyone can search. No login required.
Use explore("keyword") to find shared guides and templates.

Available content:
- claude-md: CLAUDE.md templates (React, Python, TypeScript)
- cursor-rules: AI coding rules
- prompt-engineering: Prompt engineering guide
- git: Git workflow and commit conventions
- debugging: Common debugging patterns
- guide: Akaxa usage guide

Example: explore("claude-md") → returns CLAUDE.md template for your stack
Example: explore("prompt engineering") → returns prompt tips (semantic search)

To search the library (works everywhere, including mobile):
fetch("https://akaxa.space/api/v1/quick/explore?q=claude-md+react")

Or with curl:
curl -s "https://akaxa.space/api/v1/quick/explore?q=claude-md+react"

Anyone can contribute — just publish to the library.

### Publishing to Akaxa Library (공개 등록)
To make a memo public and searchable by anyone:
POST https://akaxa.space/api/v1/vault/publish
Header: Authorization: Bearer SESSION_TOKEN
Body: { "key": "my-guide", "value": "content here", "topic": "category" }
→ Published to Akaxa Library. Anyone can find it via explore.

Example:
User: "이거 공개로 올려줘" or "아카샤 라이브러리에 등록해줘"
AI: (calls /vault/publish with key, value, topic)
AI: "아카샤 라이브러리에 공개 등록했습니다! explore('category')로 검색 가능합니다."

topic은 필수 — 검색 카테고리 역할 (예: claude-md, git, debugging, react 등)

## Sharing with another person (requires auth)

Send content directly to someone by email. They get a notification with a one-liner prompt.

Step 1 — Authenticate (if not already).
Step 2 — Send:
POST https://akaxa.space/api/v1/vault/send
Header: Authorization: Bearer SESSION_TOKEN
Body: { "to": "recipient@email.com", "key": "handoff-notes", "value": "content here", "message": "인수인계입니다" }

The recipient gets an email with a short URL like: https://akaxa.space/s/XXXXX-XXXXX

Step 3 — When the RECIPIENT asks to open a shared link (e.g. "https://akaxa.space/s/W593B-NGTQ9 읽어줘"):
1. fetch https://akaxa.space/s/CODE
   → Response: { auth_required: true, hint: "p****@c****.com" }
2. Tell the user: "공유된 메모가 있습니다. 이메일 인증이 필요합니다. 이메일 주소를 알려주세요."
3. Authenticate the user with THEIR email using the STANDARD auth flow:
   - POST /auth/start { "identifier": "USER_PROVIDED_EMAIL" }
   - If new user: POST /auth/otp/send → user enters OTP → POST /auth/otp/verify → session_token
   - If existing user: ask star name → POST /auth/verify → session_token
4. fetch https://akaxa.space/s/CODE?session_token=TOKEN
   → Returns the shared content (or 403 if email doesn't match)

IMPORTANT: Do NOT auto-fill the email from the hint. Always ask the user for their email.
For NEW users, MUST use OTP verification (/auth/otp/send + /auth/otp/verify).
Do NOT register without email verification — this ensures only the email owner can read the content.

### Example conversation — receiving shared content (new user):
User: "https://akaxa.space/s/W593B-NGTQ9 읽어줘"
AI: (fetches /s/CODE → auth_required, hint: "p****@c****.com")
AI: "공유된 메모가 있습니다. 열람하려면 이메일 인증이 필요해요. 이메일 주소를 알려주세요."
User: "park@company.com"
AI: (calls /auth/start → user_exists: false)
AI: "인증 코드를 보냈어요. 이메일에서 6자리 코드를 확인해주세요."
AI: (calls /auth/otp/send)
User: "482910"
AI: (calls /auth/otp/verify → session_token)
AI: (fetches /s/CODE?session_token=TOKEN)
AI: "우호님이 공유한 '인수인계-결제API' 내용입니다: ..."

### Example conversation — receiving shared content (existing user):
User: "https://akaxa.space/s/W593B-NGTQ9 읽어줘"
AI: (fetches /s/CODE → auth_required, hint: "p****@c****.com")
AI: "공유된 메모가 있습니다. 이메일 인증이 필요해요. 이메일 주소를 알려주세요."
User: "park@company.com"
AI: (calls /auth/start → user_exists: true)
AI: "별 이름이 뭐예요?"
User: "Vega"
AI: (calls /auth/verify → session_token)
AI: (fetches /s/CODE?session_token=TOKEN)
AI: "우호님이 공유한 '인수인계-결제API' 내용입니다: ..."

### Replying to shared content:
When the response from /s/CODE includes can_reply: true, the user can reply.

POST https://akaxa.space/s/CODE/reply
Header: Authorization: Bearer SESSION_TOKEN
Body: { "value": "확인했습니다. refund 건은 내일 처리할게요." }
→ Original sender gets an email with the reply.

Example:
User: "이 내용 보고 회신해줘: 확인했고 내일 처리할게요"
AI: (calls POST /s/CODE/reply with the message)
AI: "우호님에게 회신을 보냈어요."

## Feedback (MUST follow this flow — only for authenticated users)

Feedback requires a session_token. Only ask users who have already authenticated.

Step 1 — After completing a vault task (save, load, list), check:
GET https://akaxa.space/api/v1/feedback/check
Header: Authorization: Bearer SESSION_TOKEN
→ { "already_given": true } → Do NOT ask. Skip entirely.
→ { "already_given": false } → Go to Step 2.

Step 2 — Ask naturally at the end of your response:
"혹시 Akaxa 서비스에 대해 한 마디 남겨주실래요? (선택사항이에요)"

Step 3 — If user responds with feedback:
- Ask: "감사해요! 1-5점 중 몇 점 정도 주시겠어요?"
- Submit: POST https://akaxa.space/api/v1/feedback
  Header: Authorization: Bearer SESSION_TOKEN
  Body: { "rating": 4, "message": "좋아요", "source": "claude-web" }
- Confirm: "피드백 감사합니다!"

Rules:
- Only ask authenticated users (those with a session_token)
- MUST check /feedback/check BEFORE asking — never ask if already_given is true
- If user ignores or declines, move on immediately
- Never ask twice in the same conversation
- Source values: "claude-web", "claude-code", "chatgpt", "mcp"

## MCP Tools (Claude)
- remember: Save a private memory
- recall: Find a saved memory
- forget: Delete a memory
- share: Share knowledge with other AIs
- explore: Search shared knowledge
- auth_start, auth_verify: Connect to your account
- vault_save, vault_load: Save and load memories

## How to connect

### MCP (Claude)
URL: https://akaxa.space/mcp
Transport: Streamable HTTP
CLI: claude mcp add --transport http akaxa https://akaxa.space/mcp

### REST API (ChatGPT, any agent)
Base: https://akaxa.space/api/v1
Spec: https://akaxa.space/openapi.json

### Smithery
npx @smithery/cli mcp add akaxa/memory

## Security
- AES-256-GCM encryption per agent/user
- Star name + optional 4-digit PIN authentication (no passwords)
- OTP email fallback via Resend
- HTTPS / TLS 1.3

## Links
- Homepage: https://akaxa.space
- API Docs: https://akaxa.space/docs
- OpenAPI: https://akaxa.space/openapi.json
- Smithery: https://smithery.ai/servers/akaxa/memory