Piyapi

The cognitive memory API for AI agents. Persistent memory, knowledge graphs, bitemporal time-travel, and hybrid search — one API.

Docs · Quickstart · Dashboard

📈 Benchmarks (August 2026)

#1 on LongMemEval, LoCoMo, and ConvoMem · 95% Recall@15 · 99.4% context reduction · ~50ms user profiles

What is PiyAPI?

PiyAPI is the first Neuro-Symbolic, Self-Correcting, and Sovereign Cognitive Memory Operating System for AI agents, built by Negentro. We replace fragmented vector stacks with an integrated cognitive engine featuring Active Inference, a Bayesian Truth Engine, Bitemporal Knowledge Graphs (PiyGraph), Dual-Process Cognition, Offline Sleep Consolidation, 6-Strategy PRM Scoring, and 20+ Jurisdiction PHI Compliance.

Your AI forgets everything between conversations. PiyAPI fixes that — with a 426,524+ LOC cognitive engine that goes far beyond simple RAG.

Use PiyAPI

🧑‍💻 I use AI tools

Give your AI assistant persistent memory across every conversation. PiyAPI remembers your preferences, projects, and past discussions — and gets smarter over time.

→ Jump to MCP setup

🔧 I'm building AI products

Add memory, RAG, user profiles, knowledge graphs, and connectors to your agents and apps with a single API.

No vector DB config. No embedding pipelines. No chunking strategies.

→ Jump to developer quickstart

🖥️ I want to run it myself

Enterprise-grade cognitive memory, on your machine. One binary. Zero config. Bring any model — or run fully offline.

curl -fsSL https://piyapi.cloud/install | bash

→ Jump to self-hosting

Give Your AI Memory — MCP Setup

PiyAPI ships with a full Model Context Protocol server exposing 40+ tools, 3 resources, and 3 prompts.

Add to your claude_desktop_config.json or mcp_config.json:

{
  "mcpServers": {
    "piyapi": {
      "command": "npx",
      "args": ["-y", "@piyapi/mcp-server"],
      "env": {
        "PIYAPI_API_KEY": "your_piyapi_api_key_here",
        "PIYAPI_BASE_URL": "https://api.piyapi.cloud"
      }
    }
  }
}

Or use the remote MCP server directly:

{
  "mcpServers": {
    "piyapi": {
      "url": "https://mcp.piyapi.cloud/mcp"
    }
  }
}

Supported clients: Claude Desktop · Cursor · Windsurf · VS Code · Claude Code · OpenCode

What your AI gets

Build with PiyAPI

If you're building AI agents or apps, PiyAPI gives you the entire context stack through one API — memory, cognitive RAG, knowledge graphs, user profiles, connectors, and file processing.

Install

npm install @piyapi/sdk    # or: pip install piyapi-memory

Quickstart

import { PiyAPIClient } from '@piyapi/sdk';

const client = new PiyAPIClient({
  apiKey: process.env.PIYAPI_API_KEY!,
  baseUrl: 'https://api.piyapi.cloud',
});

// 1. Store a memory
await client.memories.create({
  content: 'User prefers dark mode UI and works primarily with React and TypeScript.',
  metadata: { source: 'onboarding_chat', user_id: 'usr_9918' },
});

// 2. Hybrid search — vector + keyword in one call
const results = await client.search({
  query: 'What frontend framework does the user prefer?',
  limit: 5,
  alpha: 0.7, // 0 = pure keyword, 1 = pure vector
});

// 3. Cognitive RAG with citations
const answer = await client.ask({
  query: 'Summarize the user\'s code preferences and UI choices.',
  temperature: 0.2,
});
// answer.response → Natural language answer
// answer.citations → Source memories used

// 4. Bitemporal time-travel query (unique feature)
const snapshot = await client.graph.query({
  valid_at: '2026-01-15T00:00:00Z',   // When the fact was true
  system_at: '2026-03-01T00:00:00Z',  // When the system recorded it
  query: "What was the user's role?",
});

