بناء ذاكرة مشروع دلالية باستخدام Basic Memory و Milvus

يحتفظBasic Memory بمعرفة المشروع في ملفات Markdown عادية ويجعلها متاحة عبر واجهة سطر الأوامر (CLI) وخادم MCP. وهذا يوفر لمطور البرمجيات مكانًا دائمًا لتسجيل القرارات ودلائل التشغيل والدروس المستفادة التي يجب أن تبقى متاحة بعد انتهاء المحادثة.

في هذا البرنامج التعليمي، سنقوم ببناء مشروع ذاكرة صغير لفريق تطبيق. سنسجل ملاحظات حول التخزين المؤقت والمصادقة وعمليات النشر والنسخ الاحتياطي، ثم نسترجع الملاحظة الصحيحة باستخدام البحث الدلالي والمختلط.

سيقومMilvus بتخزين المتجهات وإجراء البحث عن التشابه. سيستمر Basic Memory في إدارة ملاحظات Markdown وبيانات تعريف المشروع والبحث عن النص الكامل وقائمة المتجهات في PostgreSQL.

Markdown notes
      |
      v
Basic Memory CLI / MCP
      |-- PostgreSQL: projects, metadata, full-text search, vector manifest
      |-- OpenAI: embeddings
      `-- Milvus: vector persistence and similarity search

يستخدم هذا البرنامج التعليمي Milvus Lite، الذي يعمل محليًّا في مسار على جهازك. ويمكن أن يشير نفس تكوين Basic Memory لاحقًا إلى Milvus Standalone أو Milvus Distributed أو Zilliz Cloud.

المتطلبات الأساسية

تحتاج إلى:

• Python 3.12 أو إصدار أحدث
• uv
• قاعدة بيانات PostgreSQL وعنوان URL الخاص باتصالها عبر postgresql+asyncpg://...
• مفتاح API لـ OpenAI

قم بتثبيت Basic Memory مع التبعيات الاختيارية لـ Milvus من PyPI:

uv tool install --python 3.12 "basic-memory[milvus]"

تكوين Basic Memory

قم بإنشاء مساحة عمل للبرنامج التعليمي. إن الاحتفاظ بتكوين Basic Memory وبيانات Milvus Lite هنا يجعل من السهل فحص المثال وإزالته لاحقًا.

mkdir -p basic-memory-milvus-demo/notes
cd basic-memory-milvus-demo

export BASIC_MEMORY_CONFIG_DIR="$PWD/.basic-memory"

قم بتكوين PostgreSQL كقاعدة البيانات الأساسية، و OpenAI كمزود التضمين، و Milvus كفهرس متجهي:

export BASIC_MEMORY_DATABASE_BACKEND=postgres
export BASIC_MEMORY_DATABASE_URL="postgresql+asyncpg://USER:PASSWORD@HOST:5432/DATABASE"

export BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED=true
export BASIC_MEMORY_SEMANTIC_VECTOR_INDEX=milvus
export BASIC_MEMORY_MILVUS_URI="$PWD/basic-memory-vectors.db"

export BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER=openai
export BASIC_MEMORY_SEMANTIC_EMBEDDING_MODEL=text-embedding-3-small
export OPENAI_API_KEY="sk-***********"

هنا، يُعد BASIC_MEMORY_MILVUS_URI مسارًا محليًّا، لذا يقوم PyMilvus بتشغيل Milvus Lite تلقائيًّا. ولا يلزم وجود خادم Milvus منفصل.

يُعد Milvus اختياريًا في «الذاكرة الأساسية» ككل، ولكنه الخلفية المتجهة المحددة في هذا البرنامج التعليمي. لا ينطبق هذا الاختيار حاليًا إلا عندما تكون الخلفية الأساسية لقاعدة البيانات هي PostgreSQL. تستخدم مشاريع «الذاكرة الأساسية» القائمة على SQLite sqlite-vec بدلاً من ذلك.

إنشاء مشروع "الذاكرة"

يقوم مشروع Basic Memory بتعيين اسم إلى دليل يحتوي على ملاحظات Markdown. أضف دليل البرنامج التعليمي كمشروع واجعله هو الافتراضي:

bm project add app-memory "$PWD/notes" --default

أصبح لدى فريق التطبيق الآن مساحة ذاكرة دائمة. دعونا نملأها بكتالوج صغير ومختلط. ستكون بعض الملاحظات ذات صلة بأسئلتنا اللاحقة، بينما توفر ملاحظات أخرى عوامل تشتيت واقعية.

تسجيل ذكريات المشروع

ابدأ بقرار التخزين المؤقت للتطبيق:

bm tool write-note \
  --title "Caching Strategy" \
  --folder "engineering" \
  --project app-memory <<'EOF'
# Caching Strategy

The application caches read-heavy product responses in Redis for five minutes. This avoids repeated database queries and makes repeated requests faster. Cache entries are invalidated immediately after a write.
EOF

سجل كيفية التعامل مع رموز المصادقة:

bm tool write-note \
  --title "Authentication Tokens" \
  --folder "engineering" \
  --project app-memory <<'EOF'
# Authentication Tokens

JWT access tokens expire after fifteen minutes. Refresh tokens rotate on every use. After suspicious activity, revoke the entire token family and require the user to sign in again.
EOF

أضف دليلين تشغيليين:

bm tool write-note \
  --title "Deployment Reliability" \
  --folder "operations" \
  --project app-memory <<'EOF'
# Deployment Reliability

Production releases use a canary deployment. Readiness probes must pass before traffic shifts, and the rollout automatically stops when the error rate crosses the agreed threshold.
EOF

bm tool write-note \
  --title "Database Backups" \
  --folder "operations" \
  --project app-memory <<'EOF'
# Database Backups

PostgreSQL uses daily snapshots and continuous write-ahead log archiving. The team runs a restore drill every month and records the recovery point and recovery time.
EOF

أخيرًا، أضف ملاحظتين غير مرتبطتين بالمنتج. فهذه الملاحظات تجعل عملية البحث أكثر تمثيلاً مقارنة بفهرس تكون فيه كل وثيقة ذات صلة:

bm tool write-note \
  --title "UI Accessibility" \
  --folder "product" \
  --project app-memory <<'EOF'
# UI Accessibility

The settings screen must support keyboard navigation, visible focus states, sufficient color contrast, and descriptive labels for screen readers.
EOF

bm tool write-note \
  --title "Content Planning" \
  --folder "product" \
  --project app-memory <<'EOF'
# Content Planning

The content calendar tracks blog drafts, launch screenshots, reviewers, and publication dates for the next product release.
EOF

تظل كل ملاحظة ملف Markdown عاديًا في notes/. يضيف Basic Memory البنية القابلة للبحث دون انتزاع الملكية من نظام الملفات.

قم بإنشاء فهارس البحث

قم بإجراء إعادة فهرسة كاملة بعد إضافة مجموعة من الملاحظات أو إجراء تغييرات جوهرية عليها:

bm reindex --full --project app-memory

خلال هذه الخطوة، يقوم Basic Memory بما يلي:

1. تقوم بقراءة ملاحظات Markdown وتقسيمها إلى أجزاء.
2. تقوم بإنشاء فهرس النص الكامل في PostgreSQL.
3. ترسل الأجزاء إلى نموذج التضمين OpenAI المُهيأ.
4. تخزين المتجهات الناتجة في مجموعة Milvus الخاصة بالمشروع.
5. تضع علامة "جاهز" على الأجزاء التي تم تخزينها بنجاح في قائمة المتجهات الخاصة بـ PostgreSQL.

يستخدم Basic Memory مجموعة Milvus حتمية لكل مشروع. لا تحتاج إلى إنشاء المجموعة أو تسميتها بنفسك.

استرجاع الذاكرة حسب المعنى

لنفترض أن مهندسًا جديدًا يتذكر أن التطبيق يحتوي على تحسين للطلبات المتكررة، لكنه لا يتذكر أن الفريق أطلق عليه اسم «استراتيجية التخزين المؤقت».

استخدم البحث المتجه لطرح السؤال باللغة الطبيعية:

bm tool search-notes \
  "How does the application make repeated requests faster?" \
  --vector \
  --project app-memory \
  --page-size 3 \
  --plain

Caching Strategy يجب أن تكون النتيجة الأولى حتى وإن لم يكن من الضروري تكرار عنوان الملاحظة في الاستعلام. يقوم البحث المتجه بتضمين السؤال ويطلب من Milvus أقرب الأجزاء المخزنة.

قد تختلف الدرجات الدقيقة والنتائج ذات الترتيب الأدنى باختلاف نموذج التضمين ومحتويات المشروع.

دمج الإشارات الدلالية وإشارات الكلمات المفتاحية

تخيل الآن الاستجابة لحادث أمني. يحتوي الاستعلام على مصطلحات دقيقة مثل « JWT » (إلغاء الرمز المميز)، لكننا نريد أيضًا لغة ذات صلة من الناحية المفاهيمية حول إلغاء الرمز المميز وتسجيل الدخول مرة أخرى.

استخدم البحث الهجين:

bm tool search-notes \
  "JWT rotation after suspicious activity" \
  --hybrid \
  --project app-memory \
  --page-size 3 \
  --plain

Authentication Tokens يجب أن تكون النتيجة الأولى. يجمع «Basic Memory» بين استرجاع النص الكامل في PostgreSQL واسترجاع المتجهات في Milvus، مما يمنح الأولوية للمحتوى القوي في أي من المسارين، وخاصة المحتوى الذي يتم العثور عليه في كليهما.

تتميز أوضاع البحث الثلاثة بمزايا مختلفة:

الوضع	علامة الأمر	أفضل استخدام
النص الكامل	لا يوجد علامة الوضع	استعلامات المصطلحات والعبارات الدقيقة والكلمات الرئيسية المنطقية
المتجه	--vector	الإعادة الصياغة والمفاهيم والأسئلة الاستكشافية
مختلط	--hybrid	الاسترجاع للأغراض العامة باستخدام كل من الكلمات المفتاحية والإشارات الدلالية

استخدام نسخة أخرى من Milvus

لا يتغير كود التطبيق وأوامر الذاكرة الأساسية عندما تتجاوز سعة Milvus Lite. قم بتغيير عنوان URI، وقدم رمزًا مميزًا عند الحاجة.

بالنسبة لخادم Milvus:

export BASIC_MEMORY_MILVUS_URI="http://localhost:19530"
export BASIC_MEMORY_MILVUS_TOKEN="root:Milvus"

بالنسبة لـ Zilliz Cloud:

export BASIC_MEMORY_MILVUS_URI="https://YOUR_CLUSTER_ENDPOINT"
export BASIC_MEMORY_MILVUS_TOKEN="YOUR_API_KEY"

قم بإنشاء مجموعة هدف جديدة أو اتبع إجراء ترحيل مخزن المتجهات في Basic Memory قبل تبديل مشروع موجود بين الخلفيات المتجهة. ثم أعد بناء المتجهات:

bm reindex --full --project app-memory

استخدم نفس الذاكرة عبر MCP

تعد واجهة سطر الأوامر (CLI) مفيدة للإعداد والصيانة وكتابة البرامج النصية وفهم تدفق البيانات. في العمل اليومي، يمكن لعميل MCP تشغيل نفس خدمة Basic Memory واستدعاء أدوات مثل write_note و search_notes و build_context مباشرةً.

على سبيل المثال، يمكن لتكوين Codex MCP تشغيل الأمر الذي تم تثبيته بواسطة uv tool:

[mcp_servers.basic-memory]
command = "basic-memory"
args = ["mcp"]

[mcp_servers.basic-memory.env]
BASIC_MEMORY_CONFIG_DIR = "/absolute/path/to/basic-memory-milvus-demo/.basic-memory"
BASIC_MEMORY_DATABASE_BACKEND = "postgres"
BASIC_MEMORY_DATABASE_URL = "postgresql+asyncpg://USER:PASSWORD@HOST:5432/DATABASE"
BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED = "true"
BASIC_MEMORY_SEMANTIC_VECTOR_INDEX = "milvus"
BASIC_MEMORY_MILVUS_URI = "/absolute/path/to/basic-memory-milvus-demo/basic-memory-vectors.db"
BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER = "openai"
BASIC_MEMORY_SEMANTIC_EMBEDDING_MODEL = "text-embedding-3-small"
OPENAI_API_KEY = "sk-***********"

تستخدم عملاء MCP الآخرون نفس الملف القابل للتنفيذ والوسائط بتنسيق JSON:

{
  "mcpServers": {
    "basic-memory": {
      "command": "basic-memory",
      "args": ["mcp"],
      "env": {
        "BASIC_MEMORY_CONFIG_DIR": "/absolute/path/to/basic-memory-milvus-demo/.basic-memory",
        "BASIC_MEMORY_DATABASE_BACKEND": "postgres",
        "BASIC_MEMORY_DATABASE_URL": "postgresql+asyncpg://USER:PASSWORD@HOST:5432/DATABASE",
        "BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED": "true",
        "BASIC_MEMORY_SEMANTIC_VECTOR_INDEX": "milvus",
        "BASIC_MEMORY_MILVUS_URI": "/absolute/path/to/basic-memory-milvus-demo/basic-memory-vectors.db",
        "BASIC_MEMORY_SEMANTIC_EMBEDDING_PROVIDER": "openai",
        "BASIC_MEMORY_SEMANTIC_EMBEDDING_MODEL": "text-embedding-3-small",
        "OPENAI_API_KEY": "sk-***********"
      }
    }
  }
}

احتفظ بكلمات مرور قواعد البيانات ومفاتيح واجهة برمجة التطبيقات (API) في نظام إدارة الأسرار الخاص بالعميل أو بيئة التشغيل كلما أمكن ذلك. الشرط المهم هو أن تتلقى عملية MCP نفس تكوين الذاكرة الأساسية (Basic Memory) الذي تستخدمه واجهة سطر الأوامر (CLI).

ما تمتلكه كل طبقة تخزين

في نهاية البرنامج التعليمي، يتم الفصل بين المسؤوليات بشكل متعمد:

• يمتلك دليل المشروع ملاحظات Markdown الأصلية.
• يمتلك PostgreSQL مشاريع Basic Memory، والكيانات، والبيانات الوصفية، وفهرس النص الكامل، وقائمة المتجهات الموثوقة.
• تقوم OpenAI بتحويل أجزاء الملاحظات وأسئلة البحث إلى تضمينات.
• تمتلك Milvus استمرارية المتجهات واسترجاع أقرب الجيران.
• تقوم Basic Memory بتنسيق الطبقات وتوفر تجربة واحدة لواجهة سطر الأوامر (CLI) وواجهة MCP.

وبالتالي، لا يحل Milvus محل PostgreSQL في هذا التكامل. بل يحل محل مسار PostgreSQL pgvector لتخزين المتجهات والبحث عن التشابه، بينما تظل بقية ميزات Basic Memory العلائقية والنصية الكاملة في PostgreSQL.