Tài liệu MemoryAI

Cài một lần. Bộ não của anh em chạy mãi mãi. Hướng dẫn đầy đủ cho mọi IDE, mọi ngôn ngữ.

Cài extension cho gọn — khỏi paste config thủ công

Kiro · Cursor · Windsurf · VS Code. Paste API key vào, xong. Extension tự ghi MCP server, hooks và rules cho anh em.

VS Marketplace Open VSX

Hoặc CLI: code --install-extension memoryai.memoryai-vsx · rồi chạy MemoryAI: Connect trong command palette.

— hoặc đọc hướng dẫn cài thủ công bên dưới (Claude Code / Antigravity / bot integrations) —

Cài 3 phút

Copycurl -X POST https://memoryai.dev/v1/admin/provision \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "tos_accepted": true}'

Copynpx memoryai-mcp@latest

Lấy API key

Có 3 cách:

Cách 1: Demo page (dễ nhất)

Vào /demo.html, bấm "Tạo brain miễn phí". Key tự lưu vào localStorage của browser. Dùng được luôn cho demo.

Cách 2: API call

Copycurl -X POST https://memoryai.dev/v1/admin/provision \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "tos_accepted": true,
    "email": "[email protected]"
  }'

Response:

{
  "tenant_id": "...",
  "api_key": "hm_sk_...",
  "plan": "personal",
  "trial_pro_until": "2026-06-12T00:00:00Z"
}

Cách 3: Đăng ký + thanh toán

Xem bảng giá. Hỗ trợ VNPay, MoMo, chuyển khoản, hoá đơn VAT đầy đủ.

Cài theo IDE

Cấu trúc config giống nhau cho mọi IDE — chỉ khác đường dẫn file. Chọn IDE của anh em:

Copynpx memoryai-claude install

Copynpx memoryai-claude doctor     # check hooks + ping server
npx memoryai-claude status     # xem scope (user/project)
npx memoryai-claude uninstall  # gỡ hooks, không xóa data

Copynpx memoryai-claude config                       # xem ngưỡng hiện tại
npx memoryai-claude config compact 180000        # đổi soft warning thành 180K
npx memoryai-claude config critical 250000       # đổi hard ceiling thành 250K
npx memoryai-claude config compact reset         # gỡ override, về mặc định 150K
npx memoryai-claude config critical reset        # gỡ override, về mặc định 200K
npx memoryai-claude config reset                 # gỡ cả 2 → về defaults