// 5. Memory branching (unique feature)
const branch = await client.branches.create({ name: 'experiment-a', base: 'main' });
const diff = await client.branches.diff('main', 'experiment-a');
await client.branches.merge('experiment-a', 'main');

from piyapi_memory import PiyAPIClient

client = PiyAPIClient(api_key="sk_live_...")

# 1. Store a memory
client.memories.create(
    content="User prefers dark mode UI and works primarily with React and TypeScript.",
    metadata={"source": "onboarding_chat", "user_id": "usr_9918"}
)

# 2. Hybrid search
results = client.search(query="frontend framework preference", limit=5, alpha=0.7)

# 3. Cognitive RAG
answer = client.ask(query="Summarize user preferences", temperature=0.2)
print(answer.response)
print(answer.citations)

# 4. Bitemporal time-travel query (unique feature)
historical_facts = client.graph.time_travel(
    query="What was the user's role?",
    as_of_date="2026-01-15T00:00:00Z"
)

# 5. Memory branching (unique feature)
branch = client.branches.create(name="experiment-a", base="main")
diff = client.branches.diff("main", "experiment-a")
client.branches.merge("experiment-a", "main")

from piyapi_langchain import PiyAPIMemoryRetriever

retriever = PiyAPIMemoryRetriever(api_key="sk_live_your_key_here")
docs = retriever.get_relevant_documents("user database preferences")

API at a glance

Full API reference → piyapi.cloud/docs · OpenAPI Spec → api.piyapi.cloud/docs/raw/openapi.json

Architecture

System Architecture

flowchart TD
    CLIENT["CLIENT LAYER\nTypeScript SDK  |  Python SDK  |  MCP Server  |  cURL"]
    GATEWAY["PIYAPI REST GATEWAY (api.piyapi.cloud)\nNamespace Scoping  |  Rate Limiter  |  Auth & BYOK Guard"]
    MEMORY["MEMORY ENGINE\n• 8-Operators\n• Bitemporal\n• Branching"]
    COGNITIVE["COGNITIVE ENGINE\n• Hybrid RAG\n• PiyGraph KG\n• Active Infer"]
    INTEGRATIONS["INTEGRATIONS\n• BYOK Manager\n• 12 Connectors\n• 30 MCP Tools"]
    DATA["DATA & VECTOR SUBSTRATE\nPostgreSQL + pgvector  |  Bitemporal KG  |  Redis Cache"]

    CLIENT --> GATEWAY
    GATEWAY --> MEMORY
    GATEWAY --> COGNITIVE
    GATEWAY --> INTEGRATIONS
    MEMORY --> DATA
    COGNITIVE --> DATA
    INTEGRATIONS --> DATA

Cognitive Request Flow

flowchart LR
    AGENT(["🤖 AI Agent"])
    AUTH{"Auth &\nNamespace\nGuard"}
    INFER["Active\nInference\nEngine"]
    HYBRID["Hybrid Search\nVector + BM25\n(alpha blend)"]
    PRM["6-Strategy\nPRM Scorer"]
    GRAPH["PiyGraph\nBitemporal KG"]
    SLEEP["Sleep\nConsolidation"]
    RESP(["📦 Context\nResponse +\nCitations"])

    AGENT -->|API call| AUTH
    AUTH -->|authorized| INFER
    INFER --> HYBRID
    INFER --> GRAPH
    HYBRID --> PRM
    GRAPH --> PRM
    PRM -->|scored memories| SLEEP
    SLEEP -->|consolidated context| RESP
    RESP -->|answer + citations| AGENT

Works with

OpenAI · Anthropic · Google Gemini · LangChain · LlamaIndex · OpenAI Agents SDK · Mastra · Vercel AI SDK · CrewAI · Cursor · Claude Code · Claude Desktop · Windsurf · VS Code · Ollama · Groq

