diff --git a/.github/i18n/README.ar.md b/.github/i18n/README.ar.md index d151b7ac..f2529601 100644 --- a/.github/i18n/README.ar.md +++ b/.github/i18n/README.ar.md @@ -53,13 +53,17 @@ opencode-mem **لا** يتطلب وحدة معالجة رسومات (GPU). تع على macOS وLinux، يمكن لعدة جلسات OpenCode مشاركة نفس `storagePath` عبر `multiprocess_wal` التجريبي من Turso (يجب أن يستخدم كل عملية نفس الوضع — أعد تشغيل جميع الجلسات بعد الترقية). على Windows يرفض المحرك ذلك العلم، لذا يمكن لجلسة OpenCode واحدة فقط امتلاك قواعد بيانات الذاكرة في وقت واحد. +يفتح `tursoMultiprocessWal: false` في وضع المالك الواحد بدلًا من ذلك: تفشل العمليات الأخرى بـ `database is locked` بدل مشاركة المخزن. هذا الخيار أكثر أمانًا إذا لمست أدوات خارج المكوّن الإضافي نفس الملفات، لأن عملية SQLite أجنبية _تكتب_ تجعل فهرس WAL لـ Turso قديمًا وتُفقد الكتابة التالية بصمت. ينقل `tursoAutoHeal` (الافتراضي `true`) ملفات الفهرس الجانبية `-shm`/`-tshm` للمخزن إلى `storagePath/recovery/-/` ويعيد المحاولة مرة عند فشل الفتح بسبب فهرس WAL قديم، بعد التحقق من نسخة من قاعدة البيانات الرئيسية. لا يُنقل `-wal` غير الفارغ أبدًا، فتبقى المعاملات المُلتزَم بها وغير المُتحققَنَة؛ يُزال فقط `-wal` المفقود أو ذو حجم 0 بايت. تُسلسل الجلسات المتزامنة الإصلاح عبر `storagePath/recovery/.lock`. + عند أول تشغيل بعد الترقية، يرحّل opencode-mem تلقائيًا قواعد بيانات أجزاء الذاكرة الحالية إلى تنسيق متجهات Turso/libSQL الأصلي: - يُنسخ كل جزء احتياطيًا باسم `.db.legacy.bak` قبل إعادة الكتابة - يُتتبَّع التقدم لكل جزء في `.db.turso-migrate.json` - تُكتب علامة عالمية `.turso-migrated` فقط بعد التحقق الناجح من جميع الأجزاء +- لا تُبطل الإدراجات والحذف العادية ترحيل جزء مكتمل؛ لا يزال البدء يتحقق من أن المتجهات قابلة للقراءة وتطابق الأبعاد المخزّنة - لا تشغّل عدة نسخ من OpenCode ضد نفس `storagePath` أثناء الترحيل؛ يمنع ملف قفل (`.turso-migrate.lock`) الترحيل المتزامن - تستخدم ترحيلات الأبعاد اليدوية `.turso-operation.lock`؛ ترفض عمليات المكون الإضافي الأخرى كتابات الذاكرة الجديدة حتى ينتهي الترحيل +- تنتهي الأقفال بعد 30 دقيقة دون تحديث طابع زمني للتقدم (أو وقت تعديل الملف إن تعذّر الطابع)، حتى لو كانت العملية المالكة حيّة. يستخدم هذا الإيجار ساعة الحائط: قفزة ساعة للأمام أكبر من 30 دقيقة قد تُنهي عملية جارية مبكرًا؛ قفزة للخلف أو قفل مؤرخ في المستقبل قد يمدّد عمر قفل خامل. تحمل الأقفال معرّف اقتناء فريدًا، وتنظيف الأقفال البالية يزيل فقط الملف الذي فحصه. ترسل الترحيلات نبضات أثناء التقدم وتُلغى إذا اكتشفت فقدان الملكية. يُسجَّل تنظيف الأقفال البالية للتشخيص. إذا انقطع الترحيل، يستأنف التشغيل التالي تلقائيًا من النسخة الاحتياطية. @@ -161,15 +165,27 @@ opencode-mem **لا** يتطلب وحدة معالجة رسومات (GPU). تع ما زال البحث/الإضافة/القائمة اليدوية تعمل حتى لو لم يكن للالتقاط التلقائي مزود مُعَد. يحتاج الالتقاط التلقائي وتعلّم ملف المستخدم مزودًا يمكنه إرجاع مخرجات منظمة/استدعاء أدوات. -### الذاكرة مقابل AGENTS.md / وثائق المشروع +### الذاكرة مقابل AGENTS.md مقابل Skills + +| خزّن في **الذاكرة** | خزّن في **AGENTS.md** / الوثائق الثابتة | خزّن كـ **Skills** (واجهة الويب / `skills.db`) | +| -------------------------------------------------- | --------------------------------------------------- | --------------------------------------------------- | +| قرارات خاصة بالمشروع، أنماط أخطاء، «جرّبنا X وفشل» | قواعد وسير عمل مستقرة نادرًا ما تتغير | إجراءات قابلة لإعادة الاستخدام يحمّلها الوكيل عند الحاجة | +| تفضيلات المستخدم المكتشفة عبر الجلسات | اصطلاحات البرمجة والعملية الدائمة | حزم skills قابلة للتحرير من الفريق عبر نفس التخزين | +| حقائق يجب أن تتبعك عبر المحادثات | تعليمات يجب أن يراها كل وكيل بغض النظر عن الاسترجاع | أداة `skill` الأصلية في OpenCode (جسر إضافة V2) | + +قاعدة عامة: تعليمات المشروع الدائمة دائمًا → `AGENTS.md`؛ سياق العمل المتنامي → الذاكرة؛ الإجراءات عند الطلب القابلة لإعادة الاستخدام → **Skills**. + +#### Shared Skills (V2) -| خزّن في **الذاكرة** | خزّن في **AGENTS.md** / الوثائق الثابتة | -| -------------------------------------------------- | --------------------------------------------------- | -| قرارات خاصة بالمشروع، أنماط أخطاء، «جرّبنا X وفشل» | قواعد وسير عمل مستقرة نادرًا ما تتغير | -| تفضيلات المستخدم المكتشفة عبر الجلسات | اصطلاحات البرمجة والعملية الدائمة | -| حقائق يجب أن تتبعك عبر المحادثات | تعليمات يجب أن يراها كل وكيل بغض النظر عن الاسترجاع | +- أنشئ/حرّر المهارات في مستكشف الويب (علامة تبويب **Skills** في `/skill-library`). +- تُحفَظ في `skills.db` تحت مسار تخزين المكوّن الإضافي (وليست متجهات ذاكرة). +- على OpenCode **V2** يسجّل المكوّن الإضافي المهارات المفعّلة عبر `ctx.skill.transform` حتى يحمّلها الوكيل بأداة `skill` الأصلية. +- كتالوج HTTP اختياري لنسخ OpenCode الأخرى: `"skills": ["http://127.0.0.1:4747/skills/"]` (يقدّم `/skills/index.json` و`/skills//.md` — منفصل عن مسار الواجهة). +- REST: `GET/POST /api/skills`، `GET/PUT/DELETE /api/skills/:id`. -قاعدة عامة: إذا كانت تعليمات مشروع دائمة، ضعها في AGENTS.md؛ إذا كان سياقًا ينمو من العمل الفعلي، دع الذاكرة (أو الالتقاط التلقائي) تحتفظ به. +### إحصاءات الصحة + +تعرض علامة تبويب **Stats** في واجهة الويب (في `/stats`) صحة نظام الذاكرة بنظرة واحدة: إجماليات لكل نطاق، وعدّادات الذاكرة لكل جزء مع تحذيرات الأجزاء البالية/المفقودة ووكيل تكرار نفس الوسم، وإصدار ملف المستخدم النشط، وسلسلة نشاط لـ14 يومًا (التقاطات، التقاطات المتخطاة، حقن الملف/الضغط، وأخطاء مجمّعة حسب الرسالة) مُحلَّلة من سجلات المكوّن الإضافي المنظَّمة في `~/.opencode-mem/`. للقراءة فقط — `GET /api/stats` — وتتراجع لكل قسم إن تعذّر الوصول إلى قاعدة بيانات، فتواصل الإبلاغ أثناء الحوادث. ### استخراج الذاكرة الذكي المستند إلى المطالبات @@ -219,6 +235,29 @@ memory({ mode: "import", inputPath: "./memories.json" }); ينشئ المكون الإضافي قالبًا كاملًا معلَّقًا في هذا المسار عند أول تشغيل. لكل إعداد وتعليق، انظر [`opencode-mem.example.jsonc`](../../opencode-mem.example.jsonc). +### خلفية Markdown vault (`memoryBackend`) + +افتراضيًا تعيش الذكريات فقط في Turso تحت `storagePath`. يمكنك اختياريًا تعيين **مجلد Markdown عام** كمصدر حقيقة (ملفات `.md` عادية متوافقة مع Obsidian/Raneto — وليست تكاملًا خاصًا بـ Obsidian): + +```jsonc +{ + "memoryBackend": "markdown", + "markdownPath": "~/Documents/LLM-Wiki", +} +``` + +| المفتاح | الافتراضي | ماذا يفعل | +| --------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `memoryBackend` | `"database"` | `"database"` يبقي المحتوى في Turso. `"markdown"` يستخدم كل ملفات `.md` تحت `markdownPath` كمصدر حقيقة. | +| `markdownPath` | — | مطلوب عندما يكون `memoryBackend` هو `"markdown"`. مسار مطلق أو `~/…` لمجلد الـ vault. لا مجلد ذاكرة فرعي منفصل — المسار _هو_ المخزن. | + +عند تفعيل وضع Markdown: + +- تُكتب الذكريات التي ينشئها المكوّن الإضافي كـ `{id}.md` مع YAML frontmatter + المحتوى. +- تُستورد/تُفهرس الملاحظات الموجودة في المجلد (أي أسلوب صفحة Markdown)؛ وTurso مجرد فهرس بحث دلالي قابل لإعادة البناء. +- تُراقَب إضافات/تعديلات/حذف الملفات ويُعاد فهرستها؛ تعرض واجهة الويب صفحة شريط جانبي **Markdown** (الحالة، قائمة الملفات، إعادة الفهرسة) في هذا الوضع فقط. +- التبديل إلى Markdown يعيد بناء الفهرس من المجلد — تُسقَط صفوف قاعدة البيانات فقط بلا ملف مطابق. صدّر أولًا بـ `memory export` إن احتجت الإبقاء على ذكريات قاعدة البيانات القديمة. + ### التقاط رسائل الدردشة وحقنها (`chatMessage`) تعيش هذه الإعدادات تحت المفتاح `chatMessage` في `~/.config/opencode/opencode-mem.jsonc`: diff --git a/.github/i18n/README.de.md b/.github/i18n/README.de.md index b1107c93..f8ce5c2b 100644 --- a/.github/i18n/README.de.md +++ b/.github/i18n/README.de.md @@ -53,13 +53,17 @@ Beim Start werden unterbrochene Re-Embed-Swaps wiederhergestellt, libSQL-DiskANN Unter macOS und Linux können mehrere OpenCode-Sitzungen denselben `storagePath` über Turso’s experimentelles `multiprocess_wal` teilen (jeder Prozess muss denselben Modus nutzen — nach dem Upgrade alle Sitzungen neu starten). Unter Windows lehnt die Engine dieses Flag ab, sodass nur eine OpenCode-Sitzung die Speicherdatenbanken gleichzeitig besitzen kann. +`tursoMultiprocessWal: false` öffnet stattdessen im Single-Owner-Modus: andere Prozesse scheitern dann mit `database is locked`, statt den Store zu teilen. Das ist die sicherere Wahl, wenn Nicht-Plugin-Tools dieselben Dateien anfassen, weil ein _schreibender_ fremder SQLite-Prozess den WAL-Index von Turso veraltet macht und der eigene nächste Write still verloren geht. `tursoAutoHeal` (Standard `true`) verschiebt die Index-Sidecars `-shm`/`-tshm` eines Stores nach `storagePath/recovery/-/` und versucht einmal erneut, wenn ein Open wegen veraltetem WAL-Index scheitert — nachdem eine Kopie der Hauptdatenbank verifiziert wurde. Eine nicht leere `-wal` wird nie verschoben, sodass committed aber noch nicht checkpointete Transaktionen erhalten bleiben; nur fehlende oder 0-Byte-`-wal` werden entfernt. Gleichzeitige Sitzungen serialisieren das Heilen über `storagePath/recovery/.lock`. + Beim ersten Start nach dem Upgrade migriert opencode-mem vorhandene Memory-Shard-Datenbanken automatisch in das native Turso/libSQL-Vektorformat: - Jeder Shard wird vor dem Rewrite als `.db.legacy.bak` gesichert - Der Fortschritt wird pro Shard in `.db.turso-migrate.json` verfolgt - Ein globaler Marker `.turso-migrated` wird erst geschrieben, wenn alle Shards erfolgreich verifiziert wurden +- Normale Inserts und Deletes entwerten eine abgeschlossene Shard-Migration nicht; beim Start wird weiterhin geprüft, dass Vektoren lesbar sind und zu den gespeicherten Dimensionen passen - Während der Migration keine mehreren OpenCode-Instanzen gegen denselben `storagePath` betreiben; eine Lock-Datei (`.turso-migrate.lock`) verhindert parallele Migration - Manuelle Dimensionsmigrationen nutzen `.turso-operation.lock`; andere Plugin-Prozesse lehnen neue Memory-Writes ab, bis die Migration fertig ist +- Locks verfallen nach 30 Minuten ohne Fortschritts-Timestamp-Update (oder Datei-Änderungszeit, falls der Timestamp fehlt), auch wenn der besitzende Prozess noch lebt. Dieses Lease nutzt Wanduhrzeit: ein Vorwärtssprung der Uhr um mehr als 30 Minuten kann eine laufende Operation früh beenden; ein Rückwärtssprung oder ein zukunftsdatiertes Lock kann ein inertes Lock verlängern. Locks tragen eine eindeutige Acquisition-ID, und Stale-Cleanup entfernt nur die genau inspizierte Datei. Migrationen senden Heartbeats und brechen ab, wenn sie den Besitzverlust feststellen. Stale-Lock-Cleanup wird zur Diagnose geloggt. Wird die Migration unterbrochen, setzt der nächste Start die Arbeit aus dem Backup automatisch fort. @@ -161,15 +165,27 @@ Du musst OpenCode **nicht** bitten, Dinge zu „merken“, damit das Plugin funk Manuelle Suche/Hinzufügen/Listen funktionieren auch, wenn für Auto-Capture kein Provider konfiguriert ist. Auto-Capture und Lernen des Benutzerprofils brauchen einen Provider, der strukturierte/Tool-Call-Ausgabe liefern kann. -### Speicher vs. AGENTS.md / Projektdokumentation +### Speicher vs. AGENTS.md vs. Skills + +| In **memory** speichern | In **AGENTS.md** / statischen Docs speichern | Als **Skills** speichern (Web-UI / `skills.db`) | +| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | --------------------------------------------------------------- | +| Projektspezifische Entscheidungen, Bug-Muster, „wir haben X versucht und es ist gescheitert“ | Stabile Regeln und Workflows, die sich selten ändern | Wiederverwendbare Prozeduren, die der Agent bei Bedarf lädt | +| Über Sitzungen hinweg entdeckte Benutzerpräferenzen | Immer gültige Coding-Konventionen und Prozesse | Team-editierbare Skill-Packs über denselben Storage | +| Fakten, die dir über Chats hinweg folgen sollen | Anweisungen, die jeder Agent unabhängig von Retrieval sehen soll | OpenCode-natives `skill`-Tool (V2-Plugin-Bridge) | + +Faustregel: dauerhafte Always-on-Projektanweisungen → `AGENTS.md`; wachsender Arbeitskontext → Speicher; wiederverwendbare On-Demand-Prozeduren → **Skills**. + +#### Shared Skills (V2) -| In **memory** speichern | In **AGENTS.md** / statischen Docs speichern | -| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| Projektspezifische Entscheidungen, Bug-Muster, „wir haben X versucht und es ist gescheitert“ | Stabile Regeln und Workflows, die sich selten ändern | -| Über Sitzungen hinweg entdeckte Benutzerpräferenzen | Immer gültige Coding-Konventionen und Prozesse | -| Fakten, die dir über Chats hinweg folgen sollen | Anweisungen, die jeder Agent unabhängig von Retrieval sehen soll | +- Skills im Web-Explorer anlegen/bearbeiten (**Skills**-Tab unter `/skill-library`). +- Persistiert in `skills.db` unter dem Plugin-Storage-Pfad (nicht als Memory-Vektoren). +- Unter OpenCode **V2** registriert das Plugin aktivierte Skills über `ctx.skill.transform`, sodass der Agent sie mit dem nativen `skill`-Tool laden kann. +- Optionaler HTTP-Katalog für andere OpenCode-Instanzen: `"skills": ["http://127.0.0.1:4747/skills/"]` (liefert `/skills/index.json` und `/skills//.md` — getrennt vom UI-Pfad). +- REST: `GET/POST /api/skills`, `GET/PUT/DELETE /api/skills/:id`. -Faustregel: Ist es eine dauerhafte Projektanweisung, gehört sie in AGENTS.md; ist es Kontext, der aus echter Arbeit wächst, soll ihn der Speicher (oder Auto-Capture) halten. +### Health-Stats + +Der **Stats**-Tab der Web-UI (unter `/stats`) zeigt auf einen Blick die Gesundheit des Memory-Systems: Totals pro Scope, Memory-Zählungen pro Shard mit Warnungen zu veralteten/fehlenden Shards und einem Proxy für Same-Tag-Duplikate, die aktive User-Profil-Version sowie eine 14-Tage-Aktivitätsserie (Captures, übersprungene Captures, Profil-/Compaction-Injections und nach Message gebucketete Fehler) aus den strukturierten Plugin-Logs in `~/.opencode-mem/`. Nur lesend — `GET /api/stats` — und degradiert pro Abschnitt, wenn eine Datenbank fehlt, sodass bei Incidents weiter berichtet wird. ### Intelligente promptbasierte Speicherextraktion @@ -219,6 +235,29 @@ Konfiguration unter `~/.config/opencode/opencode-mem.jsonc`: Das Plugin legt beim ersten Start eine voll kommentierte Vorlage unter diesem Pfad an. Für jede Einstellung und jeden Kommentar siehe [`opencode-mem.example.jsonc`](../../opencode-mem.example.jsonc). +### Markdown-Vault-Backend (`memoryBackend`) + +Standardmäßig liegen Memories nur in Turso unter `storagePath`. Optional kannst du einen **generischen Markdown-Ordner** als Source of Truth setzen (Obsidian-/Raneto-kompatible reine `.md`-Dateien — keine Obsidian-spezifische Integration): + +```jsonc +{ + "memoryBackend": "markdown", + "markdownPath": "~/Documents/LLM-Wiki", +} +``` + +| Schlüssel | Standard | Was er tut | +| --------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `memoryBackend` | `"database"` | `"database"` hält den Inhalt in Turso. `"markdown"` nutzt alle `.md`-Dateien unter `markdownPath` als Source of Truth. | +| `markdownPath` | — | Erforderlich bei `memoryBackend: "markdown"`. Absoluter oder `~/…`-Pfad zum Vault-Ordner. Kein separates Memory-Unterverzeichnis — der Pfad _ist_ der Store. | + +Wenn Markdown-Modus aktiv ist: + +- Vom Plugin erzeugte Memories werden als `{id}.md` mit YAML-Frontmatter + Body geschrieben. +- Vorhandene Notizen im Ordner (beliebiger Markdown-Seitenstil) werden importiert/indexiert; Turso ist nur ein neu aufbaubarer Semantic-Search-Index. +- Datei-Adds/Edits/Deletes werden beobachtet und neu indexiert; die Web-UI zeigt nur in diesem Modus eine **Markdown**-Sidebar-Seite (Status, Dateiliste, Reindex). +- Der Wechsel zu Markdown baut den Index aus dem Ordner neu — DB-only-Zeilen ohne passende Datei entfallen. Zuerst mit `memory export` exportieren, wenn du alte Datenbank-Memories behalten willst. + ### Erfassung und Injection von Chat-Nachrichten (`chatMessage`) Diese Einstellungen liegen unter dem Schlüssel `chatMessage` in `~/.config/opencode/opencode-mem.jsonc`: diff --git a/.github/i18n/README.nl.md b/.github/i18n/README.nl.md index 38f52543..45f0ddd3 100644 --- a/.github/i18n/README.nl.md +++ b/.github/i18n/README.nl.md @@ -53,13 +53,17 @@ Bij opstarten herstelt de plugin onderbroken re-embed-swaps, zet libSQL DiskANN- Op macOS en Linux kunnen meerdere OpenCode-sessies hetzelfde `storagePath` delen via Turso’s experimentele `multiprocess_wal` (elk proces moet dezelfde modus gebruiken — herstart alle sessies na een upgrade). Op Windows weigert de engine die flag, dus slechts één OpenCode-sessie kan tegelijk de geheugendatabases bezitten. +`tursoMultiprocessWal: false` opent in single-owner-modus: andere processen falen dan met `database is locked` in plaats van de store te delen. Dat is veiliger als niet-plugin-tools dezelfde bestanden aanraken, omdat een _schrijvend_ vreemd SQLite-proces de WAL-index van Turso stale maakt en de eigen volgende write stil verloren gaat. `tursoAutoHeal` (standaard `true`) verplaatst de index-sidecars `-shm`/`-tshm` van een store naar `storagePath/recovery/-/` en probeert één keer opnieuw wanneer een open faalt door een stale WAL-index, na verificatie van een kopie van de hoofddatabase. Een niet-lege `-wal` wordt nooit verplaatst, zodat gecommitte maar nog niet gecheckpointte transacties overleven; alleen een ontbrekende of 0-byte `-wal` wordt verwijderd. Gelijktijdige sessies serialiseren healing via `storagePath/recovery/.lock`. + Bij de eerste start na een upgrade migreert opencode-mem bestaande memory-shard-databases automatisch naar het native Turso/libSQL-vectorformaat: - Elke shard wordt vóór herschrijven geback-upt als `.db.legacy.bak` - Voortgang wordt per shard bijgehouden in `.db.turso-migrate.json` - Een globale marker `.turso-migrated` wordt pas geschreven nadat alle shards succesvol zijn geverifieerd +- Normale inserts en deletes maken een voltooide shard-migratie niet ongeldig; bij opstarten controleert de plugin nog steeds of vectoren leesbaar zijn en bij de opgeslagen dimensies passen - Draai geen meerdere OpenCode-instanties tegen hetzelfde `storagePath` tijdens migratie; een lockbestand (`.turso-migrate.lock`) voorkomt gelijktijdige migratie - Handmatige dimensiemigraties gebruiken `.turso-operation.lock`; andere pluginprocessen weigeren nieuwe memory-writes tot de migratie klaar is +- Locks verlopen na 30 minuten zonder voortgangs-timestamp-update (of bestandswijzigingstijd als die timestamp ontbreekt), ook als het bezittende proces nog leeft. Deze lease gebruikt wandkloktijd: een voorwaartse kloksprong groter dan 30 minuten kan een lopende operatie vroeg laten verlopen; een achterwaartse stap of toekomstgedateerde lock kan een inerte lock verlengen. Locks dragen een unieke acquisition-id, en stale cleanup verwijdert alleen het precies geïnspecteerde bestand. Migraties sturen heartbeats en breken af als ze merken dat ownership verloren is. Stale-lock-cleanup wordt gelogd voor diagnose. Als migratie wordt onderbroken, hervat de volgende start automatisch vanuit de backup. @@ -161,15 +165,27 @@ Je hoeft OpenCode **niet** te vragen dingen te “onthouden” om de plugin te l Handmatige search/add/list werken nog steeds, ook als auto-capture geen provider geconfigureerd heeft. Auto-capture en gebruikersprofiel-leren hebben een provider nodig die structured/tool-call-output kan teruggeven. -### Geheugen versus AGENTS.md / projectdocumentatie +### Geheugen versus AGENTS.md versus Skills + +| Opslaan in **geheugen** | Opslaan in **AGENTS.md** / statische docs | Opslaan als **Skills** (web-UI / `skills.db`) | +| ----------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------- | +| Projectspecifieke beslissingen, bugpatronen, “we hebben X geprobeerd en het faalde” | Stabiele regels en workflows die zelden wijzigen | Herbruikbare procedures die de agent on demand laadt | +| Gebruikersvoorkeuren ontdekt over sessies | Altijd-aan codingconventies en proces | Door het team bewerkbare skill-packs via dezelfde opslag | +| Feiten die je over chats heen moeten volgen | Instructies die elke agent moet zien, ongeacht retrieval | OpenCode-native `skill`-tool (V2-pluginbrug) | + +Vuistregel: blijvende always-on projectinstructies → `AGENTS.md`; groeiende werkcontext → geheugen; herbruikbare on-demand procedures → **Skills**. + +#### Shared Skills (V2) -| Opslaan in **geheugen** | Opslaan in **AGENTS.md** / statische docs | -| ----------------------------------------------------------------------------------- | -------------------------------------------------------- | -| Projectspecifieke beslissingen, bugpatronen, “we hebben X geprobeerd en het faalde” | Stabiele regels en workflows die zelden wijzigen | -| Gebruikersvoorkeuren ontdekt over sessies | Altijd-aan codingconventies en proces | -| Feiten die je over chats heen moeten volgen | Instructies die elke agent moet zien, ongeacht retrieval | +- Skills aanmaken/bewerken in de web explorer (**Skills**-tab op `/skill-library`). +- Opgeslagen in `skills.db` onder het plugin-opslagpad (niet als geheugenvectoren). +- Op OpenCode **V2** registreert de plugin ingeschakelde skills via `ctx.skill.transform`, zodat de agent ze met de native `skill`-tool kan laden. +- Optionele HTTP-catalogus voor andere OpenCode-instanties: `"skills": ["http://127.0.0.1:4747/skills/"]` (serveert `/skills/index.json` en `/skills//.md` — los van het UI-pad). +- REST: `GET/POST /api/skills`, `GET/PUT/DELETE /api/skills/:id`. -Vuistregel: als het een blijvende projectinstructie is, zet het in AGENTS.md; als het context is die groeit uit echt werk, laat geheugen (of auto-capture) het bewaren. +### Health-stats + +De **Stats**-tab van de web-UI (op `/stats`) toont in één oogopslag de gezondheid van het geheugensysteem: totalen per scope, geheugentellingen per shard met waarschuwingen voor stale/ontbrekende shards en een same-tag-duplicatieproxy, de actieve gebruikersprofielversie, en een 14-daagse activiteitsserie (captures, overgeslagen captures, profiel-/compaction-injecties en op message gebucketteerde fouten) uit de gestructureerde pluginlogs in `~/.opencode-mem/`. Alleen-lezen — `GET /api/stats` — en degradeert per sectie als een database ontbreekt, zodat rapportage tijdens incidenten doorgaat. ### Intelligente promptgebaseerde geheugenextractie @@ -219,6 +235,29 @@ Configureer op `~/.config/opencode/opencode-mem.jsonc`: De plugin maakt bij de eerste start een volledig becommentarieerd template op dit pad. Voor elke instelling en commentaar, zie [`opencode-mem.example.jsonc`](../../opencode-mem.example.jsonc). +### Markdown-vault-backend (`memoryBackend`) + +Standaard leven herinneringen alleen in Turso onder `storagePath`. Optioneel kun je een **generieke Markdown-map** als bron van waarheid zetten (Obsidian-/Raneto-compatibele platte `.md`-bestanden — geen Obsidian-specifieke integratie): + +```jsonc +{ + "memoryBackend": "markdown", + "markdownPath": "~/Documents/LLM-Wiki", +} +``` + +| Sleutel | Standaard | Wat het doet | +| --------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `memoryBackend` | `"database"` | `"database"` houdt content in Turso. `"markdown"` gebruikt alle `.md`-bestanden onder `markdownPath` als bron van waarheid. | +| `markdownPath` | — | Vereist wanneer `memoryBackend` `"markdown"` is. Absoluut of `~/…`-pad naar de vault-map. Geen aparte memory-submap — het pad _is_ de store. | + +Wanneer Markdown-modus aan staat: + +- Door de plugin gemaakte herinneringen worden als `{id}.md` met YAML-frontmatter + body geschreven. +- Bestaande notities in de map (elke Markdown-paginastijl) worden geïmporteerd/geïndexeerd; Turso is alleen een herbouwbare semantic-search-index. +- Bestandsadds/bewerkingen/verwijderingen worden bewaakt en opnieuw geïndexeerd; de web-UI toont alleen in deze modus een **Markdown**-sidebarpagina (status, bestandenlijst, reindex). +- Overschakelen naar Markdown herbouwt de index vanuit de map — DB-only-rijen zonder bijpassend bestand verdwijnen. Exporteer eerst met `memory export` als je oude databaseherinneringen wilt bewaren. + ### Chatberichtvastlegging en -injectie (`chatMessage`) Deze instellingen staan onder de `chatMessage`-sleutel in `~/.config/opencode/opencode-mem.jsonc`: diff --git a/.github/i18n/README.tr.md b/.github/i18n/README.tr.md index 093df533..27281470 100644 --- a/.github/i18n/README.tr.md +++ b/.github/i18n/README.tr.md @@ -53,13 +53,17 @@ Başlangıçta kesintiye uğramış yeniden-embedding değişimleri kurtarılır macOS ve Linux’ta birden fazla OpenCode oturumu, Turso’nun deneysel `multiprocess_wal` özelliğiyle aynı `storagePath`’i paylaşabilir (her süreç aynı modu kullanmalıdır — yükseltmeden sonra tüm oturumları yeniden başlatın). Windows’ta motor bu bayrağı reddeder; bu nedenle aynı anda yalnızca bir OpenCode oturumu bellek veritabanlarının sahibi olabilir. +`tursoMultiprocessWal: false` bunun yerine tek-sahip modunda açar: diğer süreçler depoyu paylaşmak yerine `database is locked` ile başarısız olur. Eklenti dışı araçlar aynı dosyalara dokunuyorsa bu daha güvenlidir; çünkü _yazan_ yabancı bir SQLite süreci Turso’nun WAL dizinini bayatlatır ve bir sonraki yazma sessizce kaybolur. `tursoAutoHeal` (varsayılan `true`), bir açılış bayat WAL dizininden dolayı başarısız olduğunda ana veritabanının bir kopyasını doğruladıktan sonra deponun `-shm`/`-tshm` indeks yan dosyalarını `storagePath/recovery/-/` altına taşır ve bir kez yeniden dener. Boş olmayan bir `-wal` asla taşınmaz; böylece commit edilmiş ama henüz checkpoint edilmemiş işlemler korunur; yalnızca eksik veya 0 baytlık `-wal` kaldırılır. Eşzamanlı oturumlar iyileştirmeyi `storagePath/recovery/.lock` üzerinden serileştirir. + Yükseltmeden sonraki ilk başlangıçta opencode-mem mevcut bellek shard veritabanlarını yerel Turso/libSQL vektör biçimine otomatik olarak taşır: - Her shard yeniden yazılmadan önce `.db.legacy.bak` olarak yedeklenir - İlerleme shard başına `.db.turso-migrate.json` içinde izlenir - Genel bir `.turso-migrated` işaretçisi yalnızca tüm shard’lar başarıyla doğrulandıktan sonra yazılır +- Normal eklemeler ve silmeler tamamlanmış bir shard migrasyonunu geçersiz kılmaz; başlangıçta vektörlerin okunabilir olduğu ve saklanan boyutlarla eşleştiği hâlâ kontrol edilir - Migrasyon sırasında aynı `storagePath`’e karşı birden fazla OpenCode örneği çalıştırmayın; bir kilit dosyası (`.turso-migrate.lock`) eşzamanlı migrasyonu engeller - Manuel boyut migrasyonları `.turso-operation.lock` kullanır; diğer eklenti süreçleri migrasyon bitene kadar yeni bellek yazılarını reddeder +- Kilitler, ilerleme zaman damgası güncellemesi olmadan (veya zaman damgası yoksa dosya değişiklik zamanı) 30 dakika sonra sona erer; sahip süreç hâlâ canlı olsa bile. Bu kira duvar saati kullanır: 30 dakikadan büyük ileri saat sıçraması ilerleyen bir işlemi erken sonlandırabilir; geri sıçrama veya geleceğe tarihli kilit hareketsiz bir kilidin ömrünü uzatabilir. Kilitler benzersiz bir edinme kimliği taşır ve bayat temizleme yalnızca incelediği dosyayı kaldırır. Migrasyonlar ilerlerken heartbeat gönderir ve sahipliğin kaybolduğunu fark ederlerse iptal eder. Bayat-kilit temizliği tanı için günlüğe yazılır. Migrasyon kesintiye uğrarsa, sonraki başlangıç yedekten otomatik olarak devam eder. @@ -163,15 +167,27 @@ Eklentinin çalışması için OpenCode’dan bir şeyleri “hatırlamasını Manuel arama/ekleme/listeleme, otomatik yakalama için yapılandırılmış bir sağlayıcı olmasa bile çalışır. Otomatik yakalama ve kullanıcı profili öğrenme, yapılandırılmış/araç-çağrısı çıktısı döndürebilen bir sağlayıcı gerektirir. -### Bellek ve AGENTS.md / proje dokümanları +### Bellek ve AGENTS.md ve Skills + +| **Bellekte** saklayın | **AGENTS.md** / statik dokümanlarda saklayın | **Skills** olarak saklayın (web arayüzü / `skills.db`) | +| ---------------------------------------------------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------- | +| Projeye özgü kararlar, hata kalıpları, “X’i denedik ve başarısız oldu” | Nadiren değişen kararlı kurallar ve iş akışları | Ajanın gerektiğinde yüklediği yeniden kullanılabilir prosedürler | +| Oturumlar boyunca keşfedilen kullanıcı tercihleri | Her zaman geçerli kodlama kuralları ve süreç | Aynı depolama üzerinden düzenlenebilir ekip skill paketleri | +| Sohbetler arasında sizi takip etmesi gereken gerçekler | Erişimden bağımsız olarak her ajanın görmesi gereken talimatlar | OpenCode yerel `skill` aracı (V2 eklenti köprüsü) | + +Parmak kuralı: kalıcı always-on proje talimatları → `AGENTS.md`; büyüyen çalışma bağlamı → bellek; yeniden kullanılabilir on-demand prosedürler → **Skills**. + +#### Shared Skills (V2) -| **Bellekte** saklayın | **AGENTS.md** / statik dokümanlarda saklayın | -| ---------------------------------------------------------------------- | --------------------------------------------------------------- | -| Projeye özgü kararlar, hata kalıpları, “X’i denedik ve başarısız oldu” | Nadiren değişen kararlı kurallar ve iş akışları | -| Oturumlar boyunca keşfedilen kullanıcı tercihleri | Her zaman geçerli kodlama kuralları ve süreç | -| Sohbetler arasında sizi takip etmesi gereken gerçekler | Erişimden bağımsız olarak her ajanın görmesi gereken talimatlar | +- Web gezgininde skill oluşturun/düzenleyin (**Skills** sekmesi `/skill-library`). +- Eklenti depolama yolundaki `skills.db` içinde saklanır (bellek vektörleri olarak değil). +- OpenCode **V2**’de eklenti, etkin skill’leri `ctx.skill.transform` ile kaydeder; ajan bunları yerel `skill` aracıyla yükleyebilir. +- Diğer OpenCode örnekleri için isteğe bağlı HTTP kataloğu: `"skills": ["http://127.0.0.1:4747/skills/"]` (`/skills/index.json` ve `/skills//.md` sunar — UI yolundan ayrı). +- REST: `GET/POST /api/skills`, `GET/PUT/DELETE /api/skills/:id`. -Parmak kuralı: kalıcı bir proje talimatıysa AGENTS.md’ye koyun; gerçek çalışmadan büyüyen bağlamsa belleğin (veya otomatik yakalamanın) tutmasına izin verin. +### Sağlık istatistikleri + +Web arayüzünün **Stats** sekmesi (`/stats`) bellek sistemi sağlığını bir bakışta gösterir: kapsam başına toplamlar, bayat/eksik shard uyarıları ve aynı-etiket çoğaltma vekiliyle shard başına bellek sayıları, etkin kullanıcı profili sürümü ve `~/.opencode-mem/` içindeki yapılandırılmış eklenti günlüklerinden ayrıştırılan 14 günlük etkinlik serisi (yakalamalar, atlanan yakalamalar, profil/sıkıştırma enjeksiyonları ve mesaja göre gruplanmış hatalar). Salt okunur — `GET /api/stats` — ve bir veritabanı kullanılamazsa bölüm bölüm bozulur; böylece olay sırasında raporlamaya devam eder. ### Akıllı prompt tabanlı bellek çıkarımı @@ -221,6 +237,29 @@ Boyut migrasyonları önce her yeni embedding’i üretir, bunları geçici inde Eklenti ilk başlangıçta bu yolda tam yorumlu bir şablon oluşturur. Her ayar ve yorum için bkz. [`opencode-mem.example.jsonc`](../../opencode-mem.example.jsonc). +### Markdown vault backend (`memoryBackend`) + +Varsayılan olarak bellekler yalnızca `storagePath` altındaki Turso’da yaşar. İsteğe bağlı olarak **genel bir Markdown klasörünü** doğruluk kaynağı olarak ayarlayabilirsiniz (Obsidian/Raneto uyumlu düz `.md` dosyaları — Obsidian’a özel bir entegrasyon değildir): + +```jsonc +{ + "memoryBackend": "markdown", + "markdownPath": "~/Documents/LLM-Wiki", +} +``` + +| Anahtar | Varsayılan | Ne yapar | +| --------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `memoryBackend` | `"database"` | `"database"` içeriği Turso’da tutar. `"markdown"`, `markdownPath` altındaki tüm `.md` dosyalarını doğruluk kaynağı olarak kullanır. | +| `markdownPath` | — | `memoryBackend` `"markdown"` iken zorunlu. Vault klasörüne mutlak veya `~/…` yolu. Ayrı bir bellek alt klasörü yok — yol _kendisi_ depodur. | + +Markdown modu açıkken: + +- Eklentinin oluşturduğu bellekler YAML frontmatter + gövde ile `{id}.md` olarak yazılır. +- Klasördeki mevcut notlar (herhangi bir Markdown sayfa stili) içe aktarılır/indekslenir; Turso yalnızca yeniden oluşturulabilir bir anlamsal arama indeksidir. +- Dosya ekleme/düzenleme/silme izlenir ve yeniden indekslenir; Web arayüzü yalnızca bu modda bir **Markdown** kenar çubuğu sayfası gösterir (durum, dosya listesi, yeniden indeks). +- Markdown’a geçiş indeksi klasörden yeniden oluşturur — eşleşen dosyası olmayan yalnızca-DB satırları düşer. Eski veritabanı belleklerini saklamak istiyorsanız önce `memory export` ile dışa aktarın. + ### Sohbet mesajı yakalama ve enjekte etme (`chatMessage`) Bu ayarlar `~/.config/opencode/opencode-mem.jsonc` içindeki `chatMessage` anahtarı altında yaşar: diff --git a/.github/i18n/README.zh.md b/.github/i18n/README.zh.md index 1909fc55..d90a4e92 100644 --- a/.github/i18n/README.zh.md +++ b/.github/i18n/README.zh.md @@ -53,13 +53,17 @@ opencode-mem **不**需要 GPU。本地嵌入通过 `@huggingface/transformers` 在 macOS 与 Linux 上，多个 OpenCode 会话可通过 Turso 的实验性 `multiprocess_wal` 共享同一 `storagePath`（每个进程必须使用相同模式 — 升级后请重启所有会话）。在 Windows 上引擎会拒绝该标志，因此同一时间只能有一个 OpenCode 会话拥有记忆数据库。 +`tursoMultiprocessWal: false` 改为单所有者模式打开：其他进程会以 `database is locked` 失败，而不是共享存储。若非插件工具会触碰相同文件，这更安全——因为_正在写入_的外部 SQLite 进程会使 Turso 的 WAL 索引过期，随后本进程的下一次写入会静默丢失。`tursoAutoHeal`（默认 `true`）在因过期 WAL 索引导致打开失败时，会在验证主数据库副本后，将存储的 `-shm`/`-tshm` 索引旁路文件移到 `storagePath/recovery/-/` 并重试一次。非空 `-wal` 永不移动，因此已提交但未检查点的事务得以保留；仅删除缺失或 0 字节的 `-wal`。并发会话通过 `storagePath/recovery/.lock` 串行化修复。 + 升级后首次启动时，opencode-mem 会自动将现有记忆分片数据库迁移为原生 Turso/libSQL 向量格式： - 每个分片在重写前备份为 `.db.legacy.bak` - 进度按分片记录在 `.db.turso-migrate.json` - 仅在所有分片验证成功后才写入全局标记 `.turso-migrated` +- 普通插入与删除不会使已完成的分片迁移失效；启动时仍会检查向量可读且与已存维度匹配 - 迁移期间请勿对同一 `storagePath` 运行多个 OpenCode 实例；锁文件（`.turso-migrate.lock`）可防止并发迁移 - 手动维度迁移使用 `.turso-operation.lock`；在迁移完成前，其他插件进程会拒绝新的记忆写入 +- 若 30 分钟内没有进度时间戳更新（若无时间戳则看文件修改时间），锁会过期，即使持有进程仍在运行。该租约使用挂钟时间：向前拨钟超过 30 分钟可能使进行中的操作过早过期；向后拨钟或未来日期的锁可能延长空闲锁寿命。锁带有唯一获取 id，过期清理只删除其检查过的那个文件。迁移过程会发送心跳，一旦发现所有权丢失即中止。过期锁清理会写入日志以便诊断。 若迁移被中断，下次启动会自动从备份恢复。 @@ -161,15 +165,27 @@ v2 插件通过模型的系统上下文提供自动记忆上下文。 即使自动捕获未配置提供商，手动搜索/添加/列表仍可工作。自动捕获与用户画像学习需要能返回结构化/工具调用输出的提供商。 -### 记忆 vs AGENTS.md / 项目文档 +### 记忆 vs AGENTS.md vs Skills + +| 存入**记忆** | 存入 **AGENTS.md** / 静态文档 | 存为 **Skills**（Web UI / `skills.db`） | +| --------------------------------------------- | ------------------------------------ | --------------------------------------------- | +| 项目特定决策、缺陷模式、“我们试过 X 但失败了” | 很少变化的稳定规则与工作流 | 代理按需加载的可复用流程 | +| 跨会话发现的用户偏好 | 始终生效的编码约定与流程 | 通过同一存储共享、可由团队编辑的 skill 包 | +| 应跟随你跨聊天的事实 | 无论检索如何、每个代理都应看到的指令 | OpenCode 原生 `skill` 工具（V2 插件桥接） | + +经验法则：持久的始终生效项目指令 → `AGENTS.md`；不断增长的工作上下文 → 记忆；可复用的按需流程 → **Skills**。 + +#### Shared Skills（V2） -| 存入**记忆** | 存入 **AGENTS.md** / 静态文档 | -| --------------------------------------------- | ------------------------------------ | -| 项目特定决策、缺陷模式、“我们试过 X 但失败了” | 很少变化的稳定规则与工作流 | -| 跨会话发现的用户偏好 | 始终生效的编码约定与流程 | -| 应跟随你跨聊天的事实 | 无论检索如何、每个代理都应看到的指令 | +- 在 Web 资源管理器中创建/编辑 skills（**Skills** 选项卡，路径 `/skill-library`）。 +- 保存在插件存储路径下的 `skills.db`（不是记忆向量）。 +- 在 OpenCode **V2** 上，插件通过 `ctx.skill.transform` 注册已启用的 skills，以便代理用原生 `skill` 工具加载。 +- 供其他 OpenCode 实例使用的可选 HTTP 目录：`"skills": ["http://127.0.0.1:4747/skills/"]`（提供 `/skills/index.json` 与 `/skills//.md` — 与 UI 路径分开）。 +- REST：`GET/POST /api/skills`，`GET/PUT/DELETE /api/skills/:id`。 -经验法则：若是持久的项目指令，放入 AGENTS.md；若是从实际工作中增长的上下文，让记忆（或自动捕获）来保存。 +### 健康统计 + +Web UI 的 **Stats** 选项卡（`/stats`）一眼展示记忆系统健康状况：按范围合计、带过期/缺失分片警告与同标签重复代理的每分片记忆计数、当前用户画像版本，以及从 `~/.opencode-mem/` 中插件结构化日志解析出的 14 天活动序列（捕获、跳过的捕获、画像/压缩注入，以及按消息分桶的错误）。只读 — `GET /api/stats` — 若某数据库不可用则按区块降级，以便在事故期间仍能继续报告。 ### 基于提示的智能记忆提取 @@ -219,6 +235,29 @@ memory({ mode: "import", inputPath: "./memories.json" }); 插件在首次启动时会在此路径创建完整的注释模板。有关每项设置与注释，参见 [`opencode-mem.example.jsonc`](../../opencode-mem.example.jsonc)。 +### Markdown vault 后端（`memoryBackend`） + +默认情况下，记忆仅存放在 `storagePath` 下的 Turso 中。也可选将**通用 Markdown 文件夹**设为事实来源（兼容 Obsidian/Raneto 的纯 `.md` 文件 — 并非 Obsidian 专用集成）： + +```jsonc +{ + "memoryBackend": "markdown", + "markdownPath": "~/Documents/LLM-Wiki", +} +``` + +| 键 | 默认 | 作用 | +| --------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- | +| `memoryBackend` | `"database"` | `"database"` 将内容保存在 Turso。`"markdown"` 将 `markdownPath` 下所有 `.md` 文件作为事实来源。 | +| `markdownPath` | — | `memoryBackend` 为 `"markdown"` 时必填。vault 文件夹的绝对路径或 `~/…`。没有单独的记忆子文件夹 — 该路径_就是_存储本身。 | + +启用 Markdown 模式时： + +- 插件创建的记忆以 `{id}.md` 写入，含 YAML frontmatter + 正文。 +- 文件夹中已有笔记（任意 Markdown 页面风格）会被导入/索引；Turso 仅作为可重建的语义搜索索引。 +- 监视文件新增/编辑/删除并重新索引；Web UI 仅在此模式下显示 **Markdown** 侧边栏页（状态、文件列表、重新索引）。 +- 切换到 Markdown 会从文件夹重建索引 — 没有对应文件的仅数据库行会被丢弃。若需保留旧数据库记忆，请先用 `memory export` 导出。 + ### 聊天消息捕获与注入（`chatMessage`） 这些设置位于 `~/.config/opencode/opencode-mem.jsonc` 中的 `chatMessage` 键下：