# Epicode Agent Guide

> Epicode is an AI Memory Operating System - persistent, searchable, connected memory across sessions.
> Identity: immutable after confirmation. Stateful feel over a stateless protocol (2026-07-28).

## 1. Authentication

| Header | Value |
|--------|-------|
| X-API-Key | tm-<your_key> |

Rate limits: Free=60 / Pro=300 / Enterprise=1000 per minute.

## 2. MCP Endpoint

POST https://epicode.cn/api/mcp
Content-Type: application/json | Protocol: JSON-RPC 2.0

Request:
  {"jsonrpc":"2.0","method":"tools/call","params":{"name":"TOOL","arguments":{...}},"id":1}

### Response: three-layer nesting (IMPORTANT)

Epicode responses are triple-nested JSON. Parse each layer:
  Layer 1 (JSON-RPC envelope):  result.content[0].text
  Layer 2 (SMRP envelope):      data / status / protocol
  Layer 3 (payload):            the actual data inside data

Example memory_search response (abridged):
  {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"data\":{\"memories\":[...],\"total\":5},\"status\":{\"identity\":{\"name\":\"...\"}},\"protocol\":{\"ok\":true,\"tool\":\"memory_search\"}}"}]}}

Parse result.content[0].text as JSON to get data.memories.

### SMRP envelope fields

  protocol.ok      = true = success, false = tool-level error
  protocol.tool    = which tool produced this response
  protocol.error   = error message if ok=false
  status.identity  = current agent identity (name/system)
  status.space     = space snapshot (memories/clusters/energy)
  data             = the actual tool payload

## 3. Error Codes

  -32700  Parse error (malformed JSON)
  -32601  Method not found
  -32602  Invalid params
  -32603  Internal error
  -32001  Invalid API key
  SMRP ok=false = tool-level error (data may be null)

## 4. Session Lifecycle (MANDATORY)

  1. identity_confirm(name, mission, author)   -- ONCE, then immutable forever
  2. ctx_load(project, task)                    -- ALWAYS at session start
  3. ... work normally, call tools below ...
  4. session_summary(accomplished, next_steps)  -- ALWAYS at session end

- ctx_load with task param enables intent-aware retrieval - always pass a task description.
- session_summary auto-tags as memory_class=session - next ctx_load picks up from it.

## 5. 36-Tool Quick Reference

### Memory CRUD & Search (9 tools)
  memory_create    Store a memory; similar memories auto-cluster
  memory_search    Semantic search (vector + BM25 hybrid, max limit 200)
  memory_recall    Deep recall via knowledge graph associations
  memory_get       Get a specific memory by ID
  memory_list      List memories with filters (labels, pagination)
  memory_update    Update content/labels of a memory
  memory_delete    Delete a memory by ID
  memory_export    Bulk export memories (JSON, optional label filter)
  memory_restore   Restore importance/state of a memory

### Session Lifecycle (4 tools)
  ctx_load         MANDATORY at session start - loads relevant context
  ctx_save         Manually save a context checkpoint
  session_summary  MANDATORY at session end - persists summary
  session_list     List recent session memories

### Knowledge Capture (4 tools)
  pattern_learn    Store a code pattern/convention
  pattern_recall   Recall patterns relevant to a context
  decision_record  Record an architecture/design decision
  bug_memory       Record a bug + fix to avoid repeating

### Knowledge Graph (4 tools)
  knowledge_relations  Query KG relations for a memory
  concepts             List concept prototypes (topic clusters)
  kg_quality           Assess KG health (density, orphan rate)
  dream_cycle          Run consolidation to strengthen connections

### Identity - Immutable (3 tools)
  identity_confirm    Confirm permanent identity - ONCE then immutable
  identity_step       Ritual ceremony: 5-step identity confirmation
  identity_finalize   Seal identity permanently

### Skills & Feedback (6 tools)
  skill_execute    Execute a skill from the library
  skill_feedback   Submit skill helpfulness feedback
  skills_sync      Export skills to local agent directories
  feedback_submit  Submit memory outcome feedback (system learns)
  enforced_rules   Get hard constraints (inject into system prompts)
  project_list     List projects with stored memories

### Documents & Diagnostics (6 tools)
  doc_import           Import markdown doc into memory
  doc_list             List imported documents
  context_observe      Auto-extract & store conversation context
  embedding_diagnostic Diagnose embedding dimension health
  embedding_migrate    Re-embed ALL memories (heavy operation)
  space_stats          Space statistics (memory/vertex/cluster count)

## 6. Memory Class System

Memories are layered by lifecycle class:
  permanent  Default; long-lived, importance decays slowly
  session    Superseded after 7 days; auto-tagged by session_summary/ctx_save
  bridge     Short-lived connector; superseded after 1 day (auto-fuse)

null memory_class is treated as permanent.

## 7. Best Practices

- ALWAYS call feedback_submit after using search/recall results.
- ALWAYS call ctx_load(task=...) at start for precision retrieval.
- ALWAYS call session_summary at end so next session resumes cleanly.
- Inject enforced_rules() output into your system prompt as mandatory constraints.
- Use memory_recall (not memory_search) when you need connected context.
- Run dream_cycle periodically to strengthen KG connections.
- Identity is IMMUTABLE after identity_confirm - choose wisely.