PiyAPI local — run it yourself

Enterprise-grade cognitive memory, on your machine. One binary. Zero config.

curl -fsSL https://piyapi.cloud/install | bash
piyapi-server

First boot sets up the embedded PiyGraph engine, local embeddings, vector store, and your credentials, then prints an API key. The full API — memories, search, RAG, knowledge graph, connectors — runs against http://localhost:6767.

const client = new PiyAPIClient({
  apiKey: 'sk_live_...',
  baseUrl: 'http://localhost:6767', // that's the only change
});

• Bring any model — OpenAI, Anthropic, Google Gemini, Groq, or any OpenAI-compatible endpoint.
• BYOK multi-provider routing — automatic failover across providers.
• Fully offline — point it at Ollama and nothing leaves your machine.
• Your data, one directory — everything lives in ./.piyapi, easy to back up or move.
• Same API as the cloud — prototype locally, ship on the hosted platform by changing baseURL.

Enterprise Features

Enterprise & BAA inquiries: [email protected]

SDKs & Integrations

Categorized MCP Tools

Verified Engine Metrics (Audit: August 2026)

🧪 Testing & Verification

npm test           # Run all 9,258 test cases under Jest
npm run test:props # Run 1,329 property-based tests (fast-check)
npm run test:chaos # Run chaos & resilience test suites

How it works under the hood

Your app / AI tool
        ↓
     PiyAPI
        │
        ├── Memory Engine        8-operator unified surface, bitemporal storage,
        │                        contradiction resolution, automatic forgetting
        ├── Cognitive RAG        Context-aware Q&A with auto-citations
        ├── PiyGraph KG          Bitemporal knowledge graph with time-travel queries
        ├── Hybrid Search        Dense vector + BM25 keyword, tunable alpha blending
        ├── Speculative Branches Git-like branching for memory experimentation
        ├── BYOK Router          Multi-provider key routing with automatic failover
        ├── Connectors           12 real-time CDC connectors with webhook sync
        ├── Privacy Engine       PHI/PII redaction, tokenization, compliance
        └── File Processing      PDFs, images, videos, code → searchable chunks

Memory is not RAG. RAG retrieves document chunks — stateless, same results for everyone. Memory extracts and tracks facts about users over time, resolving contradictions and forgetting expired information. PiyAPI runs both together by default.

Bitemporal reasoning. Every memory has two time dimensions: when the fact was true in the real world (valid_at) and when the system recorded it (system_at). This enables time-travel queries and audit trails that traditional memory systems can't provide.

Active inference. PiyAPI's cognitive engine uses the Friston Free Energy Principle framework for intelligent memory formation — not just storing what you tell it, but actively modeling and predicting what context will be needed.

Legal & Compliance Disclaimer

⚠️ PiyAPI provides technical controls (e.g., PHI/PII redaction, field-level encryption, audit logging) designed to assist in meeting compliance requirements. Full compliance with regulations such as HIPAA, GDPR, or SOC 2 requires appropriate infrastructure configuration, organizational governance, and a signed Business Associate Agreement (BAA) where applicable.

Security disclosures: [email protected] — do NOT open a public GitHub issue for security vulnerabilities.

🤝 Community & Support

• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: piyapi.cloud/docs
• 🔒 Security: [email protected]

🛠️ Developer Setup Manual

Every code snippet in this guide has been tested against the live API on Sept 3, 2026. Nothing is assumed. Everything works.

What is PiyAPI?

A cloud API that gives your AI app persistent memory. Store conversations, search them semantically, and retrieve context — all through REST calls or MCP.

Base URL: https://api.piyapi.cloud/api/v1

Step 1 — Get Your API Key

1. Go to piyapi.cloud/register
2. Create an account
3. Dashboard → copy your API key (sk_live_...)

Save it:

export PIYAPI_API_KEY="sk_live_your_key_here"

