shared-memory-vault
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.
Badge for your README
Markdown
[](/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
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)
- ---
- name: shared-memory-vault
- 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.
- agent_created: true
- ---
- # shared-memory-vault — Multi-Agent Memory Governance Engine
- > Packages "session blackboard + layered knowledge + nine governance automations" into a self-bootstrapping, long-running, pure-Markdown memory governance layer.
- > Any agent using this skill can build a shared multi-agent knowledge base on any file-sync directory and automatically gain nine governance capabilities.
- ## Shared knowledge-base root (user-defined)
- ```
- Vault = <your cloud-synced directory> (any cloud/sync drive, or any local synced folder)
- ```
- > How to recognize a knowledge-base root: the directory contains both a navigation home (`MOC.md` or equivalent) and a `user memory/` folder.
- > The carrier is vendor-agnostic — pure Markdown files only; cross-device sync is the user's choice.
- ## Core structure (machine zone / human zone)
- | Zone | Ownership | Content | Governance rule |
- |---|---|---|---|
- | `user memory/` | machine | protocol (AGENT_PROTOCOL + MEMORY + FRONTMATTER_SPEC) | the highest authority for all behavior |
- | `work memory/<sessionID>/` | machine | daily log (append) + project notes + reflections | one per session |
- | `context/<sessionID>/` | machine | session blackboard CONTEXT.md (collaboration core) | 3-turn compression; archiving per ① |
- | `context/_archive/` | machine | completed + expired sessions | move-only, never delete |
- | `context/_index.md` | machine | index of all sessions (topic/status/updated) | read on open |
- | `references/` | human | knowledge assets (layered, see below) | **readable; writing requires user authorization** |
- | `_templates/` `_attachments/` `other/` | human | templates / attachments / misc | read-only by default |
- ### references layered knowledge (four categories)
- ```
- references/
- ├── notes/ raw layer: original study/work notes (categorized by topic) ← source of truth
- ├── learning/ learning layer: distilled notes → topic libraries + theory traces
- ├── work/ work layer: work-material distillation → project-specific + general methodology
- └── reading/ reading layer: book-list distillation → topic categories
- ```
- > Layers progress and cross-reference each other; libraries interconnect via wikilinks so the graph grows.
- ## Nine governance automations
- > Each = "what action + which script + when it fires". Scripts use only the Python standard library and live in this skill's `scripts/`.
- ### ① Session archiving & indexing
- - 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`.
- - Scripts: `vault-archive.py` (archive), `vault-index.py` (index).
- - Trigger: on open + optional schedule. Three tiers: active (HOT) / done ≤ threshold (WARM) / archived (COLD).
- ### ② Incremental update decisions (replaces full overwrite)
- - 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.
- - Red line: `-` only removes "items you wrote this session that are now stale"; others' todos default to `·` (keep).
- - Script: `context-update.py` (`log` records a change / `merge` checks conflict).
- ### ③ Provenance / confidence tagging (prevents shared misconception)
- - 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.
- - Script: `provenance-check.py` (audits for missing/low-confidence provenance).
- ### ④ Periodic reflection (compression → abstraction)
- - 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.
- - Script: `reflect.py` (aggregates logs + generates a reflection skeleton).
- - Trigger: milestone / session end / schedule.
- ### ⑤ Write-after change awareness (blackboard)
- - 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).
- - Read order on open: protocol → dashboard (with recent changes) → this session's CONTEXT.
- ### ⑥ Semantic retrieval
- - L1 (zero-dependency): `search.py` filters by frontmatter (`--topic/--status/--since`), enough for 100–200 sessions.
- - L2 (optional, local vectors): local embeddings + a vector store (multilingual model); index artifacts are not committed or dual-written.
- ### ⑦ Cross-project memory linking (A-MEM style)
- - 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`.
- - Value: breaks "each project's memory is isolated", making cross-project experience retrievable.
- - Script: `link-memory.py` (idempotent; re-runs don't duplicate).
- ### ⑧ Forgetting-curve scoring (MemoryBank style)
- - Action: compute a retention score as `importance × exp(-decay_rate × days since last access) × frequency boost`; below threshold → suggest archiving (move-only, keep original).
- - Replaces "fixed-day cutoff": high importance decays slowly, low importance decays fast, frequent access resists forgetting.
- - Script: `decay-score.py` (outputs ranking + archive suggestions).
- - Optional frontmatter: `importance`, `last_access`, `access_count`.
- ### ⑨ Governance benchmark
- - Action: compute governance health (provenance coverage / archive timeliness / change-log coverage / reflection coverage / index completeness / linking coverage) → Governance Score (0–100).
- - Value: quantifies "memory quality", filling the "no benchmark for governance" gap.
- - Script: `governance-score.py` (prints report, `--out` writes a file).
- ## Lifecycle SOP (every session runs this automatically)
- 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).
- 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 ③.
- 3. **Work**: every 3 turns, update CONTEXT.md incrementally with `context-update.py log` (keep frontmatter, bump `updated`, append change log).
- 4. **Distill**: at milestones/end, run `reflect.py` + `link-memory.py`; writing knowledge into references requires explicit user request.
- 5. **Handoff**: complete todos + decision rationale → set status to done → run `vault-archive.py` (if expired) + `vault-index.py` (write change log).
- ## Script cheatsheet
- | Script | Purpose | Example |
- |---|---|---|
- | `vault-init.sh` | bootstrap the skeleton | `bash scripts/vault-init.sh --dir <path>` |
- | `vault-index.py` | rebuild index + write change log | `python3 vault-index.py --vault <Vault>` |
- | `vault-archive.py` | archive expired sessions | `python3 vault-archive.py --vault <Vault> --days 30` |
- | `context-update.py` | incremental update / changelog / merge | `python3 context-update.py --context <path> log --mark + --section todo --summary "..."` |
- | `provenance-check.py` | provenance audit | `python3 provenance-check.py --vault <Vault>` |
- | `reflect.py` | reflection generation | `python3 reflect.py --work <dir> --out <file>` |
- | `search.py` | frontmatter retrieval | `python3 search.py --vault <Vault> --status done --since 7` |
- | `link-memory.py` | cross-project linking | `python3 link-memory.py --vault <Vault> --threshold 0.15` |
- | `decay-score.py` | forgetting-curve scoring | `python3 decay-score.py --vault <Vault> --score-threshold 0.2` |
- | `governance-score.py` | governance benchmark | `python3 governance-score.py --vault <Vault> --out report.md` |
- ## Five iron rules (apply to every action)
- 1. Never build a private memory/knowledge base — write everything to the shared repository
- 2. `references/` is readable; writing requires user authorization
- 3. External systems (collaboration platforms / online docs / email) are read-only
- 4. Never touch personal directories
- 5. Before any batch write/edit/delete (>1 item), show the detailed list and get confirmation
- ## Install & bootstrap
- 1. Install this skill into your agent's skills directory (e.g. `~/.workbuddy/skills/shared-memory-vault/`).
- 2. Bootstrap: `bash scripts/vault-init.sh --dir "<your cloud-synced directory>"` generates the skeleton (protocol + templates + index) in one command.
- 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)
- # shared-memory-vault
- > **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.
- <p align="center">
- <img src="https://img.shields.io/badge/license-MIT-blue" alt="License">
- <img src="https://img.shields.io/badge/python-3.8%2B-blue" alt="Python">
- <img src="https://img.shields.io/badge/dependencies-zero-brightgreen" alt="Zero dependency">
- <img src="https://img.shields.io/badge/storage-pure%20Markdown-9cf" alt="Pure Markdown">
- <img src="https://img.shields.io/badge/platform-cross--platform-green" alt="Platform">
- </p>
- ---
- ## What it does
- 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:
- ### 🌐 Multi-agent collaboration
- 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.
- ### 📱 Cross-device sharing
- 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.
- ### 🔒 Consistency guaranteed
- 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.
- ```mermaid
- %%{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'}}}%%
- flowchart LR
- subgraph AG["Any agent"]
- A1["Agent A"]
- A2["Agent B"]
- A3["Agent C"]
- end
- subgraph DV["Any device"]
- D1["Mac"]
- D2["Windows"]
- D3["Mobile"]
- end
- KB["Cloud Knowledge Base<br/>single source of truth"]
- AG --> KB
- DV --> KB
- ```
- > **Zero infrastructure. Zero vendor lock-in. Zero third-party dependencies** — every script uses only the Python standard library.
- ---
- ## How it works
- ### Architecture
- ```mermaid
- %%{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'}}}%%
- flowchart TB
- subgraph H["Human Layer · optional · zero agent dependency"]
- UI["Knowledge Desktop<br/>graph · dashboard · navigation"]
- end
- subgraph M["Agent Machine Layer · protocol-governed"]
- direction LR
- C["Protocol Zone<br/>Five Iron Rules"]
- W["Project Memory<br/>logs · notes · reflections"]
- K["Session Blackboard<br/>CONTEXT.md"]
- S["Skills + Tools<br/>dual-write"]
- end
- subgraph D["Storage Layer · pure Markdown"]
- V["Cloud-synced directory<br/>any vendor · cross-device"]
- end
- H -. read-only .-> M
- M --> D
- ```
- - **Storage layer** — pure Markdown, a single source of truth, portable and versionable.
- - **Machine layer** — agents read and write the four machine zones, governed by a protocol and nine governance actions.
- - **Human layer** — an optional knowledge desktop for browsing; the agent workflow has zero dependency on it.
- ### Session lifecycle
- ```mermaid
- %%{init: {'theme':'base','themeVariables':{'primaryColor':'#059669','primaryTextColor':'#ffffff','primaryBorderColor':'#047857','lineColor':'#94A3B8','fontFamily':'system-ui,sans-serif'}}}%%
- flowchart LR
- A["① Open<br/>protocol + index"] --> B["② Set up<br/>CONTEXT + log"]
- B --> C["③ Work<br/>incremental update / 3 turns"]
- C --> D["④ Distill<br/>reflect + link"]
- D --> E["⑤ Handoff<br/>archive + changelog"]
- E -. next agent resumes via CONTEXT .-> A
- ```
- Nine governance actions fire automatically across the lifecycle:
- | # | Governance action | Script | Trigger |
- |---|---|---|---|
- | ① | Session archiving & indexing | `vault-archive.py` / `vault-index.py` | open / scheduled |
- | ② | Incremental updates (replace full overwrite) | `context-update.py` | every 3 turns |
- | ③ | Provenance & confidence tagging | `provenance-check.py` | on write / audit |
- | ④ | Periodic reflection | `reflect.py` | milestone / scheduled |
- | ⑤ | Write-after change awareness | `vault-index.py --notify` | after each overwrite |
- | ⑥ | Semantic retrieval | `search.py` | on query |
- | ⑦ | Cross-project memory linking (A-MEM style) | `link-memory.py` | milestone / scheduled |
- | ⑧ | Forgetting-curve scoring (MemoryBank style) | `decay-score.py` | before archiving |
- | ⑨ | Governance benchmark | `governance-score.py` | periodic / on demand |
- ---
- ## Quick start
- ```bash
- # 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
- ```
- ---
- ## Design rationale (academic grounding)
- Every design choice has a reference, not an arbitrary convention:
- | Design | Reference | Basis |
- |---|---|---|
- | Session blackboard + reflection + retrieval | [Generative Agents](https://arxiv.org/abs/2304.03442) | memory stream + reflection + weighted retrieval |
- | Tiered context paging | [MemGPT](https://arxiv.org/abs/2310.08560) | OS-style virtual context |
- | Incremental update decisions | [Mem0](https://arxiv.org/abs/2504.19413) | ADD/UPDATE/DELETE/NOOP pipeline |
- | Cross-project memory linking | [A-MEM](https://arxiv.org/abs/2502.12110) | Zettelkasten dynamic linking |
- | Forgetting-curve scoring | MemoryBank (cognitive science) | Ebbinghaus curve + importance weighting |
- | Built-in governance | [Always-On Agents Survey](https://arxiv.org/abs/2606.30306) | shared-memory governance, provenance |
- > Full reference list: [`references/research.md`](references/research.md).
- ---
- ## Core protocol
- **Five iron rules** (non-negotiable, apply to every action):
- 1. Never build a private memory/knowledge base — write everything to the shared repository
- 2. `references/` is readable; writing requires explicit user authorization
- 3. External systems (collaboration platforms / online docs / email) are read-only
- 4. Never touch personal directories
- 5. Before any batch write/edit/delete (>1 item), show the detailed list and get confirmation
- **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.
- ---
- ## Repository layout
- ```
- shared-memory-vault/
- ├── SKILL.md entry: governance protocol + lifecycle SOP + script cheatsheet
- ├── templates/ templates: protocol / CONTEXT / frontmatter / log / reflection / index
- ├── scripts/ automation engine (10 standard-library scripts)
- └── references/ design notes + academic references
- ```
- ---
- ## License
- [MIT License](LICENSE)
- ## Disclaimer
- 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 inFree to use. If it’s helped, pass it on.