CogmemAi REST API Reference

CogmemAi / REST API

The same memory engine that powers the MCP server is available over plain HTTPS, in any language, from any runtime. Use it when MCP isn’t an option: serverless functions, web frontends, mobile apps, edge runtimes, agents written in Go, Rust, Python, Ruby, or any non-Node stack.

Base URL and authentication

https://hifriendbot.com/wp-json/hifriendbot/v1

Every request needs an API key in the Authorization header. Get one free at /developer/#get-key.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Response format

All responses are JSON. Success responses return the requested data. Errors return:

{
  "error": "human-readable message",
  "code": "machine-readable code"
}

HTTP status codes follow standard conventions: 200 for success, 400 for bad input, 401 for missing or invalid auth, 402 when usage exceeds the plan limit, 404 when the resource doesn’t exist, 429 for rate limiting, 5xx for backend issues.

End-to-end example: save and recall

The shortest possible save → recall flow, in three languages.

curl:

# save a memory
curl -X POST https://hifriendbot.com/wp-json/hifriendbot/v1/cogmemai/store 
  -H "Authorization: Bearer YOUR_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "content": "Orders service uses GraphQL only. Mobile latency budget 200ms.",
    "memory_type": "decision",
    "importance": 9,
    "scope": "project",
    "project_id": "orders-service"
  }'

# recall later (different session, same project)
curl -X POST https://hifriendbot.com/wp-json/hifriendbot/v1/cogmemai/recall 
  -H "Authorization: Bearer YOUR_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "query": "what did we decide about the orders service API?",
    "project_id": "orders-service",
    "limit": 5
  }'

Python:

import requests

BASE = "https://hifriendbot.com/wp-json/hifriendbot/v1"
HEADERS = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

# save
requests.post(f"{BASE}/cogmemai/store", headers=HEADERS, json={
    "content": "Orders service uses GraphQL only. Mobile latency budget 200ms.",
    "memory_type": "decision",
    "importance": 9,
    "scope": "project",
    "project_id": "orders-service",
})

# recall
result = requests.post(f"{BASE}/cogmemai/recall", headers=HEADERS, json={
    "query": "what did we decide about the orders service API?",
    "project_id": "orders-service",
    "limit": 5,
}).json()

JavaScript / TypeScript (Node 20+):

const BASE = "https://hifriendbot.com/wp-json/hifriendbot/v1";
const headers = {
  "Authorization": `Bearer ${apiKey}`,
  "Content-Type": "application/json",
};

// save
await fetch(`${BASE}/cogmemai/store`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    content: "Orders service uses GraphQL only. Mobile latency budget 200ms.",
    memory_type: "decision",
    importance: 9,
    scope: "project",
    project_id: "orders-service",
  }),
});

// recall
const result = await fetch(`${BASE}/cogmemai/recall`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    query: "what did we decide about the orders service API?",
    project_id: "orders-service",
    limit: 5,
  }),
}).then(r => r.json());

Endpoint reference

All endpoints sit under /cogmemai/ (full path: /wp-json/hifriendbot/v1/cogmemai/...). All POST and PATCH endpoints accept JSON bodies. All GET endpoints take query-string parameters.

Memory lifecycle

Method	Path	Purpose
POST	/cogmemai/store	Save a memory. Also used for corrections and reminders (pass memory_type: "correction" or "reminder").
POST	/cogmemai/recall	Semantic recall, ranked by relevance + recency + importance.
POST	/cogmemai/smart-recall	Higher-quality recall with reasoning, for complex queries.
GET	/cogmemai/context	Load top memories for a project (call this on session start).
GET	/cogmemai/memories	List all memories matching filters (type, category, scope, tag).
PATCH	/cogmemai/memory/{id}	Update a memory’s content, importance, type, or tags.
DELETE	/cogmemai/memory/{id}	Delete a memory.
POST	/cogmemai/memory/{id}/promote	Lift a project-scope memory to global so it applies everywhere.

Bulk operations

Method	Path	Purpose
POST	/cogmemai/bulk-delete	Delete many memories by ID list. Body: { "ids": [1,2,3] }.
POST	/cogmemai/bulk-update	Update many memories in one call. Body: { "updates": [{ "id": 1, ... }] }.
GET	/cogmemai/export	Export all memories matching a filter (JSON download).
POST	/cogmemai/import	Bulk-load memories from a previous export or external source.

Intelligence

Method	Path	Purpose
POST	/cogmemai/extract	Extract a batch of memories from a conversation transcript. Identifies type, importance, and tags automatically.
POST	/cogmemai/ingest	Ingest a long document (PDF, markdown, transcript) as memories. Body: { "content": "...", "project_id": "..." }.
POST	/cogmemai/consolidate	Merge related memories into a single comprehensive summary. Takes up to 30 seconds.
POST	/cogmemai/generate-skills	Generate Anthropic-style SKILL.md content from accumulated memories.
POST	/cogmemai/extract-principles	Distill long-standing patterns into reusable principles. Up to 30 seconds.

Knowledge graph

Method	Path	Purpose
POST	/cogmemai/memory/{id}/link	Connect this memory to another (related fact, supersedes, contradicts).
GET	/cogmemai/memory/{id}/links	Get all memories linked to this one, with relationship types.
GET	/cogmemai/memory/{id}/versions	Version history for a memory (auto-tracked on every PATCH).

Analytics and feedback

Method	Path	Purpose
GET	/cogmemai/analytics	Usage patterns, recall frequency, health metrics.
GET	/cogmemai/usage	Current monthly usage vs plan limits.
GET	/cogmemai/stale	Memories that haven’t been recalled in N days, candidates for cleanup.
GET	/cogmemai/tags	List all tags currently in use, with memory counts.
POST	/cogmemai/feedback	Signal that a recalled memory was useful or not. Improves ranking over time.

Sessions

Method	Path	Purpose
POST	/cogmemai/session-summary	Save a wrap-up summary of what was accomplished in a session. Surfaces at next session start.

Request body essentials

Common fields across /cogmemai/store and recall endpoints:

Field	Type	Notes
content	string	The memory itself. One or two sentences, self-contained.
memory_type	string	identity, preference, architecture, decision, bug, dependency, pattern, context, session_summary, task, correction, reminder. Custom types accepted.
importance	int 1-10	10 = core architecture, 1 = trivial.
scope	string	project (default) or global. team requires Pro plan.
project_id	string	Scopes the memory to one codebase. Auto-detected from cwd or git remote when called via MCP; pass explicitly via REST.
tags	string[]	Up to 5 tags, each up to 30 chars. For grouping related memories.
category	string	frontend, backend, devops, etc. Custom values accepted.
subject	string	Short label (e.g. auth_system) for organization.
ttl	string	Auto-expire after this duration (24h, 7d, 30d).

Rate limits

Plan	Memories / month	Extractions / month	Projects	Requests / minute
Free	500	500	5	60
Pro	Higher limits	Higher limits	Unlimited	600
Team / On-prem	Custom	Custom	Unlimited	Custom

When you exceed a limit, requests return HTTP 402 Payment Required with an upgrade link. See pricing.

SDKs and clients

• MCP server (TypeScript, the recommended path for Claude Code, Claude Agent SDK, Cursor, Windsurf, Cline, Continue): npm install -g cogmemai-mcp
• Direct API / SDK for low-latency deep integration: contact us
• Working examples in JS and Python: quickstart repo

Help

Stuck? Tell us what you’re building. We answer real engineering questions, not just sales.