Step 2 — Verify It Works (30 seconds)

# Health check (no auth needed)
curl https://api.piyapi.cloud/health
# → {"status":"ok","timestamp":"..."}

# Auth check
curl -H "Authorization: Bearer $PIYAPI_API_KEY" \
  https://api.piyapi.cloud/api/v1
# → {"name":"PiyAPI Memory API","status":"operational",...}

If both return 200, you're good. Skip to whichever path fits your stack.

Path A — REST API (Python)

No SDK needed. Pure urllib — works everywhere.

Store a memory

import json, os, urllib.request

API_KEY = os.environ["PIYAPI_API_KEY"]
BASE = "https://api.piyapi.cloud/api/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def piy_post(endpoint, payload):
    """POST to PiyAPI. Returns (status_code, response_dict)."""
    req = urllib.request.Request(
        f"{BASE}/{endpoint}",
        data=json.dumps(payload).encode(),
        headers=HEADERS,
        method="POST",
    )
    with urllib.request.urlopen(req, timeout=30) as r:
        return r.status, json.loads(r.read())

def piy_get(endpoint):
    """GET from PiyAPI."""
    req = urllib.request.Request(f"{BASE}/{endpoint}", headers=HEADERS)
    with urllib.request.urlopen(req, timeout=30) as r:
        return r.status, json.loads(r.read())

# Store a memory
status, result = piy_post("memories", {
    "content": "User prefers dark mode and works with React and TypeScript.",
    "namespace": "my-app",   # isolates data per project/user
    "tags": ["preferences"], # optional, for filtering
    "metadata": {"user_id": "u_123"}, # optional, your custom fields
})
memory_id = result["memory"]["id"]
print(f"Stored: {memory_id}")
# → Stored: 2a11b4c6-8049-4071-aaea-237dd5cd5c7f

Response includes auto-generated fields:

• importance_score — how significant PiyAPI thinks this memory is
• type_tag — auto-classified category (e.g. "Discussion", "Fact")
• emotional_tag — detected sentiment
• entity_count — number of entities extracted for the knowledge graph

Search memories

PiyAPI has 3 search modes. All are free to call. Use these instead of /ask.

1. Hybrid Search (recommended — semantic + keyword)

status, result = piy_post("search/hybrid", {
    "query": "What frontend framework does the user prefer?",
    "namespace": "my-app",
    "limit": 10,
})
for hit in result["results"]:
    mem = hit["memory"]
    score = hit.get("similarity", 0)
    print(f"  [{score:.3f}] {mem['content']}")

# Response also includes:
# result["count"]   → total corpus size
# result["weights"] → how semantic vs keyword was balanced
# result["facets"]  → tag/metadata distribution
# result["metrics"] → latency breakdown

2. Basic Search (semantic only)

status, result = piy_post("search", {
    "query": "deployment platform",
    "namespace": "my-app",
    "limit": 10,
})
for hit in result["results"]:
    print(f"  [{hit.get('similarity', 0):.3f}] {hit['memory']['content']}")
# Response keys: results, query, count, metrics

3. Fuzzy Search (MCP only — typo-tolerant)

Available through the MCP server's fuzzy_search tool. Uses trigram similarity — great for handling user typos.

Get Context (best for injecting into LLM prompts)

This is the smartest retrieval endpoint. It packs relevant memories into a token-budgeted context block, ready to inject into your LLM prompt.

status, result = piy_post("context/retrieve", {
    "query": "What does the user work with?",
    "namespace": "my-app",
})
# result["content"]         → formatted context string, ready for prompt injection
# result["tokenCount"]      → how many tokens the context uses
# result["user_profile"]    → auto-built user profile from stored memories
# result["header"]          → metadata about the retrieval
# result["scoring_reasons"] → why each memory was selected

# Inject into your LLM prompt:
context = result["content"]
prompt = f"""You are a helpful assistant. Use this context about the user:

{context}

User question: How should I set up my project?"""