Copy{
  "mcpServers": {
    "memoryai": {
      "command": "npx",
      "args": ["-y", "memoryai-mcp"],
      "env": {
        "HM_ENDPOINT": "https://memoryai.dev",
        "HM_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Copy{
  "mcpServers": {
    "memoryai": {
      "command": "npx",
      "args": ["-y", "memoryai-mcp"],
      "env": {
        "HM_ENDPOINT": "https://memoryai.dev",
        "HM_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Copy{
  "mcpServers": {
    "memoryai": {
      "command": "npx",
      "args": ["-y", "memoryai-mcp"],
      "env": {
        "HM_ENDPOINT": "https://memoryai.dev",
        "HM_API_KEY": "YOUR_KEY"
      },
      "disabled": false,
      "autoApprove": [
        "memory_bootstrap", "memory_recall", "memory_store",
        "context_guard_check", "context_guard_compact",
        "memory_pitfall_check", "l2_inject"
      ]
    }
  }
}

Copy{
  "mcpServers": {
    "memoryai": {
      "command": "npx",
      "args": ["-y", "memoryai-mcp"],
      "env": {
        "HM_ENDPOINT": "https://memoryai.dev",
        "HM_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Copy{
  "servers": {
    "memoryai": {
      "command": "npx",
      "args": ["-y", "memoryai-mcp"],
      "env": {
        "HM_ENDPOINT": "https://memoryai.dev",
        "HM_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Copy{
  "mcpServers": {
    "memoryai": {
      "command": "npx",
      "args": ["-y", "memoryai-mcp"],
      "env": {
        "HM_ENDPOINT": "https://memoryai.dev",
        "HM_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Copy{
  "mcpServers": {
    "memoryai": {
      "command": "npx",
      "args": ["-y", "memoryai-mcp"],
      "env": {
        "HM_ENDPOINT": "https://memoryai.dev",
        "HM_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Auto-bootstrap rule

Sau khi cài MCP, anh em cần một file rule để AI tự gọi memory mỗi lần mở session. Mỗi IDE có kiểu rule khác nhau, nhưng nội dung giống hệt:

Cách 1: Một dòng curl (nhanh nhất)

Copy# Claude Code
curl -s https://memoryai.dev/install/SKILL.md > ~/.claude/CLAUDE.md

# Cursor (Linux/macOS)
mkdir -p .cursor/rules && curl -s https://memoryai.dev/install/SKILL.md > .cursor/rules/memoryai.mdc

# Kiro
mkdir -p .kiro/steering && curl -s https://memoryai.dev/install/SKILL.md > .kiro/steering/memoryai.md

Cách 2: Copy-paste manual

Copy nội dung dưới đây, dán vào file rule tương ứng:

Copy# MemoryAI — Auto Memory + Context Guard

Bạn có MemoryAI — bộ não persistent nhớ qua mọi session.
Mọi thứ dưới đây là TỰ ĐỘNG. Tuân theo mỗi session.

## 1. Session start (LUÔN LUÔN làm đầu tiên)

Gọi `memory_bootstrap` ngay khi user gửi tin nhắn đầu tiên. Trả về:
- User identity + preferences (DNA-protected)
- Recent activity 24h
- Active goals
- Mood + persona

KHÔNG hỏi user lặp lại context cũ.

## 2. Trong session — auto-store (không cần hỏi)

| Khi nào | Tool | memory_type |
|---|---|---|
| User nói preference ("tao thích...") | memory_store | preference |
| Quyết định được chốt | memory_store | decision |
| User chia sẻ identity (role, công ty) | memory_store | identity |
| Fact quan trọng học được | memory_store | fact |
| Workflow chạy ổn định | memory_store | procedure |
| Lỗi cần tránh lần sau | memory_store | pitfall |

KHÔNG store: "ok", "thanks", debug output, thứ đã có trong code/git.

## 3. Recall TRƯỚC KHI làm

- Trước đề xuất kiến trúc → memory_recall trước
- User nói "you did this before" → memory_recall ngay, đừng đoán
- Trước action rủi ro (deploy, rm, push, migrate) → memory_pitfall_check

## 4. Context Guard (mỗi 15 messages)

Gọi context_guard_check với:
{"estimated_tokens": current_count, "max_tokens": model_window}

Response:
- safe → tiếp tục
- compact_soon → chuẩn bị summarize
- compact_now → gọi context_guard_compact NGAY với summary đầy đủ

## 5. Smart Context Inject — cho deep context

Khi cần composed context block trong budget:
l2_inject {query, context_budget_tokens: 2000}
→ Trả về DNA + decisions + facts + recent đã merge sẵn. Cache 10 phút.

## 6. Important

- Nếu MemoryAI down → tiếp tục bình thường (non-fatal)
- preferences/decisions/identity là DNA — không bao giờ expire
- Facts thường fade theo thời gian nếu không dùng

## Quick MCP tools

| Tool | Khi nào |
|---|---|
| memory_bootstrap | Session start |
| memory_recall | Cần context cũ |
| memory_store | Save preference/decision/identity/fact/pitfall |
| memory_pitfall_check | Trước action rủi ro |
| context_guard_check | Mỗi 15 messages |
| context_guard_compact | Context full |
| l2_inject | Cần composed context block |
| memory_changelog | Catch up sau khi away

Python SDK

Copypip install hmc-memory

Quick example

Copyfrom memoryai import AsyncMemoryAI

async with AsyncMemoryAI(
    api_key="hm_sk_...",
    base_url="https://memoryai.dev"
) as mem:
    # Session start — load brain context
    ctx = await mem.bootstrap(task="building chatbot")

    # Store memory
    await mem.store(
        "User prefers Vietnamese for casual, English for code",
        memory_type="preference",
        zone="important"
    )

    # Recall (semantic + graph + FTS fusion)
    results = await mem.recall(
        "what language does user prefer?",
        depth="deep",
        limit=5
    )

    # Context guard
    guard = await mem.ide_guard_check(
        estimated_tokens=85000,
        max_tokens=200000
    )
    if guard.get("should_compact"):
        await mem.ide_guard_compact(
            content="conversation summary...",
            task_context="chat session"
        )

    # Smart context inject — composed context block in budget
    l2 = await mem.l2_inject(
        query="user preferences for stack",
        context_budget_tokens=2000
    )
    # l2["composed_context"] → paste into your prompt

Sync version

from memoryai import MemoryAI

mem = MemoryAI(api_key="hm_sk_...", base_url="https://memoryai.dev")
ctx = mem.bootstrap(task="my task")
results = mem.recall("query")
mem.close()

Node.js SDK

Copynpm install @cortex-memory/memoryai

Copyimport { MemoryAI } from '@cortex-memory/memoryai';

const mem = new MemoryAI({
  apiKey: 'hm_sk_...',
  baseUrl: 'https://memoryai.dev'
});

// Session start
const ctx = await mem.bootstrap({ task: 'my project' });

// Store
await mem.store('User prefers dark mode', {
  memoryType: 'preference',
  zone: 'important'
});

// Recall
const results = await mem.recall('user preferences', {
  depth: 'deep',
  limit: 5
});

// Context Guard
const guard = await mem.ideGuardCheck({
  estimatedTokens: 85000,
  maxTokens: 200000
});

if (guard.should_compact) {
  await mem.ideGuardCompact({
    content: summarizeConversation(messages),
    taskContext: 'current task'
  });
}

// Smart Context Inject
const l2 = await mem.l2Inject({
  query: 'user stack preferences',
  contextBudgetTokens: 2000
});
console.log(l2.composed_context);

OpenAI Proxy

Dùng MemoryAI như drop-in replacement cho OpenAI API. Tự động inject memory vào mỗi request.

Copyfrom openai import OpenAI

# Chỉ cần đổi base_url + thêm header
client = OpenAI(
    api_key="hm_sk_...",
    base_url="https://memoryai.dev/v1/openai-proxy",
    default_headers={"X-Memory-Inject": "true"}
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "what was my last decision?"}]
)
# Response sẽ có context được inject từ brain

REST API

Mọi tính năng đều có REST endpoint. Dùng curl, Postman, hoặc bất kỳ HTTP client nào.

Base URL + Auth

Base: https://memoryai.dev
Auth: Authorization: Bearer hm_sk_...

Store memory

Copycurl -X POST https://memoryai.dev/v1/store \
  -H "Authorization: Bearer hm_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User thích cà phê đen không đường",
    "memory_type": "preference",
    "zone": "important",
    "tags": ["coffee", "preference"]
  }'

Recall

Copycurl -X POST https://memoryai.dev/v1/recall \
  -H "Authorization: Bearer hm_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "user prefer drink",
    "depth": "deep",
    "limit": 5,
    "language": "auto"
  }'

language: "auto" — server tự detect tiếng Việt vs English (96% chính xác cho VN, 100% cho EN). Tiếng Việt được match qua Vietnamese FTS dictionary tự build.

Smart Context Inject

Copycurl -X POST https://memoryai.dev/v1/l2/inject \
  -H "Authorization: Bearer hm_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what does user need for current task",
    "context_budget_tokens": 2000
  }'

Response có composed_context dán thẳng vào prompt.

Brain Export

Copycurl -X POST https://memoryai.dev/v1/brain/export \
  -H "Authorization: Bearer hm_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"scope": "full"}' \
  -o brain-bundle.json

JSON bundle theo Bundle Format v1 (CC BY 4.0). Anh em download, sau này import vào server self-host (lite-build) hoặc bất kỳ implementation nào tuân Protocol v1.

Public stats (no auth)

curl https://memoryai.dev/v1/internal-stats
curl https://memoryai.dev/v1/spec/info
curl https://memoryai.dev/v1/benchmark/pricing

Endpoints public, không cần auth. Dùng để monitor hệ thống hoặc embed live numbers vào landing page.

Đầy đủ API: /redoc · OpenAPI spec: /openapi.json

Context Guard

Context Guard tự bảo vệ session khỏi context overflow. Khi window đầy, AI tự compact conversation về brain — không mất data, không cần anh em can thiệp.

Ngưỡng mặc định

Preset gợi ý

API: check + compact

CopyPOST /v1/ide/guard/check
Authorization: Bearer YOUR_KEY

{
  "estimated_tokens": 100000,
  "max_tokens": 200000,
  "compact_pct": 0.20,
  "critical_pct": 0.30
}

Response:

{
  "recommendation": "compact_now",
  "urgency": "high",
  "should_compact": true,
  "usage_percent": 50.0,
  "dna_memories": 12,
  "bootstrap_ready": true
}

Compact

CopyPOST /v1/ide/guard/compact

{
  "content": "Summary đầy đủ: thảo luận pricing Kiro, chốt 2K plan giá $20/acc, margin 92.7%, Gemini 1.5 cho L1, Claude cho L2...",
  "task_context": "pricing decision"
}

Tuỳ chỉnh per-tenant

v2.3.2+ dùng token tuyệt đối, không phải %. Anh em pick ngưỡng theo cost ceiling muốn giam:

Copy# Set absolute thresholds via per-request override
curl -X POST https://memoryai.dev/v1/ide/guard/turn-check \
  -H "Authorization: Bearer hm_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"turn_count": 30, "compact_at_tokens": 100000, "critical_at_tokens": 150000}'

Hoặc set qua MCP env:

"env": {
  "HM_COMPACT_AT": "100000",
  "HM_CRITICAL_AT": "150000"
}

Pick ngưỡng theo cost ceiling muốn giam — nó áp dụng đồng đều cho mọi model, không phụ thuộc model window. Tăng số lên cho session dài hơn (vd 400K/600K trên model 1M).

Priority: per-request override > env vars > server defaults.

Smart Context Inject

Khi anh em cần composed context block trong budget — DNA + decisions + facts + recent đã merge sẵn — gọi endpoint này. Server tự chọn relevant nhất, fit budget tokens, paste thẳng vào prompt của top model.

API

CopyPOST /v1/l2/inject

{
  "query": "what should I do for current task",
  "context_budget_tokens": 2000,
  "include_dna": true,
  "include_recent": true
}

Response:

{
  "composed_context": "## DNA\n- ...\n## Recent Decisions\n- ...\n## Insights\n- ...",
  "tokens_used": 1847,
  "components": ["dna:5", "decisions:3", "facts:8", "recent:4"],
  "cache_hit": false,
  "latency_ms": 142
}

Cách dùng

Paste composed_context thẳng vào system prompt hoặc đầu user message. AI nhận được context đã được pre-compose, không phải raw dump.

Brain Export — Vendor Sovereignty

DNA #3: Brain thuộc về user, không phải vendor. Anh em export brain ra JSON bundle bất kỳ lúc nào, import vào server self-host hoặc implementation khác tuân Protocol v1.

Export

Copycurl -X POST https://memoryai.dev/v1/brain/export \
  -H "Authorization: Bearer hm_sk_..." \
  -d '{"scope": "full"}' \
  -o brain-bundle.json

Scope options:

• full — toàn bộ chunks + edges + entities + sessions + mood (mặc định)
• dna_only — chỉ preferences/decisions/identity (lightweight identity portable)
• since — incremental, cần thêm "since": "2026-05-01T00:00:00Z"

Bundle Format v1

{
  "format": "memoryai-bundle",
  "version": "1.0",
  "manifest": {
    "exported_at": "2026-05-29T...",
    "tenant_hash": "...",
    "checksum_sha256": "..."
  },
  "chunks": [...],
  "edges": [...],
  "entities": [...],
  "sessions": [...],
  "embedding_model": "text-embedding-3-small"
}

Import vào instance khác

Copycurl -X POST https://your-instance.com/v1/brain/import \
  -H "Authorization: Bearer NEW_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @brain-bundle.json

Idempotent — chunks dedup theo content_hash. Embeddings reused nếu model match, drop nếu khác (re-embed lazily).

31 MCP Tools

Đầy đủ tools available qua MCP — gọi từ Claude Code, Cursor, Kiro, Windsurf, hoặc bất kỳ MCP client nào.

Core (mỗi session đều dùng)

Context Guard

Smart Context

Brain ownership (DNA #3)

Multi-agent (DNA #1)

Insights + benchmark

Cách hoạt động

Anh em không cần đọc phần này để dùng. Đọc nếu muốn hiểu sao memory persist được, sao recall ra đúng thứ cần.

Cách brain tổ chức memory

Recent memory
       Conversations, raw chunks, fresh decisions
       Searched via hybrid recall

Distilled memory
       Patterns and summaries auto-built in the background
       Returns near-instant on repeat queries

Long-term archive
       Compressed sessions, DNA preserved forever
       Bootstrap pulls "who is the user" on demand

Flow một session bình thường

Open IDE
  → MCP auto-connects
  → AI reads rule → calls memory_bootstrap
  → Loads: DNA + recent activity + preferences + entities + persona
  → AI biết bạn là ai và đang làm gì

Trong session:
  → AI auto-stores quyết định + preferences quan trọng
  → Memories tagged + embedded + linked vào graph
  → Smart fusion 4 nguồn cho recall

Context đầy:
  → AI gọi context_guard_check → "compact_now"
  → AI gọi context_guard_compact → save session về brain
  → Mọi thứ preserved

Background (24/7, không cần user):
  → Sleep consolidation (LLM phân tích insights overnight)
  → association strengthening (memories co-recalled gắn chặt hơn)
  → Decay (memories không dùng fade dần)
  → Community detection (tìm topic clusters)
  → DNA-protected memories KHÔNG bao giờ expire

Session sau:
  → memory_bootstrap load lại tất cả
  → Bao gồm insights mới từ overnight consolidation
  → Cycle tiếp tục. Brain càng dùng càng smart hơn.

Recall fusion

Khi anh em gọi memory_recall, server merge nhiều nguồn thành một bảng xếp hạng:

• Vector similarity (semantic — meaning match)
• Full-text search (lexical — exact word match, có Vietnamese tokenizer)
• Neural graph traversal (memories liên quan)
• Recency boost + DNA priority boost

Có 4 depth modes:

Brain hoạt động như thế nào

MemoryAI mô phỏng cơ chế bộ não thật:

• Encoding — chuyển input thành memory chunk có embedding + tags
• Consolidation — định kỳ trích insight từ raw chunks lúc rảnh
• Natural fade — memories không dùng phai dần
• DNA protection — preferences / decisions / identity / pitfalls / procedures không bao giờ expire
• Association linking — memories co-recalled gắn chặt hơn qua edges
• Spreading activation — recall lan toả qua graph
• Mood tracking — adapt response style theo trạng thái user
• Community detection — auto-cluster topics
• Pattern extraction — tìm recurring themes
• Self-model — persona + goals + entities + procedures

Khắc phục lỗi

Debug tips

• Check connection: curl https://memoryai.dev/v1/health
• Check key: curl -H "Authorization: Bearer YOUR_KEY" https://memoryai.dev/v1/admin/whoami
• Check usage: curl -H "Authorization: Bearer YOUR_KEY" https://memoryai.dev/v1/admin/usage
• Check MCP version: npx memoryai-mcp --version
• Force update MCP: npm install -g memoryai-mcp@latest

MemoryAI Protocol v1

Protocol v1 là spec mở (CC BY 4.0) — anyone có thể implement. Reference implementation MIT-licensed.

3 conformance levels

Public spec endpoints (no auth)

Đầy đủ: memoryai.dev/spec/v1

Hỏi đáp

Brain của tôi thuộc về ai?

Của anh em. Brain Export trả về JSON bundle vendor-neutral — anh em download bất kỳ lúc nào, import vào server self-host (lite-build) hoặc bất kỳ implementation nào tuân Protocol v1. Đây là DNA #3, không thương lượng.

Có lock-in không?

Không. Brain Export = JSON spec mở (CC BY 4.0). MCP package open source. SDK mã nguồn mở. Server code self-hostable (Q3 2027 ra lite-build). Lock-in chỉ xảy ra khi vendor giữ format proprietary — MemoryAI không làm vậy.

Trial Pro 14 ngày tự renew không?

Không. Hết 14 ngày, tự về plan Personal (free). Anh em không bị charge bất ngờ. Nếu muốn nâng cấp, vào pricing-vn chọn plan, thanh toán qua VNPay/MoMo/chuyển khoản.

Có hỗ trợ tiếng Việt thật sự không?

Có. MemoryAI có Vietnamese FTS dictionary tự build (PostgreSQL vietnamese_simple dict). Test detection: 96% chính xác cho VN, 100% cho EN. Recall query tiếng Việt match content tiếng Việt qua semantic + lexical fusion.

Server đặt ở đâu? Data ở đâu?

Server primary: VN. Data tuân VN PDPA Decree 13/2023, full DSR support qua public API (export/forget/delete). Privacy-preserving audit log (sha256 hashing). SOC 2 Type II observation period bắt đầu 29/05/2026, certified Q1 2028.

Một brain dùng được nhiều agent không?

Có. DNA #1: One brain. ∞ agents. Forever. Plan Personal trở lên unlimited agents/tenant. Một API key chia cho 10-50 AI agents khác nhau (chat, code, doctor, lawyer, robot — tương lai). Tất cả share một brain.

Khi tôi chết, brain đi đâu?

Theo will của anh em. Plan Pro+ có inheritance feature — designate người kế thừa brain. Person đó nhận access qua brain_export bundle. Đây là DNA #1 ở scale lifetime.

Khác vector store / RAG ở đâu?

MemoryAI hành xử như cortex thật: DNA-protected memory không phai, memory không dùng tự fade, association tự strengthen, brain tự consolidation. Trong khi vector store chỉ là database. Tự test trên brain của bạn tại /demo.html.

Tôi muốn self-host?

Lite-build sẽ có Q3 2027 (sau khi go-world). Hiện tại Enterprise plan unlock self-host docker compose. Liên hệ [email protected].

API rate limit như nào?

Vượt rate limit → 429 với Retry-After header. Không charge thêm — chỉ throttle.

Tôi gặp bug?

• GitHub issues: github.com/CH270035/memoryai/issues
• Email: [email protected]
• Telegram (founder): @tonyadam01