التوثيق
الذاكرة
الذاكرة محلية مئة بالمئة: ضمّين BGE-M3 في حاوية مخصصة، والنص في pgvector داخل PostgreSQL خاصتنا. لا شيء يُرسَل لنموذج خارجي. المقيس: hit@1 = 19/25 إجمالًا و8/10 في العامية المصرية (تقييم P2.5).
يخزّن نصًا في ذاكرتك الخاصة. تُزال التكرارات ببصمة النص المطبَّع — إعادة كتابة النص نفسه تحدّثه.
الطلب
| الحقل | النوع | الوصف | |
|---|---|---|---|
items | array | مطلوب | مصفوفة عناصر للتخزين (64 كحد أقصى في الطلب). |
items[].text | string | مطلوب | النص المُراد تذكّره. |
items[].sourceUrl | string | اختياري | عنوان المصدر اختياريًا للإسناد. |
items[].tags | string[] | اختياري | وسوم اختيارية لاسترجاع مُرشّح. |
مثال
curl -X POST https://agw.orcanox.xyz/v1/memory/write \ -H "Authorization: Bearer agw_…" \ -H "Content-Type: application/json" \ -d '{"items":[{"text":"The renewal price is $90/year","sourceUrl":"https://example.com/pricing","tags":["pricing"]}]}'
import requests r = requests.post("https://agw.orcanox.xyz/v1/memory/write", headers={"Authorization": "Bearer agw_…"}, json={"items":[{"text":"The renewal price is $90/year","sourceUrl":"https://example.com/pricing","tags":["pricing"]}]}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/v1/memory/write", { method: "POST", headers: { "Authorization": "Bearer agw_…", "Content-Type": "application/json" }, body: JSON.stringify({"items":[{"text":"The renewal price is $90/year","sourceUrl":"https://example.com/pricing","tags":["pricing"]}]}) }); console.log(r.status, await r.json());
الاستجابة
json
{
"written": 2,
"updated": 0,
"ids": [
"<id-1>",
"<id-2>"
]
}الأخطاء
| الحالة | code | مثال |
|---|---|---|
| 400 | bad_request | {"code":"bad_request","message":"text normalizes to empty — nothing to store"} |
بحث دلالي على ذاكرتك — درجة هجينة: 0.7·تشابه الضمين + 0.3·تشابه النص. استعلامات العامية المصرية تُحوَّل للفصحى آليًا.
الطلب
| الحقل | النوع | الوصف | |
|---|---|---|---|
query | string | مطلوب | ما تبحث عنه. |
k | integer | اختياري | أقصى عدد نتائج (الافتراضي 10). |
minScore | number | اختياري | أدنى درجة هجينة (الافتراضي 0.35). |
tags | string[] | اختياري | عناصر تحمل أيًّا من هذه الوسوم فقط. |
مثال
curl -X POST https://agw.orcanox.xyz/v1/memory/search \ -H "Authorization: Bearer agw_…" \ -H "Content-Type: application/json" \ -d '{"query":"renewal price","k": 5}'
import requests r = requests.post("https://agw.orcanox.xyz/v1/memory/search", headers={"Authorization": "Bearer agw_…"}, json={"query":"renewal price","k": 5}) print(r.status_code, r.json())
const r = await fetch("https://agw.orcanox.xyz/v1/memory/search", { method: "POST", headers: { "Authorization": "Bearer agw_…", "Content-Type": "application/json" }, body: JSON.stringify({"query":"renewal price","k": 5}) }); console.log(r.status, await r.json());
الاستجابة
json
{
"items": [
{
"id": "<id>",
"text": "…",
"sourceUrl": "https://…",
"tags": [
"docs"
],
"createdAt": "2026-10-01T12: 00: 00.000Z",
"score": 0.78
}
],
"tookMs": 95
}الأخطاء
| الحالة | code | مثال |
|---|---|---|
| 400 | bad_request | {"code":"bad_request","message":"query normalizes to empty — nothing to match"} |
يحذف عنصر ذاكرة واحدًا بالمعرّف. محصور بالمستأجر: معرّف الغير لا يُميَّز عن المعدوم.
الطلب
| الحقل | النوع | الوصف | |
|---|---|---|---|
id (path) | string | مطلوب | معرّف عنصر الذاكرة. |
مثال
curl -X DELETE https://agw.orcanox.xyz/v1/memory/<id> \ -H "Authorization: Bearer agw_…" \ -H "Content-Type: application/json" \ -d '{}'
import requests
r = requests.delete("https://agw.orcanox.xyz/v1/memory/<id>", headers={"Authorization": "Bearer agw_…"}, json={})
print(r.status_code, r.json())const r = await fetch("https://agw.orcanox.xyz/v1/memory/<id>", {
method: "DELETE",
headers: { "Authorization": "Bearer agw_…", "Content-Type": "application/json" },
body: JSON.stringify({})
});
console.log(r.status, await r.json());
الاستجابة
json
{
"deleted": true,
"id": "<id>"
}الأخطاء
| الحالة | code | مثال |
|---|---|---|
| 404 | not_found | {"code":"not_found","message":"memory item not found"} |