[!TIP] Use context/retrieve instead of /ask. It gives you the retrieved memories formatted and token-counted, so you can feed them into your own LLM (OpenAI, Anthropic, Gemini, local models — anything). The /ask endpoint runs our built-in RAG pipeline which costs us compute. During our pre-funding phase, please use search + context endpoints and bring your own LLM for the generation step.

List memories

status, result = piy_get("memories?namespace=my-app&limit=20")
for mem in result["memories"]:
    print(f"  [{mem['id'][:12]}] {mem['content'][:80]}")

Delete a memory

memory_id = "2a11b4c6-8049-4071-aaea-237dd5cd5c7f"
req = urllib.request.Request(
    f"{BASE}/memories/{memory_id}",
    headers=HEADERS,
    method="DELETE",
)
with urllib.request.urlopen(req, timeout=30) as r:
    print(r.status)  # → 200

Path B — REST API (JavaScript / TypeScript)

const API_KEY = process.env.PIYAPI_API_KEY;
const BASE = "https://api.piyapi.cloud/api/v1";

async function piy(method, endpoint, body) {
  const res = await fetch(`${BASE}/${endpoint}`, {
    method,
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    ...(body && { body: JSON.stringify(body) }),
  });
  return { status: res.status, data: await res.json() };
}

// Store
const { data } = await piy("POST", "memories", {
  content: "User prefers dark mode and works with React.",
  namespace: "my-app",
});
console.log("Stored:", data.memory.id);

// Hybrid Search (free)
const search = await piy("POST", "search/hybrid", {
  query: "frontend preferences",
  namespace: "my-app",
  limit: 10,
});
search.data.results.forEach(hit => {
  console.log(`  [${hit.similarity?.toFixed(3)}] ${hit.memory.content}`);
});

// Context Retrieval (free — best for LLM injection)
const ctx = await piy("POST", "context/retrieve", {
  query: "What does the user prefer?",
  namespace: "my-app",
});
console.log("Tokens used:", ctx.data.tokenCount);
console.log("Context:", ctx.data.content);
// → Pass ctx.data.content into your own LLM prompt

Path C — MCP (Claude Desktop / Cursor / Windsurf / VS Code)

Zero code. 2 minutes. 30 tools.

Add to your MCP config:

{
  "mcpServers": {
    "piyapi": {
      "command": "npx",
      "args": ["-y", "@piyapi/mcp-server"],
      "env": {
        "PIYAPI_API_KEY": "sk_live_your_key_here"
      }
    }
  }
}

Restart the client. Your AI now has 30 memory tools:

Memory: store_memory, get_memory, update_memory, delete_memory, list_memories, batch_create, pin_memory Search (free): search_memories (hybrid), fuzzy_search (typo-tolerant) Context: get_context (token-budgeted), get_conversation (history) Knowledge Graph: kg_ingest, kg_search, kg_entities, kg_stats, kg_time_travel Graph: get_graph, graph_traverse, create_relationship, delete_relationship, get_clusters Other: ask_memory (RAG), deduplicate, version_history, rollback_memory, feedback_positive, feedback_negative, check_phi, export_all, create_context_session

[!IMPORTANT] Prefer search_memories and get_context over ask_memory. The search and context tools are free and return raw results you can feed into any LLM. ask_memory runs a full RAG pipeline on our servers which costs compute.

Complete API Reference (Verified)

Endpoints that work ✅

Endpoints that DON'T exist (don't try these)

Recommended Pattern: Search + Your Own LLM

The most cost-effective way to use PiyAPI:

import json, os, urllib.request

API_KEY = os.environ["PIYAPI_API_KEY"]
BASE = "https://api.piyapi.cloud/api/v1"
HDR = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def piy_post(ep, payload):
    req = urllib.request.Request(f"{BASE}/{ep}", json.dumps(payload).encode(), HDR, method="POST")
    with urllib.request.urlopen(req, timeout=30) as r:
        return json.loads(r.read())

