opensite-ai/opensite-skills / memory
memory
VerifiedThe OpenSite persistent long-term memory store. Provides a hierarchical filesystem tree for all agent memories across four cognitive layers: episodic (session history), semantic (project/tech/user knowledge), procedural (decisions, workflows, conventions), and working (active session state). Use this skill to directly read, write, search, or inspect memory entries. For automated session capture use memory-write; for context retrieval before a task use memory-recall; for periodic maintenance use memory-consolidate.
| File | Kind | Size |
|---|---|---|
| .gitignore | other | 780 B |
| README.md | markdown | 1.4 KB |
| SKILL.md | skill md | 5.2 KB |
| meta/.gitkeep | other | 0 B |
| scripts/consolidate.py | script | 7.4 KB |
| scripts/list_memories.py | script | 2.4 KB |
| scripts/search_memory.py | script | 7.6 KB |
| scripts/write_memory.py | script | 8.2 KB |
SKILL.md
View on GitHub---
name: memory
description: "The OpenSite persistent long-term memory store. Provides a hierarchical filesystem tree for all agent memories across four cognitive layers: episodic (session history), semantic (project/tech/user knowledge), procedural (decisions, workflows, conventions), and working (active session state). Use this skill to directly read, write, search, or inspect memory entries. For automated session capture use memory-write; for context retrieval before a task use memory-recall; for periodic maintenance use memory-consolidate."
allowed-tools: "Read, Write, Bash, Glob, Grep, Edit"
metadata:
version: 2.0.0
---
# Memory Store
You have access to the OpenSite persistent memory store — a hierarchical directory tree of
markdown files that persists knowledge across all sessions and AI engines.
## Store Location
The store lives at `{baseDir}/store/` relative to this skill. The canonical path is set by
the installing engine's symlink. All scripts use `Path(__file__).resolve()` so they always
find the store regardless of which engine invokes them.
## Memory Tree Structure
```
store/
├── episodic/
│ ├── sessions/ ← YYYY-MM-DD-{slug}.md per session
│ │ └── archive/ ← Monthly summaries of old sessions
│ └── events/ ← Significant milestones and breakthroughs
├── semantic/
│ ├── projects/ ← {project-name}/ subfolder per project
│ ├── people/ ← User preferences, collaborators, clients
│ ├── technologies/ ← Libraries, frameworks, versions, gotchas
│ └── domain/ ← Business / domain facts
├── procedural/
│ ├── workflows/ ← Step-by-step repeatable procedures
│ ├── decisions/ ← Architecture Decision Records (ADRs)
│ └── conventions/ ← Code style, naming rules, team patterns
└── working/
└── active.md ← Hot context for the current session only
```
## Memory Entry Format
Every memory file uses this structure:
```markdown
---
id: {8-char-uuid}
type: episodic|semantic|procedural|working
category: sessions|events|projects|people|technologies|domain|workflows|decisions|conventions|active
title: Human readable title
tags: [tag1, tag2, tag3]
project: project-name or null
created: YYYY-MM-DD
updated: YYYY-MM-DD
confidence: high|medium|low|archived
---
# Title
## Summary
1-3 sentence summary used for fast retrieval without reading the body.
## Content
Full memory content here.
```
## Common Operations
### Search for relevant memories
```bash
python {baseDir}/scripts/search_memory.py --query "rust axum" --type semantic
python {baseDir}/scripts/search_memory.py --query "deploy" --type procedural --limit 5
python {baseDir}/scripts/search_memory.py --type episodic --sort recency --limit 3
```
### Write a new memory entry
```bash
python {baseDir}/scripts/write_memory.py \
--type semantic \
--category technologies \
--title "Axum Tower Middleware Pattern" \
--content "When adding middleware in Axum 0.8+, use tower::ServiceBuilder..." \
--tags "rust,axum,middleware,tower" \
--project opensite-api
```
### Write multiline markdown safely
Use stdin or a file when the content includes markdown, code fences, backticks, or multiple paragraphs.
```bash
cat <<'EOF' | python {baseDir}/scripts/write_memory.py \
--type procedural \
--category decisions \
--title "ADR: Use Axum over Actix-Web" \
--content-stdin \
--tags "rust,axum,architecture,adr" \
--project opensite-api
## Context
Needed async HTTP framework...
## Decision
Axum...
## Rationale
...
EOF
```
### Write a procedural decision (ADR)
```bash
python {baseDir}/scripts/write_memory.py \
--type procedural \
--category decisions \
--title "ADR: Use Axum over Actix-Web" \
--content-file /tmp/axum-adr.md \
--tags "rust,axum,architecture,adr" \
--project opensite-api
```
### Read current working memory (active session state)
```bash
cat {baseDir}/store/working/active.md
```
### List all memories with summaries
```bash
python {baseDir}/scripts/list_memories.py --brief
python {baseDir}/scripts/list_memories.py --type procedural
```
### View full memory stats
```bash
python {baseDir}/scripts/search_memory.py --stats
```
## Memory Hygiene Rules
1. **One concept per file** — never bundle unrelated facts
2. **Summaries are mandatory** — they enable fast search without full reads
3. **Tags are required** — minimum 2, maximum 8 per entry
4. **Project field is required** when the memory is project-specific
5. **Confidence scoring** — mark `low` for inferred or uncertain facts
6. **Deduplication first** — search before writing to avoid duplicates
7. **Never hard-delete episodic memories** — set confidence to `archived` instead
## Standard Tag Taxonomy
```
Technology: rust, axum, rails, react, typescript, nextjs, tailwind, shadcn,
postgres, redis, fly-io, cloudflare, vercel, node, ruby, crystal
Task type: debugging, architecture, deployment, refactoring, api-design,
performance, security, testing, ci-cd
Quality: verified, inferred, deprecated, experimental, critical, temporary
Relation: decision, blocker, prerequisite, alternative, supersedes, adr
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |