Skip to content
Back to search

shared-memory-vault

SkillWorks with Claude CodeGitHub

A memory governance engine for multi-agent cloud knowledge bases — one knowledge base shared by every agent and every device, with consistency guaranteed. Nine automations on a shared Markdown knowledge base: ① session archiving & indexing ② incremental update decisions (diff + changelog) ③ provenance / confidence tagging ④ periodic reflection ⑤ write-after change awareness ⑥ semantic retrieval ⑦ cross-project memory linking (A-MEM style) ⑧ forgetting-curve scoring (MemoryBank style) ⑨ governance benchmark. One-command bootstrap generates the knowledge-base skeleton; governance actions fire automatically across the session lifecycle. All scripts are pure Python standard library with zero third-party dependencies, runnable standalone or on a schedule. Trigger words: shared memory, multi-agent collaboration, cross-device knowledge base, consistency, knowledge base governance, memory archiving, incremental update, provenance, reflection, memory linking, forgetting curve, governance benchmark, vault init, memory retrieval.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/songs-aaa--shared-memory-vault/badge.svg)](/listings/songs-aaa--shared-memory-vault)

HTML

<a href="/listings/songs-aaa--shared-memory-vault"><img src="/api/listings/songs-aaa--shared-memory-vault/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 1. Install the skill
cp -r shared-memory-vault ~/.workbuddy/skills/

# 2. Bootstrap a knowledge base skeleton in any cloud-synced directory
bash ~/.workbuddy/skills/shared-memory-vault/scripts/vault-init.sh --dir "~/MyCloud/KnowledgeBase"

# 3. Agents then follow the lifecycle SOP in SKILL.md automatically

The generated skeleton:

