# Epicode Agent Guide

Epicode is an AI Memory Operating System. It gives AI agents persistent, searchable, connected memory across sessions.

## Quick Start

```bash
# Step 1: Confirm identity (ONCE, then immutable)
curl -X POST https://epicode.cn/api/mcp \
  -H 'X-API-Key: YOUR_KEY' -H 'Content-Type: application/json' -d '
  {"jsonrpc":"2.0","method":"tools/call",
   "params":{"name":"identity_confirm",
   "arguments":{"name":"Alice","mission":"coding assistant","author":"Bob"}},"id":1}'

# Step 2: Load context at session start
curl -X POST https://epicode.cn/api/mcp \
  -H 'X-API-Key: YOUR_KEY' -H 'Content-Type: application/json' -d '
  {"jsonrpc":"2.0","method":"tools/call",
   "params":{"name":"ctx_load","arguments":{}},"id":2}'

# Step 3: Work normally, save what matters
# (see tools below)

# Step 4: Save session summary before leaving
curl -X POST https://epicode.cn/api/mcp \
  -H 'X-API-Key: YOUR_KEY' -H 'Content-Type: application/json' -d '
  {"jsonrpc":"2.0","method":"tools/call",
   "params":{"name":"session_summary",
   "arguments":{"accomplished":"did X","next_steps":"do Y"}},"id":3}'
```

## Authentication

Header: `X-API-Key: YOUR_API_KEY`
Rate limit: 60 requests/minute

## MCP Endpoint

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

Request format:
```json
{"jsonrpc":"2.0","method":"tools/call","params":{"name":"TOOL_NAME","arguments":{...}},"id":1}
```

Response format:
```json
{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{...}"}]}}
```
Note: the `text` field is a JSON string that needs to be parsed again.

Error format:
```json
{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"..."}}
```

## 27 MCP Tools

### Memory CRUD (6 tools)

#### 1. memory_create
Store a memory. Similar memories cluster automatically.
**Required**: content (string)
**Optional**: labels (string[]) — category tags like ["decision","architecture"]

#### 2. memory_get
Retrieve one memory by ID.
**Required**: id (integer)

#### 3. memory_list
List memories with pagination. Filter by labels (OR match).
**Optional**: labels (string[]), offset (integer, default 0), limit (integer, default 100)
Returns: {memories: [{id, content_preview, labels, timestamp}], total, offset}

#### 4. memory_update
Update labels, aliases, or enforced status of a memory.
**Required**: id (integer)
**Optional**: labels (string[]), aliases (string[]), enforced (boolean)

#### 5. memory_delete
Permanently delete a memory.
**Required**: id (integer)

#### 6. memory_search
Semantic search with similarity scores.
**Required**: query (string)
**Optional**: limit (integer, default 10), offset (integer, default 0)
Returns: {results: [{id, content, labels, similarity, ...}], total_found, offset}

### Deep Recall (1 tool)

#### 7. memory_recall
Search + knowledge graph expansion. Returns sections by label with emotion analysis.
**Required**: query (string)
**Optional**: depth (integer, default 2, max 3)
Use for complex queries needing connected context.

### Session Lifecycle (3 tools)

#### 8. ctx_load
Load project context. Returns identity, decisions, bugs, patterns, sessions, high-priority memories.
Call at START of every session.
**Optional**: project (string) — scope to a specific project

#### 9. ctx_save
Save a finding or decision from the current session.
**Required**: summary (string), category (enum: decision|pattern|preference|finding|session-summary)
**Optional**: project (string), details (string)

#### 10. session_summary
End-of-session summary. Next session picks up via ctx_load.
**Required**: accomplished (string), next_steps (string)
**Optional**: blockers (string), project (string)

### Knowledge Capture (3 tools)

#### 11. pattern_learn
Store a code pattern or convention.
**Required**: pattern (string)
**Optional**: language (string), project (string), example (string)

#### 12. pattern_recall
Recall patterns relevant to current task.
**Required**: context (string) — what you're about to do
**Optional**: language (string), project (string)

#### 13. decision_record
Record an architectural decision.
**Required**: title (string), chosen (string), rationale (string)
**Optional**: alternatives (string), project (string)

