MemoryZ v2 Architecture
Living Substrate
دليل التكامل وطرق الارتباط الشاملة
يوفر MemoryZ v2 أرضية ذاكرة حيّة وتنسيق مهام فائق الاقتصاد في التوكن لوكلاء الذكاء الاصطناعي والمطورين. يمكنك ربطه بأربع طرق مرنة وقوية:
1. بروتوكول MCP
Cursor & Claude Desktop
2. الكود والـ SDK
NPM & Node & Python
3. عبر الوكيل (Agent)
AGENTS.md وقواعد السياق
4. عبر المهارة (Skill)
skill.md لوكلاء الذكاء
1. الارتباط عبر بروتوكول MCP (Model Context Protocol)
توصيل MemoryZ مباشرة مع بيئات التطوير الذكية مثل Cursor و Claude Code و Windsurf و Claude Desktop.
أ. التثبيت والتسجيل التلقائي بنقرة واحدة (موصى به)
يقوم أمر npx memoryz init باكتشاف محرراتك تلقائياً وإضافتها لملفات الإعدادات:
npx memoryz init --token=YOUR_API_TOKENب. التكوين اليدوي عبر ملفات JSON (Cursor / Claude Desktop / Windsurf)
في ملف .cursor/mcp.json أو claude_desktop_config.json:
{
"mcpServers": {
"memoryz": {
"command": "npx",
"args": ["-y", "memoryz", "mcp"],
"env": {
"MEMORYZ_URL": "https://memoryz.wino.deno.net",
"MEMORYZ_TOKEN": "YOUR_API_KEY_HERE"
}
}
}
}ج. رابط MCP Remote المباشر (SSE Transport)
يدعم السيرفر بروتوكول SSE مباشر بدون تثبيت Node.js محلياً:
https://memoryz.wino.deno.net/sse
2. الارتباط عبر الكود والـ SDK (Node.js & Python & Shell)
استدعاء الذاكرة والمهام والخزنة برمجياً من تطبيقاتك وسكربتاتك المستقلة.
npm i memoryz
Python SDK
حزمة Node.js / TypeScript:
npm install memoryz// كود الاستدعاء داخل تطبيقك:import { MemoryzClient } from 'memoryz';
const mz = new MemoryzClient({
url: 'https://memoryz.wino.deno.net',
token: process.env.MEMORYZ_TOKEN
});
// 1. استرجاع دلالي مقتصد للتوكن
const memories = await mz.recall('Database schema and rules', { compact: true });
// 2. إدارة المهام الشجرية
const task = await mz.createTask({
title: 'Optimize Vector Query',
priority: 'high'
});
// 3. تخزين لوغ لحظي سريع بدون أعباء الفيكتور
await mz.log('Worker executed synchronization in 24ms');عميل Python الخفيف (Single-File SDK):
يمكنك تحميل memoryz.py مباشرة بدون أي اعتماديات خارجية (Zero-Dependency):
curl -sO https://memoryz.wino.deno.net/memoryz.pyfrom memoryz import MemoryzClientclient = MemoryzClient(token="YOUR_TOKEN")
print(client.recall("project guidelines", compact=True))3. الارتباط من خلال الوكيل الذكي (Autonomous AI Agent Substrate)
إدراج قواعد الذاكرة والمهام في ملفات التوجيه الذاتي للوكيل (AGENTS.md أو CLAUDE.md).
ضع التوجيهات التالية في ملف AGENTS.md في جذر مشروعك ليقوم أي وكيل (Claude Code, Antigravity, Cursor Agent) بالرجوع تلقائياً لذاكرة المشروع وتحديث المهام دون استهلاك سياق المحادثة:
# Project Agent Rules — MemoryZ Substrate
This project connects to MemoryZ v2 (memoryz.wino.deno.net):
- Token-Saving Recall: Use `memoryz recall "" --compact`
- Prompt Context Pack: Use `memoryz context ""` to get active tasks & rules
- Hierarchical Tasks / TODOs:
- View task tree: `memoryz task list --tree`
- Add task or subtask: `memoryz task add "" [--parent=<id>]`
- Mark completed: `memoryz task done <id>`
- Update status: `memoryz task update <id> --status=<todo|in_progress|done>`
- Ephemeral Logs: Use `memoryz log "<message>"` for fast execution traces
- Persistent Rules: Use `memoryz store --type=preference|env|skill|note --content="..."`</code></pre>
<button class="btn btn-ghost btn-xs absolute left-3 top-3 text-base-content/60 hover:text-base-content"
@click="copyText(agentsMdSnippet)">
<i class="fa-solid fa-copy"></i>
</button>
</div>
</div>
</section>
<!-- ============================================================= -->
<!-- SECTION 4: SKILL FILE INTEGRATION (SKILL.MD) -->
<!-- ============================================================= -->
<section id="skill" class="card bg-base-200/70 border border-base-300 p-5 sm:p-7 rounded-2xl shadow-sm flex flex-col gap-4">
<div class="flex items-center justify-between flex-wrap gap-2 pb-3 border-b border-base-300">
<div class="flex items-center gap-3">
<div class="w-9 h-9 rounded-xl bg-accent/20 text-accent flex items-center justify-center font-black">
<i class="fa-solid fa-scroll"></i>
</div>
<div>
<h2 class="text-lg sm:text-xl font-black">4. الارتباط عبر ملف المهارة (Skill File — skill.md)</h2>
<p class="text-xs text-base-content/70">تزويد الوكلاء كمهارة مستقلة قابلة للتحميل والاستدعاء المباشر.</p>
</div>
</div>
<span class="badge badge-accent badge-sm font-mono">No Token Leakage</span>
</div>
<div class="space-y-4 text-sm leading-relaxed">
<div class="alert alert-warning/15 border border-warning/30 text-xs py-2.5 px-4 rounded-xl flex items-center gap-2.5">
<i class="fa-solid fa-shield-halved text-warning text-sm flex-none"></i>
<span>
<strong>تأكيد الأمان والخصوصية:</strong> ملف <code class="mono bg-base-300 px-1 py-0.5 rounded">skill.md</code> عام وخالٍ تماماً من أي مفاتيح سرية أو Auth Tokens، ويعتمد على أوامر الـ CLI وبيئة الوكيل لحماية بياناتك.
</span>
</div>
<div class="flex flex-col sm:flex-row items-stretch sm:items-center gap-3 bg-base-300/60 p-4 rounded-xl border border-base-300">
<div class="flex-1 min-w-0">
<div class="font-bold text-xs sm:text-sm">رابط تحميل ملف المهارة المباشر:</div>
<div class="mono text-xs text-primary truncate">https://memoryz.wino.deno.net/skill.md</div>
</div>
<div class="flex items-center gap-2 flex-none">
<a href="/skill.md?download=true" class="btn btn-accent btn-sm gap-1">
<i class="fa-solid fa-download text-xs"></i> <span>تحميل skill.md</span>
</a>
<button class="btn btn-outline btn-sm gap-1" @click="copyText('https://memoryz.wino.deno.net/skill.md')">
<i class="fa-solid fa-copy text-xs"></i> <span>نسخ الرابط</span>
</button>
</div>
</div>
<div>
<h3 class="font-bold text-base mb-1.5 flex items-center gap-2">
<i class="fa-solid fa-folder-tree text-accent text-xs"></i>
كيفية تثبيت المهارة في مشروعك:
</h3>
<p class="text-xs text-base-content/80 mb-2">
الطريقة الموصى بها — عبر نظام المهارات المفتوح (يدعم Claude Code وCursor وCodex وغيرها):
</p>
<div class="mockup-code text-xs bg-base-300 border border-base-content/10 shadow relative mb-3">
<pre data-prefix="$"><code>npx skills add https://memoryz.wino.deno.net</code></pre>
<button class="btn btn-ghost btn-xs absolute left-3 top-3 text-base-content/60 hover:text-base-content"
@click="copyText('npx skills add https://memoryz.wino.deno.net')">
<i class="fa-solid fa-copy"></i>
</button>
</div>
<p class="text-xs text-base-content/80 mb-2">
أو نزّل الملف مباشرة إلى مجلد مهارات الوكيل (Skills Directory) بأمر واحد في الطرفية:
</p>
<div class="mockup-code text-xs bg-base-300 border border-base-content/10 shadow relative">
<pre data-prefix="$"><code>mkdir -p .agents/skills/memoryz && curl -sSL https://memoryz.wino.deno.net/skill.md > .agents/skills/memoryz/SKILL.md</code></pre>
<button class="btn btn-ghost btn-xs absolute left-3 top-3 text-base-content/60 hover:text-base-content"
@click="copyText('mkdir -p .agents/skills/memoryz && curl -sSL https://memoryz.wino.deno.net/skill.md > .agents/skills/memoryz/SKILL.md')">
<i class="fa-solid fa-copy"></i>
</button>
</div>
</div>
<div>
<h3 class="font-bold text-base mb-1.5 flex items-center gap-2">
<i class="fa-solid fa-file-lines text-accent text-xs"></i>
معاينة محتوى ملف المهارة (SKILL.md):
</h3>
<div class="bg-base-300 p-3.5 rounded-xl border border-base-content/10 text-xs font-mono whitespace-pre-wrap leading-relaxed max-h-72 overflow-y-auto scrollbar-thin">
---
name: memoryz
description: Sovereign agentic memory and hierarchical multi-agent task substrate. Use to recall developer preferences and project rules in token-saving formats, share one memory across several agents with namespace isolation and provenance, coordinate hierarchical tasks with atomic claiming so two agents never duplicate work, log ephemeral traces, and store secrets in an encrypted vault.
---
# MemoryZ v3 — Sovereign Multi-Agent Memory & Task Substrate
MemoryZ is a persistent, cross-session memory substrate and task coordinator that
**several agents can share at once**. Memories are vector-embedded and ranked by
time-decayed recall, so what the team actually uses stays near the top.
Available as a CLI (`memoryz`), an MCP server, and a REST API. The commands below
use the CLI; the MCP tool name is given in parentheses where they differ.
## 1. Recall before you act
Always check for existing rules before starting a task — the developer may have
already told another agent how they want this done.
```
memoryz recall "<task topic>" --compact # (recall_memory) one-liners, token-cheap
memoryz context "<task topic>" # (context_pack) memories + active tasks in one bundle
memoryz get <hash> [--links] # (get_memory) resolve an exact hash another agent cited
```
`recall` reinforces what it returns, so frequently-used memories rise over time.
## 2. Namespaces — keep projects apart
Every memory and task belongs to a `namespace` (default: `default`). Use one
namespace per project so agents working on different repos never see each other's
noise.
```
memoryz recall "deploy steps" --ns=my-project
memoryz task list --ns=my-project
```
Pass `--ns=` on `store`, `recall`, `task add`, and `task list`. Over MCP and REST
the field is `namespace`.
## 3. Provenance — record who wrote it
When you store something, say who you are. Later agents can then tell a human
instruction apart from a guess another agent made.
```
memoryz store --type=preference --content="<rule>" --ns=my-project --agent=<your-name>
```
Sets `agent_id` and `source` on the memory. Over MCP: `agent_id` and `source`.
## 4. Hierarchical tasks & atomic claiming
```
memoryz task list --tree # (task_list) compact ASCII hierarchy
memoryz task add "<title>" [--parent=<id>] [--priority=high] [--assignee=<agent>]
memoryz task claim <id> --agent=<your-name> # (task_claim) lock it to you
memoryz task claim <id> --agent=<your-name> --release
memoryz task update <id> --status=in_progress
memoryz task done <id>
```
**Claim before you start.** `task claim` is atomic: if another agent already holds
the task the command fails and tells you who has it, so two agents never do the
same work. Release when you stop, or mark it done.
A typical handoff: agent A creates a task and stores the context as a memory, then
puts the memory hash in the task description. Agent B claims the task and calls
`memoryz get <hash>` to load exactly the context A meant.
## 5. Storing persistent memory
Store when the developer gives a durable instruction, not for transient state.
```
memoryz store --type=<type> --content="<text>" [--title="..."] [--ns=<project>]
memoryz edit <hash> --content="<corrected text>" # (memory_update) re-embeds
memoryz forget <hash> # (memory_delete) soft delete
```
Types:
- `env` — ports, infrastructure, domains, CLI tool choices
- `preference` — coding habits, architectural patterns, style
- `skill` — multi-step procedures or reusable agent workflows
- `note` — reference facts, URLs, documentation pointers
Correct a wrong memory with `edit` rather than storing a second contradictory one.
## 6. Ephemeral logs
For run traces and low-importance notes. Skips vector embedding, so it is fast and
does not pollute recall.
```
memoryz log "<message>" [--level=info] [--source=<agent>]
memoryz logs --limit=20
```
## 7. Secret vault
Zero-knowledge, AES-256-GCM. Secrets are never embedded or indexed.
```
memoryz vault store --key="<name>" --secret="<val>" --pass="<passphrase>"
memoryz vault get --key="<name>" --pass="<passphrase>"
```
Never put a credential in a regular memory — use the vault.
</div>
</div>
</div>
</section>
</main>
<!-- FOOTER -->
<footer class="footer footer-center p-6 bg-base-200 text-base-content border-t border-base-300 mt-10">
<aside class="flex flex-col items-center gap-2">
<div class="flex items-center gap-2 font-black text-base">
<div class="w-6 h-6 rounded bg-primary text-primary-content flex items-center justify-center text-xs">
<i class="fa-solid fa-brain"></i>
</div>
<span>MemoryZ v2 Documentation</span>
</div>
<p class="text-xs text-base-content/70">
Sovereign Living Memory & Hierarchical Task Substrate for Next-Gen Autonomous AI Agents.
</p>
<div class="flex items-center gap-4 mt-2">
<a href="https://github.com/Zizwar/memoryz" target="_blank" rel="noopener noreferrer" class="link link-hover text-xs flex items-center gap-1">
<i class="fa-brands fa-github"></i> GitHub
</a>
<a href="https://www.npmjs.com/package/memoryz" target="_blank" rel="noopener noreferrer" class="link link-hover text-xs flex items-center gap-1 text-error">
<i class="fa-brands fa-npm"></i> NPM Package
</a>
<a href="/skill.md" class="link link-hover text-xs flex items-center gap-1 text-accent">
<i class="fa-solid fa-scroll"></i> skill.md
</a>
</div>
</aside>
</footer>
<!-- Toast Notification -->
<div class="toast toast-end toast-bottom z-50 pointer-events-none" x-show="toast.show" x-transition>
<div class="alert alert-info py-2 px-4 shadow-lg text-xs font-semibold gap-2">
<i class="fa-solid fa-circle-check text-success"></i>
<span x-text="toast.message"></span>
</div>
</div>
<script>
function docsApp() {
return {
theme: localStorage.getItem('memoryz_theme') || 'dark',
toast: { show: false, message: '' },
mcpJsonConfig: JSON.stringify({
mcpServers: {
memoryz: {
command: "npx",
args: ["-y", "memoryz", "mcp"],
env: {
MEMORYZ_URL: "https://memoryz.wino.deno.net",
MEMORYZ_TOKEN: "YOUR_API_KEY_HERE"
}
}
}
}, null, 2),
nodeCodeSnippet: `import { MemoryzClient } from 'memoryz';
const mz = new MemoryzClient({
url: 'https://memoryz.wino.deno.net',
token: process.env.MEMORYZ_TOKEN
});
// 1. استرجاع دلالي مقتصد للتوكن
const memories = await mz.recall('Database schema and rules', { compact: true });
// 2. إدارة المهام الشجرية
const task = await mz.createTask({
title: 'Optimize Vector Query',
priority: 'high'
});
// 3. تخزين لوغ لحظي سريع بدون أعباء الفيكتور
await mz.log('Worker executed synchronization in 24ms');`,
agentsMdSnippet: `# Project Agent Rules — MemoryZ Substrate
This project connects to MemoryZ v2 (memoryz.wino.deno.net):
- Token-Saving Recall: Use ` + "`memoryz recall \"<query>\" --compact`" + `
- Prompt Context Pack: Use ` + "`memoryz context \"<query>\"`" + ` to get active tasks & rules
- Hierarchical Tasks / TODOs:
- View task tree: ` + "`memoryz task list --tree`" + `
- Add task or subtask: ` + "`memoryz task add \"<title>\" [--parent=<id>]`" + `
- Mark completed: ` + "`memoryz task done <id>`" + `
- Update status: ` + "`memoryz task update <id> --status=<todo|in_progress|done>`" + `
- Ephemeral Logs: Use ` + "`memoryz log \"<message>\"`" + ` for fast execution traces
- Persistent Rules: Use ` + "`memoryz store --type=preference|env|skill|note --content=\"...\"`",
toggleTheme() {
this.theme = this.theme === 'dark' ? 'light' : 'dark';
localStorage.setItem('memoryz_theme', this.theme);
document.documentElement.setAttribute('data-theme', this.theme);
},
async copyText(txt) {
if (!txt) return;
await navigator.clipboard.writeText(txt);
this.toast.message = 'تم النسخ إلى الحافظة بنجاح 📋';
this.toast.show = true;
setTimeout(() => { this.toast.show = false; }, 3000);
}
}
}
</script>
</body>
</html>