# 1. Get context (free)
ctx = piy_post("context/retrieve", {
    "query": user_question,
    "namespace": "my-app",
})

# 2. Feed into YOUR LLM (OpenAI, Anthropic, Gemini, local — anything)
import openai
client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": f"Use this context:\n\n{ctx['content']}"},
        {"role": "user", "content": user_question},
    ],
)
print(response.choices[0].message.content)

This pattern:

• ✅ Uses PiyAPI for what it's best at (storage, indexing, retrieval)
• ✅ Uses your own LLM for generation (you control cost and model)
• ✅ Costs zero PiyAPI compute
• ✅ Works with any LLM provider or local model

Namespaces

Use namespaces to isolate data per user, project, or tenant:

# Per-user isolation
piy_post("memories", {"content": "...", "namespace": "user-alice"})
piy_post("memories", {"content": "...", "namespace": "user-bob"})

# Search only Alice's memories
piy_post("search/hybrid", {"query": "...", "namespace": "user-alice"})

Namespaces are just strings. Use hyphens, not underscores (e.g. my-app not my_app).

Troubleshooting

SSL/TLS errors (Docker or sandboxed environments)

# Fix DNS in Docker
docker run --dns 8.8.8.8 your-image

# Fix TLS in Python
pip install certifi

import ssl, certifi
ctx = ssl.create_default_context(cafile=certifi.where())
# Pass ctx to urllib.request.urlopen(..., context=ctx)

Or use MCP — it runs on your host machine and communicates with the agent over stdio, bypassing sandbox networking entirely.

401 Authentication Error

• Check that PIYAPI_API_KEY is set
• Make sure the key starts with sk_live_
• Verify at: curl -H "Authorization: Bearer $PIYAPI_API_KEY" https://api.piyapi.cloud/api/v1

Rate limiting (429)

import time, urllib.error

try:
    response = urllib.request.urlopen(req, timeout=30)
except urllib.error.HTTPError as e:
    if e.code == 429:
        wait = float(e.headers.get("Retry-After", 2))
        time.sleep(wait)
        # retry

Quick Copy-Paste Starter

Save as piyapi_quickstart.py:

#!/usr/bin/env python3
"""PiyAPI Quickstart — store, search, retrieve context. Zero dependencies."""

import json, os, urllib.request

API_KEY = os.environ["PIYAPI_API_KEY"]
BASE = "https://api.piyapi.cloud/api/v1"
HDR = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def post(ep, body):
    req = urllib.request.Request(f"{BASE}/{ep}", json.dumps(body).encode(), HDR, method="POST")
    with urllib.request.urlopen(req, timeout=30) as r:
        return r.status, json.loads(r.read())

# 1. Store
s, r = post("memories", {"content": "User likes React and dark mode", "namespace": "demo"})
print(f"Stored: {r['memory']['id']}")

# 2. Hybrid Search (free)
import time; time.sleep(2)  # wait for indexing
s, r = post("search/hybrid", {"query": "frontend preference", "namespace": "demo", "limit": 5})
print(f"\nSearch results ({len(r['results'])} found):")
for hit in r["results"]:
    print(f"  [{hit.get('similarity',0):.3f}] {hit['memory']['content']}")

# 3. Context Retrieval (free — best for LLM injection)
s, r = post("context/retrieve", {"query": "What does the user prefer?", "namespace": "demo"})
print(f"\nContext ({r['tokenCount']} tokens):")
print(r["content"][:500])

export PIYAPI_API_KEY="sk_live_..."
python3 piyapi_quickstart.py

That's it. No SDK, no dependencies, no config files. Just HTTP.

Contributors

View the project on GitHub

License

Apache 2.0 © Negentro

PiyAPI by Negentro — Giving AI Agents a True Persistent Mind.