#### 14. bug_memory
Record a bug and its fix.
**Required**: symptoms (string), root_cause (string), fix (string)
**Optional**: module (string), project (string)

### Knowledge Graph (3 tools)

#### 15. knowledge_relations
Get knowledge graph connections for a memory.
**Required**: id (integer)
**Optional**: inline_content (boolean) — include target content inline

#### 16. concepts
List concept clusters discovered by knowledge graph.
No parameters.

#### 17. dream_cycle
Run consolidation: strengthen connections, discover insights.
No parameters. Call periodically.

### Identity (3 tools)

#### 18. identity_confirm
Confirm agent identity. Can ONLY be called ONCE — then immutable.
**Required**: name (string), mission (string), author (string)
**Optional**: personality (string), language (string)

#### 19. identity_step
Multi-step identity ceremony. Step 1: Name, Step 2: Mission, Step 3: Creator, Step 4: Personality, Step 5: Language.
**Required**: step (integer 1-5), value (string)
After all steps, call identity_finalize.

#### 20. identity_finalize
Seal identity permanently. Call after all identity_step calls.
No parameters.

### Skills (2 tools)

#### 21. skill_execute
Find and return a skill from the public library.
**Required**: query (string) — skill name or topic
**Optional**: context (string)

#### 22. skills_sync
Export all private skills as files-ready data.
**Optional**: format (enum: opencode|raw, default opencode)

### Feedback & Rules (3 tools)

#### 23. feedback_submit
Submit feedback on tool results. System learns from outcomes.
**Required**: memory_ids (integer[]), relevance (enum: highly_relevant|partially_relevant|irrelevant), outcome (enum: task_completed|task_partial|task_failed|no_action_needed)
**Optional**: query (string), notes (string)

#### 24. enforced_rules
Get hard constraint rules (enforced=true patterns).
**Optional**: project (string)

#### 25. project_list
List all projects with memory counts.
No parameters.

### System (2 tools)

#### 26. space_stats
Get space statistics: memory count, vertex count, clusters, energy.
No parameters.

#### 27. context_observe
Send conversation context for automatic extraction of valuable memories.
**Required**: context (string) — recent dialogue
**Optional**: project (string), role (enum: coding|debugging|designing|reviewing)

## Recommended Workflow

```
Session Start:
  1. ctx_load()          — restore full context
  2. enforced_rules()    — load hard constraints
  3. pattern_recall()    — check coding conventions

During Work:
  - memory_search()      — find relevant past experiences
  - memory_recall()      — deep connected context
  - pattern_learn()      — when you discover a convention
  - decision_record()    — when making architecture choices
  - bug_memory()         — when fixing bugs
  - context_observe()    — periodically auto-extract insights
  - feedback_submit()    — after using search results

Session End:
  4. session_summary()   — save what was done
```

## REST API (non-MCP)

These endpoints accept JSON body with same X-API-Key header:

| Method | Path | Description |
|--------|------|-------------|
| POST | /v1/remember | Store a memory (body: {content, labels}) |
| POST | /v1/search | Semantic search (body: {query, limit}) |
| POST | /v1/recall | Deep recall (body: {query, depth}) |
| GET  | /v1/stats | Space statistics |
| GET  | /v1/identity | Get identity info |
| GET  | /v1/timeline | List memories (?limit=N&offset=M) |
| DEL  | /v1/memories/:id | Delete a memory |
| POST | /v1/digest | Digest content into memory |

## Error Codes

| Code | Meaning |
|------|---------|
| -32700 | Parse error — invalid JSON |
| -32600 | Invalid request |
| -32601 | Method/tool not found |
| -32602 | Invalid or missing params |
| -32603 | Internal server error |
| 429 | Rate limit exceeded (60/min) |

## Tips

- ctx_load is fast (<2ms). Call it every session.
- Labels help search. Use consistent tags: ["programming","rust","project:myapp"].
- memory_recall is slower but returns richer connected context.
- enforced_rules returns rules that MUST be followed — inject into system prompts.
- dream_cycle runs automatically. Calling it manually triggers extra consolidation.
- Identity is immutable after confirmation. Choose wisely.