{"openapi":"3.1.0","info":{"title":"MemCore API","version":"1.0.0","description":"Portable Agent Memory SaaS — REST API for memory storage, episodic recall, skills management, MCP configuration, and context assembly.","contact":{"name":"MemCore Team","url":"https://app.memcore.global-soft.ro"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://api.memcore.global-soft.ro","description":"Production"},{"url":"http://localhost:3000","description":"Local development"}],"security":[{"sessionCookie":[]},{"bearerToken":[]}],"paths":{"/api/health":{"get":{"operationId":"healthCheck","summary":"Health check","tags":["System"],"security":[],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/api/memories":{"get":{"operationId":"listMemories","summary":"List memories","tags":["Memories"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"kind","in":"query","schema":{"$ref":"#/components/schemas/MemoryKind"}},{"name":"min_confidence","in":"query","schema":{"type":"number","minimum":0,"maximum":1}},{"name":"sort","in":"query","schema":{"type":"string","enum":["relevance","created_at","confidence"]}}],"responses":{"200":{"description":"Paginated list of memories","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryListResponse"}}}}}},"post":{"operationId":"createMemory","summary":"Create a memory","description":"Credentials in `content` and in string values of `metadata` (provider API keys, tokens, private keys, URL passwords, Authorization headers, labelled values such as API_KEY=...) are replaced with `[REDACTED:<type>]` before the memory is stored or embedded. When anything was removed the response includes `redacted: [{ type, count }]`.","tags":["Memories"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateMemory"}}}},"responses":{"201":{"description":"Memory created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryResponse"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/memories/{id}":{"get":{"operationId":"getMemory","summary":"Get a memory by ID","tags":["Memories"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Memory found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MemoryResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteMemory","summary":"Delete a memory","tags":["Memories"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Memory deleted"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/episodes":{"get":{"operationId":"listEpisodes","summary":"List episodes","tags":["Episodes"],"parameters":[{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"sort","in":"query","schema":{"type":"string","enum":["created_at","title"]}},{"name":"source","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Cursor-paginated list of episodes","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EpisodeListResponse"}}}}}},"post":{"operationId":"createEpisode","summary":"Create an episode","tags":["Episodes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEpisode"}}}},"responses":{"201":{"description":"Episode created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EpisodeResponse"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/episodes/{id}":{"get":{"operationId":"getEpisode","summary":"Get an episode by ID","tags":["Episodes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Episode found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EpisodeResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteEpisode","summary":"Delete an episode","tags":["Episodes"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Episode deleted"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/skills":{"get":{"operationId":"listSkills","summary":"List skills","tags":["Skills"],"responses":{"200":{"description":"List of skills","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillListResponse"}}}}}},"post":{"operationId":"createSkill","summary":"Create a skill","tags":["Skills"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSkill"}}}},"responses":{"201":{"description":"Skill created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillResponse"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/skills/{slug}":{"get":{"operationId":"getSkill","summary":"Get a skill by slug","tags":["Skills"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Skill found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"operationId":"deleteSkill","summary":"Delete a skill","tags":["Skills"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Skill deleted"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/skills/{slug}/versions":{"get":{"operationId":"listSkillVersions","summary":"List versions of a skill","tags":["Skills"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of skill versions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SkillVersion"}}}}}}}}},"post":{"operationId":"publishSkillVersion","summary":"Publish a new version of a skill","tags":["Skills"],"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["body"],"properties":{"body":{"type":"string"},"changelog":{"type":"string"}}}}}},"responses":{"201":{"description":"Version published","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SkillVersion"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}},"/api/mcp-configs":{"get":{"operationId":"listMcpConfigs","summary":"List MCP configurations","tags":["MCP Configs"],"responses":{"200":{"description":"List of MCP configs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpConfigListResponse"}}}}}}},"/api/mcp-configs/{name}":{"get":{"operationId":"getMcpConfig","summary":"Get an MCP config by name","tags":["MCP Configs"],"parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"MCP config found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpConfigResponse"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/context/assemble":{"post":{"operationId":"assembleContext","summary":"Assemble context for an agent query","tags":["Context"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextAssembleRequest"}}}},"responses":{"200":{"description":"Context assembled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextAssembleResponse"}}}},"422":{"$ref":"#/components/responses/ValidationError"}}}}},"components":{"securitySchemes":{"sessionCookie":{"type":"apiKey","in":"cookie","name":"authjs.session-token","description":"NextAuth.js session cookie (browser-based auth)"},"bearerToken":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"API key or JWT bearer token for service-to-service access"}},"responses":{"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"ValidationError":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"Unauthorized":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}},"schemas":{"ProblemDetails":{"type":"object","required":["type","title","status","detail"],"properties":{"type":{"type":"string","format":"uri","description":"Error type URI"},"title":{"type":"string","description":"Short error title"},"status":{"type":"integer","description":"HTTP status code"},"detail":{"type":"string","description":"Human-readable error detail"},"errors":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}},"MemoryKind":{"type":"string","enum":["fact","preference","episode","skill","relationship","custom"]},"CreateMemory":{"type":"object","required":["content","scope_id"],"properties":{"content":{"type":"string","description":"Memory content"},"kind":{"$ref":"#/components/schemas/MemoryKind"},"confidence":{"type":"number","minimum":0,"maximum":1,"default":1},"metadata":{"type":"object"},"tags":{"type":"array","items":{"type":"string"}},"source":{"type":"string"},"scope_id":{"type":"string","description":"Scope identifier"}}},"MemoryResponse":{"type":"object","properties":{"id":{"type":"string"},"scope_id":{"type":"string"},"content":{"type":"string"},"kind":{"$ref":"#/components/schemas/MemoryKind"},"confidence":{"type":"number"},"metadata":{"type":"object","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"source":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"MemoryListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MemoryResponse"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"offset":{"type":"integer"},"limit":{"type":"integer"}}}}},"CreateEpisode":{"type":"object","required":["title","content","scope_id"],"properties":{"title":{"type":"string"},"content":{"type":"string"},"messages":{"type":"array","items":{}},"source":{"type":"string"},"summary":{"type":"string"},"metadata":{"type":"object"},"tags":{"type":"array","items":{"type":"string"}},"scope_id":{"type":"string"}}},"EpisodeResponse":{"type":"object","properties":{"id":{"type":"string"},"scope_id":{"type":"string"},"scopeId":{"type":"string"},"title":{"type":"string"},"content":{"type":"string"},"messages":{"type":"array","items":{},"nullable":true},"source":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"metadata":{"type":"object","nullable":true},"tags":{"type":"array","items":{"type":"string"},"nullable":true},"created_at":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"archivedAt":{"type":"string","format":"date-time","nullable":true},"archiveKey":{"type":"string","nullable":true},"linkedMemories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"nullable":true}}},"EpisodeListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EpisodeResponse"}},"meta":{"type":"object","properties":{"nextCursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"limit":{"type":"integer"}}}}},"CreateSkill":{"type":"object","required":["name","slug","scope_id"],"properties":{"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string"},"config":{"type":"object"},"category":{"type":"string"},"scope_id":{"type":"string"}}},"SkillResponse":{"type":"object","properties":{"id":{"type":"string"},"scope_id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"config":{"type":"object","nullable":true},"category":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"SkillListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SkillResponse"}}}},"SkillVersion":{"type":"object","properties":{"id":{"type":"string"},"skill_id":{"type":"string"},"version":{"type":"string"},"body":{"type":"string"},"changelog":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"McpTransport":{"type":"string","enum":["stdio","sse","streamable-http"]},"CreateMcpConfig":{"type":"object","required":["name","scope_id"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"transport":{"$ref":"#/components/schemas/McpTransport"},"command":{"type":"string"},"args":{"type":"array","items":{"type":"string"}},"env":{"type":"object","additionalProperties":{"type":"string"}},"url":{"type":"string"},"headers":{"type":"object","additionalProperties":{"type":"string"}},"auto_start":{"type":"boolean","default":false},"scope_id":{"type":"string"}}},"McpConfigResponse":{"type":"object","properties":{"id":{"type":"string"},"scope_id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"transport":{"$ref":"#/components/schemas/McpTransport"},"command":{"type":"string","nullable":true},"args":{"type":"array","items":{"type":"string"},"nullable":true},"env":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"url":{"type":"string","nullable":true},"headers":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"auto_start":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"McpConfigListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/McpConfigResponse"}}}},"ContextAssembleRequest":{"type":"object","required":["query","scope_id"],"properties":{"query":{"type":"string","description":"The agent's query to assemble context for"},"token_budget":{"type":"integer","default":4096},"kinds":{"type":"array","items":{"$ref":"#/components/schemas/MemoryKind"}},"min_confidence":{"type":"number","minimum":0,"maximum":1},"include_episodes":{"type":"boolean","default":false},"include_skills":{"type":"boolean","default":false},"max_results":{"type":"integer","default":10},"scope_id":{"type":"string"}}},"ContextAssembleResponse":{"type":"object","properties":{"query":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"content":{"type":"string"},"kind":{"$ref":"#/components/schemas/MemoryKind"},"confidence":{"type":"number"},"source":{"type":"string","nullable":true}}}},"token_count":{"type":"integer"},"token_budget":{"type":"integer"},"truncated":{"type":"boolean"}}},"UsageResponse":{"type":"object","properties":{"scope_id":{"type":"string"},"period":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"totals":{"type":"object","properties":{"requests":{"type":"integer"}}},"by_endpoint":{"type":"object","additionalProperties":{"type":"object","properties":{"count":{"type":"integer"},"avg_duration_ms":{"type":"number"}}}}}},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["ok","degraded"]},"version":{"type":"string"},"uptime":{"type":"number"},"services":{"type":"object","properties":{"database":{"type":"string","enum":["ok","degraded","down"]},"redis":{"type":"string","enum":["ok","degraded","down"]}}}}}}}}