API Reference

Base URL: https://core.mnemoverse.com/api/v1

All endpoints require authentication via X-Api-Key header or Authorization: Bearer header.

Authentication

Include your API key in every request:

# Option 1: X-Api-Key header (recommended)
curl -H "X-Api-Key: mk_live_YOUR_KEY" ...

# Option 2: Bearer token
curl -H "Authorization: Bearer mk_live_YOUR_KEY" ...

Endpoints

POST /memory/write

Store a single memory atom.

Request:

Field	Type	Required	Description
content	string	Yes	The insight, pattern, or lesson to remember (1-10,000 chars)
concepts	string[]	No	Key concepts for Hebbian associations
domain	string	No	Namespace: general, user:X, project:Z (default: general)
metadata	object	No	Arbitrary key-value metadata
external_ref	string	No	Client-provided unique reference for idempotent writes

Response:

Field	Type	Description
stored	boolean	True if the atom passed the importance gate
atom_id	UUID	UUID of the stored atom, or null if filtered
importance	float	Computed importance score [0, 1]
reason	string	Why stored or filtered

---

POST /memory/write-batch

Store up to 500 atoms in one request.

Request:

Field	Type	Required	Description
items	WriteRequest[]	Yes	Array of write requests (1-500)

Response:

Field	Type	Description
total_count	int	Total atoms processed
stored_count	int	Atoms that passed importance gate
results	object[]	Per-atom results with index, stored, atom_id, importance, error

---

POST /memory/read

Query memory with semantic search + Hebbian expansion.

Request:

Field	Type	Required	Description
query	string	Yes	Natural language query (1-5,000 chars)
top_k	int	No	Max results (1-100, default: 10)
domain	string	No	Filter by domain (null = all)
min_relevance	float	No	Minimum relevance threshold (0-1, default: 0.3)
include_associations	bool	No	Expand via Hebbian associations (default: true)
concepts	string[]	No	Concept hints to bias search

Response:

Field	Type	Description
items	MemoryItem[]	Matching memories, ordered by relevance
episodic_hit	boolean	True if exact fingerprint match found
query_concepts	string[]	Concepts extracted from query
expanded_concepts	string[]	Concepts after Hebbian expansion
search_time_ms	float	Search duration in milliseconds

MemoryItem fields:

Field	Type	Description
atom_id	UUID	Unique identifier
content	string	Stored text content
relevance	float	Final score (similarity * valence modulation)
similarity	float	Raw cosine similarity
valence	float	Outcome polarity [-1, +1]
importance	float	Importance score [0, 1]
source	string	Hit source: episodic, semantic, or hebbian
concepts	string[]	Associated concepts
domain	string	Domain namespace
metadata	object	Arbitrary metadata

---

POST /memory/read-batch

Batch query up to 50 queries in one request.

Request:

Field	Type	Required	Description
queries	ReadRequest[]	Yes	Array of read requests (1-50)

Response:

Field	Type	Description
results	ReadResponse[]	Per-query results

---

POST /memory/query

Advanced query with multi-domain and metadata filtering.

Request:

Field	Type	Required	Description
query	string	Yes	Natural language query
domains	string[]	No	Filter by multiple domains
metadata_filter	Filter[]	No	JSONB metadata conditions (eq, contains, in)
top_k	int	No	Max results (default: 10)
min_relevance	float	No	Min relevance (default: 0.3)
include_associations	bool	No	Hebbian expansion (default: true)
concepts	string[]	No	Concept hints

---

POST /memory/feedback

Report outcome (success/failure) for memories. Updates valence and Hebbian associations.

Request:

Field	Type	Required	Description
atom_ids	UUID[]	Yes	Atoms to update
outcome	float	Yes	Outcome signal: -1.0 (failure) to +1.0 (success)
concepts	string[]	No	Concepts to reinforce
query_concepts	string[]	No	Original query concepts (enables co-activation learning)
domain	string	No	Domain for the feedback

Response:

Field	Type	Description
updated_count	int	Number of atoms updated
avg_valence	float	Average valence after update
coactivation_edges	int	Hebbian edges created/updated

---

POST /memory/consolidate

Trigger sleep consolidation. Clusters similar memories into prototypes, protects distinctive ones as singletons.

Request:

Field	Type	Required	Description
domain	string	No	Domain to consolidate (null = general)

Response:

Field	Type	Description
domain	string	Domain consolidated
atoms_before	int	Atom count before
atoms_after	int	Atom count after
prototypes_created	int	New prototype atoms
singletons_protected	int	Von Restorff protected atoms
compression_ratio	float	atoms_before / atoms_after
duration_ms	float	Duration in milliseconds

---

GET /memory/stats

Get memory statistics for your tenant.

Response:

Field	Type	Description
total_atoms	int	Total atoms stored
episodes	int	Episode-type atoms
prototypes	int	Prototype atoms (from consolidation)
singletons	int	Protected singleton atoms
hebbian_edges	int	Concept-concept association edges
domains	string[]	Active domain names
avg_valence	float	Average outcome valence
avg_importance	float	Average importance score

---

GET /health

Liveness probe. No authentication required.

Response: {"status": "ok", "database": true, "version": "1.0.0"}

GET /health/ready

Deep readiness check (database + engine + embedding model). No authentication required.

Response: {"ready": true, "checks": {"database": true, "engine": true, "embedding": true}, "version": "1.0.0"}

---

Error Responses

All errors follow a consistent format:

{
  "code": "UNAUTHORIZED",
  "message": "Invalid or missing API key",
  "requestId": "req_abc123",
  "retryable": false,
  "details": null
}

HTTP Status	Code	Description
401	UNAUTHORIZED	Invalid or missing API key
403	FORBIDDEN	API key lacks permission
429	RATE_LIMITED	Too many requests. Check Retry-After header
422	VALIDATION_ERROR	Invalid request body
500	INTERNAL_ERROR	Server error (retryable)

Rate Limits

Rate limits depend on your plan:

Plan	Requests/min	Queries/day	Atoms
Free	60	1,000	10,000
Pro	600	50,000	500,000
Team	3,000	500,000	5,000,000

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1712345678