KnowledgeBase/
├── MOC.md                navigation home
├── dashboard.md          aggregated dashboard
├── user memory/          protocol zone (five iron rules + frontmatter spec)
├── work memory/          project memory (logs / notes / reflections)
├── context/              session blackboard (one CONTEXT.md per session) + archive + index
├── references/           knowledge assets (layered: notes / learning / work / reading)
├── _templates/           templates
└── skill&tool/           skills + tools

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 127 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: shared-memory-vault
  3. description: A memory governance engine for multi-agent cloud knowledge bases — one knowledge base shared by every agent and every device, with consistency guaranteed. Nine automations on a shared Markdown knowledge base: ① session archiving & indexing ② incremental update decisions (diff + changelog) ③ provenance / confidence tagging ④ periodic reflection ⑤ write-after change awareness ⑥ semantic retrieval ⑦ cross-project memory linking (A-MEM style) ⑧ forgetting-curve scoring (MemoryBank style) ⑨ governance benchmark. One-command bootstrap generates the knowledge-base skeleton; governance actions fire automatically across the session lifecycle. All scripts are pure Python standard library with zero third-party dependencies, runnable standalone or on a schedule. Trigger words: shared memory, multi-agent collaboration, cross-device knowledge base, consistency, knowledge base governance, memory archiving, incremental update, provenance, reflection, memory linking, forgetting curve, governance benchmark, vault init, memory retrieval.
  4. agent_created: true
  5. ---
  6. # shared-memory-vault — Multi-Agent Memory Governance Engine
  7. > Packages "session blackboard + layered knowledge + nine governance automations" into a self-bootstrapping, long-running, pure-Markdown memory governance layer.
  8. > Any agent using this skill can build a shared multi-agent knowledge base on any file-sync directory and automatically gain nine governance capabilities.
  9. ## Shared knowledge-base root (user-defined)
  10. ```
  11. Vault = <your cloud-synced directory> (any cloud/sync drive, or any local synced folder)
  12. ```
  13. > How to recognize a knowledge-base root: the directory contains both a navigation home (`MOC.md` or equivalent) and a `user memory/` folder.
  14. > The carrier is vendor-agnostic — pure Markdown files only; cross-device sync is the user's choice.
  15. ## Core structure (machine zone / human zone)
  16. | Zone | Ownership | Content | Governance rule |
  17. |---|---|---|---|
  18. | `user memory/` | machine | protocol (AGENT_PROTOCOL + MEMORY + FRONTMATTER_SPEC) | the highest authority for all behavior |
  19. | `work memory/<sessionID>/` | machine | daily log (append) + project notes + reflections | one per session |
  20. | `context/<sessionID>/` | machine | session blackboard CONTEXT.md (collaboration core) | 3-turn compression; archiving per ① |
  21. | `context/_archive/` | machine | completed + expired sessions | move-only, never delete |
  22. | `context/_index.md` | machine | index of all sessions (topic/status/updated) | read on open |
  23. | `references/` | human | knowledge assets (layered, see below) | **readable; writing requires user authorization** |
  24. | `_templates/` `_attachments/` `other/` | human | templates / attachments / misc | read-only by default |
  25. ### references layered knowledge (four categories)
  26. ```
  27. references/
  28. ├── notes/ raw layer: original study/work notes (categorized by topic) ← source of truth
  29. ├── learning/ learning layer: distilled notes → topic libraries + theory traces
  30. ├── work/ work layer: work-material distillation → project-specific + general methodology
  31. └── reading/ reading layer: book-list distillation → topic categories
  32. ```
  33. > Layers progress and cross-reference each other; libraries interconnect via wikilinks so the graph grows.
  34. ## Nine governance automations
  35. > Each = "what action + which script + when it fires". Scripts use only the Python standard library and live in this skill's `scripts/`.
  36. ### ① Session archiving & indexing
  37. - Action: sessions with `status=done` whose `updated` is older than a threshold (default 30 days) are moved into `context/_archive/` (**move-only, never delete**); rebuild `context/_index.md`.
  38. - Scripts: `vault-archive.py` (archive), `vault-index.py` (index).
  39. - Trigger: on open + optional schedule. Three tiers: active (HOT) / done ≤ threshold (WARM) / archived (COLD).
  40. ### ② Incremental update decisions (replaces full overwrite)
  41. - Action: before compression, judge each item of the 8 sections as `+` add / `~` modify / `-` delete / `·` NOOP; write a "## Change Log" (keep latest 5); if someone else already changed it (newer `updated`), re-apply your diff on their latest version.
  42. - Red line: `-` only removes "items you wrote this session that are now stale"; others' todos default to `·` (keep).
  43. - Script: `context-update.py` (`log` records a change / `merge` checks conflict).
  44. ### ③ Provenance / confidence tagging (prevents shared misconception)
  45. - Action: prefix key facts and decisions with `[U]` user-stated / `[I]` agent-inferred / `[E]` external-system (read-only) / `[D]` decision (with rationale); inferences get `confidence: high|medium|low`; low-confidence items are treated only as "hypothesis to verify", never as established fact.
  46. - Script: `provenance-check.py` (audits for missing/low-confidence provenance).
  47. ### ④ Periodic reflection (compression → abstraction)
  48. - Action: at milestones / session end, read multiple logs + related CONTEXT, and write a reflection into `work memory/<project>/MEMORY.md` under `## Reflection`. Four elements: patterns / lessons / reusable decisions / hints for the next agent.
  49. - Script: `reflect.py` (aggregates logs + generates a reflection skeleton).
  50. - Trigger: milestone / session end / schedule.
  51. ### ⑤ Write-after change awareness (blackboard)
  52. - Action: after each CONTEXT.md overwrite, `vault-index.py` updates the `_index.md` row `updated` + appends `context/_changes.log` (NDJSON, one `{ts,session,action,target}` per line).
  53. - Read order on open: protocol → dashboard (with recent changes) → this session's CONTEXT.
  54. ### ⑥ Semantic retrieval
  55. - L1 (zero-dependency): `search.py` filters by frontmatter (`--topic/--status/--since`), enough for 100–200 sessions.
  56. - L2 (optional, local vectors): local embeddings + a vector store (multilingual model); index artifacts are not committed or dual-written.
  57. ### ⑦ Cross-project memory linking (A-MEM style)
  58. - Action: scan `work memory/` MEMORY.md files and link similar sessions via character-bigram Jaccard similarity, writing each note's `## Related Memories` section + a global `work memory/_links.md`.
  59. - Value: breaks "each project's memory is isolated", making cross-project experience retrievable.
  60. - Script: `link-memory.py` (idempotent; re-runs don't duplicate).
  61. ### ⑧ Forgetting-curve scoring (MemoryBank style)
  62. - Action: compute a retention score as `importance × exp(-decay_rate × days since last access) × frequency boost`; below threshold → suggest archiving (move-only, keep original).
  63. - Replaces "fixed-day cutoff": high importance decays slowly, low importance decays fast, frequent access resists forgetting.
  64. - Script: `decay-score.py` (outputs ranking + archive suggestions).
  65. - Optional frontmatter: `importance`, `last_access`, `access_count`.
  66. ### ⑨ Governance benchmark
  67. - Action: compute governance health (provenance coverage / archive timeliness / change-log coverage / reflection coverage / index completeness / linking coverage) → Governance Score (0–100).
  68. - Value: quantifies "memory quality", filling the "no benchmark for governance" gap.
  69. - Script: `governance-score.py` (prints report, `--out` writes a file).
  70. ## Lifecycle SOP (every session runs this automatically)
  71. 1. **Open**: read the protocol trio → run `vault-index.py --vault <Vault>` to refresh the index → read `context/_index.md` + this session's CONTEXT.md (inherit if present).
  72. 2. **Set up**: create `context/<sessionID>/CONTEXT.md` (five frontmatter fields + 8 sections) + `work memory/<sessionID>/YYYY-MM-DD.md`; tag key facts with provenance per ③.
  73. 3. **Work**: every 3 turns, update CONTEXT.md incrementally with `context-update.py log` (keep frontmatter, bump `updated`, append change log).
  74. 4. **Distill**: at milestones/end, run `reflect.py` + `link-memory.py`; writing knowledge into references requires explicit user request.
  75. 5. **Handoff**: complete todos + decision rationale → set status to done → run `vault-archive.py` (if expired) + `vault-index.py` (write change log).
  76. ## Script cheatsheet
  77. | Script | Purpose | Example |
  78. |---|---|---|
  79. | `vault-init.sh` | bootstrap the skeleton | `bash scripts/vault-init.sh --dir <path>` |
  80. | `vault-index.py` | rebuild index + write change log | `python3 vault-index.py --vault <Vault>` |
  81. | `vault-archive.py` | archive expired sessions | `python3 vault-archive.py --vault <Vault> --days 30` |
  82. | `context-update.py` | incremental update / changelog / merge | `python3 context-update.py --context <path> log --mark + --section todo --summary "..."` |
  83. | `provenance-check.py` | provenance audit | `python3 provenance-check.py --vault <Vault>` |
  84. | `reflect.py` | reflection generation | `python3 reflect.py --work <dir> --out <file>` |
  85. | `search.py` | frontmatter retrieval | `python3 search.py --vault <Vault> --status done --since 7` |
  86. | `link-memory.py` | cross-project linking | `python3 link-memory.py --vault <Vault> --threshold 0.15` |
  87. | `decay-score.py` | forgetting-curve scoring | `python3 decay-score.py --vault <Vault> --score-threshold 0.2` |
  88. | `governance-score.py` | governance benchmark | `python3 governance-score.py --vault <Vault> --out report.md` |
  89. ## Five iron rules (apply to every action)
  90. 1. Never build a private memory/knowledge base — write everything to the shared repository
  91. 2. `references/` is readable; writing requires user authorization
  92. 3. External systems (collaboration platforms / online docs / email) are read-only
  93. 4. Never touch personal directories
  94. 5. Before any batch write/edit/delete (>1 item), show the detailed list and get confirmation
  95. ## Install & bootstrap
  96. 1. Install this skill into your agent's skills directory (e.g. `~/.workbuddy/skills/shared-memory-vault/`).
  97. 2. Bootstrap: `bash scripts/vault-init.sh --dir "<your cloud-synced directory>"` generates the skeleton (protocol + templates + index) in one command.
  98. 3. From then on, each session follows the lifecycle SOP; optionally schedule archiving / reflection / linking / scoring / retrieval.
README.md · README · 186 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # shared-memory-vault
  2. > **One knowledge base, shared by every agent and every device.** A memory governance engine for multi-agent cloud knowledge bases — collaborate without context loss, access from any device, consistency guaranteed.
  3. <p align="center">
  4. <img src="https://img.shields.io/badge/license-MIT-blue" alt="License">
  5. <img src="https://img.shields.io/badge/python-3.8%2B-blue" alt="Python">
  6. <img src="https://img.shields.io/badge/dependencies-zero-brightgreen" alt="Zero dependency">
  7. <img src="https://img.shields.io/badge/storage-pure%20Markdown-9cf" alt="Pure Markdown">
  8. <img src="https://img.shields.io/badge/platform-cross--platform-green" alt="Platform">
  9. </p>
  10. ---
  11. ## What it does
  12. This skill turns a plain cloud-synced Markdown directory into a **shared knowledge base for every agent and every device**, with three guarantees at its core:
  13. ### 🌐 Multi-agent collaboration
  14. Multiple AI agents share one knowledge base through a session-blackboard convention (`CONTEXT.md`). Any agent reads a single file and resumes the work from where another left off — no context loss, no drifting or contradictory decisions.
  15. ### 📱 Cross-device sharing
  16. The knowledge base is **pure Markdown on a cloud-synced directory** — no database, no server, no vendor lock-in. Open it from Mac, Windows, Linux, or mobile; the same knowledge base follows you everywhere.
  17. ### 🔒 Consistency guaranteed
  18. A **single source of truth**, not per-agent copies. Conflict handling (timestamp + `.bak`) and incremental updates keep every agent and every device reading the *same* consistent state, no matter who wrote last.
  19. ```mermaid
  20. %%{init: {'theme':'base','themeVariables':{'primaryColor':'#4F46E5','primaryTextColor':'#ffffff','primaryBorderColor':'#3730A3','lineColor':'#94A3B8','secondaryColor':'#EEF2FF','tertiaryColor':'#ECFDF5','clusterBkg':'#F8FAFC','clusterBorder':'#E2E8F0','fontFamily':'system-ui,sans-serif'}}}%%
  21. flowchart LR
  22. subgraph AG["Any agent"]
  23. A1["Agent A"]
  24. A2["Agent B"]
  25. A3["Agent C"]
  26. end
  27. subgraph DV["Any device"]
  28. D1["Mac"]
  29. D2["Windows"]
  30. D3["Mobile"]
  31. end
  32. KB["Cloud Knowledge Base<br/>single source of truth"]
  33. AG --> KB
  34. DV --> KB
  35. ```
  36. > **Zero infrastructure. Zero vendor lock-in. Zero third-party dependencies** — every script uses only the Python standard library.
  37. ---
  38. ## How it works
  39. ### Architecture
  40. ```mermaid
  41. %%{init: {'theme':'base','themeVariables':{'primaryColor':'#6366F1','primaryTextColor':'#ffffff','primaryBorderColor':'#4338CA','lineColor':'#94A3B8','secondaryColor':'#EEF2FF','tertiaryColor':'#ECFDF5','clusterBkg':'#F8FAFC','clusterBorder':'#E2E8F0','fontFamily':'system-ui,sans-serif'}}}%%
  42. flowchart TB
  43. subgraph H["Human Layer · optional · zero agent dependency"]
  44. UI["Knowledge Desktop<br/>graph · dashboard · navigation"]
  45. end
  46. subgraph M["Agent Machine Layer · protocol-governed"]
  47. direction LR
  48. C["Protocol Zone<br/>Five Iron Rules"]
  49. W["Project Memory<br/>logs · notes · reflections"]
  50. K["Session Blackboard<br/>CONTEXT.md"]
  51. S["Skills + Tools<br/>dual-write"]
  52. end
  53. subgraph D["Storage Layer · pure Markdown"]
  54. V["Cloud-synced directory<br/>any vendor · cross-device"]
  55. end
  56. H -. read-only .-> M
  57. M --> D
  58. ```
  59. - **Storage layer** — pure Markdown, a single source of truth, portable and versionable.
  60. - **Machine layer** — agents read and write the four machine zones, governed by a protocol and nine governance actions.
  61. - **Human layer** — an optional knowledge desktop for browsing; the agent workflow has zero dependency on it.
  62. ### Session lifecycle
  63. ```mermaid
  64. %%{init: {'theme':'base','themeVariables':{'primaryColor':'#059669','primaryTextColor':'#ffffff','primaryBorderColor':'#047857','lineColor':'#94A3B8','fontFamily':'system-ui,sans-serif'}}}%%
  65. flowchart LR
  66. A["① Open<br/>protocol + index"] --> B["② Set up<br/>CONTEXT + log"]
  67. B --> C["③ Work<br/>incremental update / 3 turns"]
  68. C --> D["④ Distill<br/>reflect + link"]
  69. D --> E["⑤ Handoff<br/>archive + changelog"]
  70. E -. next agent resumes via CONTEXT .-> A
  71. ```
  72. Nine governance actions fire automatically across the lifecycle:
  73. | # | Governance action | Script | Trigger |
  74. |---|---|---|---|
  75. | ① | Session archiving & indexing | `vault-archive.py` / `vault-index.py` | open / scheduled |
  76. | ② | Incremental updates (replace full overwrite) | `context-update.py` | every 3 turns |
  77. | ③ | Provenance & confidence tagging | `provenance-check.py` | on write / audit |
  78. | ④ | Periodic reflection | `reflect.py` | milestone / scheduled |
  79. | ⑤ | Write-after change awareness | `vault-index.py --notify` | after each overwrite |
  80. | ⑥ | Semantic retrieval | `search.py` | on query |
  81. | ⑦ | Cross-project memory linking (A-MEM style) | `link-memory.py` | milestone / scheduled |
  82. | ⑧ | Forgetting-curve scoring (MemoryBank style) | `decay-score.py` | before archiving |
  83. | ⑨ | Governance benchmark | `governance-score.py` | periodic / on demand |
  84. ---
  85. ## Quick start
  86. ```bash
  87. # 1. Install the skill
  88. cp -r shared-memory-vault ~/.workbuddy/skills/
  89. # 2. Bootstrap a knowledge base skeleton in any cloud-synced directory
  90. bash ~/.workbuddy/skills/shared-memory-vault/scripts/vault-init.sh --dir "~/MyCloud/KnowledgeBase"
  91. # 3. Agents then follow the lifecycle SOP in SKILL.md automatically
  92. ```
  93. The generated skeleton:
  94. ```
  95. KnowledgeBase/
  96. ├── MOC.md navigation home
  97. ├── dashboard.md aggregated dashboard
  98. ├── user memory/ protocol zone (five iron rules + frontmatter spec)
  99. ├── work memory/ project memory (logs / notes / reflections)
  100. ├── context/ session blackboard (one CONTEXT.md per session) + archive + index
  101. ├── references/ knowledge assets (layered: notes / learning / work / reading)
  102. ├── _templates/ templates
  103. └── skill&tool/ skills + tools
  104. ```
  105. ---
  106. ## Design rationale (academic grounding)
  107. Every design choice has a reference, not an arbitrary convention:
  108. | Design | Reference | Basis |
  109. |---|---|---|
  110. | Session blackboard + reflection + retrieval | [Generative Agents](https://arxiv.org/abs/2304.03442) | memory stream + reflection + weighted retrieval |
  111. | Tiered context paging | [MemGPT](https://arxiv.org/abs/2310.08560) | OS-style virtual context |
  112. | Incremental update decisions | [Mem0](https://arxiv.org/abs/2504.19413) | ADD/UPDATE/DELETE/NOOP pipeline |
  113. | Cross-project memory linking | [A-MEM](https://arxiv.org/abs/2502.12110) | Zettelkasten dynamic linking |
  114. | Forgetting-curve scoring | MemoryBank (cognitive science) | Ebbinghaus curve + importance weighting |
  115. | Built-in governance | [Always-On Agents Survey](https://arxiv.org/abs/2606.30306) | shared-memory governance, provenance |
  116. > Full reference list: [`references/research.md`](references/research.md).
  117. ---
  118. ## Core protocol
  119. **Five iron rules** (non-negotiable, apply to every action):
  120. 1. Never build a private memory/knowledge base — write everything to the shared repository
  121. 2. `references/` is readable; writing requires explicit user authorization
  122. 3. External systems (collaboration platforms / online docs / email) are read-only
  123. 4. Never touch personal directories
  124. 5. Before any batch write/edit/delete (>1 item), show the detailed list and get confirmation
  125. **Permission layering** — the machine zone (agent read/write) and the human zone (read-only by default) are strictly isolated, preventing agents from polluting the user's knowledge assets.
  126. ---
  127. ## Repository layout
  128. ```
  129. shared-memory-vault/
  130. ├── SKILL.md entry: governance protocol + lifecycle SOP + script cheatsheet
  131. ├── templates/ templates: protocol / CONTEXT / frontmatter / log / reflection / index
  132. ├── scripts/ automation engine (10 standard-library scripts)
  133. └── references/ design notes + academic references
  134. ```
  135. ---
  136. ## License
  137. [MIT License](LICENSE)
  138. ## Disclaimer
  139. This skill contains only **mechanisms + templates + scripts + academic references**. It contains no personal, professional, or study data of any user. Users choose their own knowledge-base content and sync carrier.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.