Skill: xiaocaijic/a-mem-memory-organization (version 1.0.0)

--- name: a-mem-memory-organization description: Organize project, agent, or user memory using an A-MEM-style workflow with structured notes, semantic tags, contextual summaries, explicit links, and lightweight memory evolution. Use when Codex or OpenClaw needs to store long-term memory, maintain project context across sessions, build a memory file or memory store, retrieve relevant historical facts, or improve memory quality beyond flat append-only notes. --- # A-MEM Memory Organization Use this skill to turn raw observations into structured memory notes that are easier to retrieve, connect, and refine over time. ## Quick Start When the user asks to "remember", "keep context", "build memory", "organize knowledge", "create long-term memory", or "make the agent learn from history", do the following: 1. Capture the new memory as a note with `content`, `context`, `keywords`, `tags`, `category`, `timestamp`, and `links`. 2. Search existing memory for semantically related notes before writing the new note. 3. Link the new note to the strongest neighbors if the relationship is concrete. 4. Prefer updating tags/context only when the new evidence genuinely improves the older note. 5. Keep memory atomic. Split unrelated facts into separate notes. ## Note Format Represent each memory note with this schema: ```json { "id": "uuid-or-stable-id", "content": "Atomic fact, preference, event, or lesson learned.", "context": "One sentence explaining the situation, domain, or why the note matters.", "keywords": ["specific terms", "entities", "concepts"], "tags": ["broader-category", "retrieval-label"], "category": "Preference | Project | Decision | Fact | Workflow | Bug | Research", "timestamp": "YYYYMMDDHHmm", "links": ["related-note-id"], "source": "optional source or conversation anchor" } ``` If the surrounding system has no formal database yet, store notes in a Markdown or JSON memory file using the same fields. ## Write Workflow Use this write workflow whenever adding memory: 1. Normalize the user input into one atomic note. 2. Generate 3-6 precise `keywords`. 3. Generate 2-5 broader `tags`. 4. Write a compact `context` sentence that explains why the memory matters. 5. Search for related notes using the combined retrieval text: ```text content: ... context: ... keywords: ... tags: ... ``` 6. Link only to genuinely related memories. Avoid link spam. 7. If the new note sharpens an older note, update the older note conservatively. ## Retrieval Workflow When answering from memory or selecting context for future work: 1. Expand the query into both a literal form and a semantic form. 2. Retrieve using the combined note text, not raw content alone. 3. Prefer topically relevant and specific notes over vaguely similar ones. 4. Include linked neighbors only when they help answer the task. 5. If there is noise, rerank manually by: exact entity overlap, stronger contextual match, recency when the information is time-sensitive, explicit links from already-relevant notes. ## Evolution Rules Apply memory evolution carefully. The goal is refinement, not constant rewriting. Safe evolution operations: - Add a missing tag that improves retrieval. - Clarify context when a later note disambiguates the old one. - Add a link between notes with a clear relationship. - Mark a note obsolete if later evidence supersedes it. Avoid: - rewriting old notes based on weak similarity, - merging unrelated memories, - broadening tags until everything looks related, - losing the original fact while summarizing. If uncertain, store a new note and link it instead of mutating old notes. ## What To Build In Practice If the user wants this skill "made real" inside a project, choose the lightest form that matches the repo: - For a documentation-first repo: create `memory/notes.json` or `memory/notes.md`. - For an app repo: add a memory module plus persistence layer. - For an agent repo: add note construction, retrieval, linking, and evolution hooks around the agent loop. - For a coding assistant: maintain durable notes for project decisions, preferences, recurring bugs, and environment facts. ## Output Conventions When you use this skill during a task: - Tell the user what memory structure you are creating or updating. - Show the proposed note fields if the user is designing the system. - If implementing code, keep the data model explicit and testable. - If no storage exists yet, propose a minimal file-based memory store first. ## References Read [references/memory-patterns.md](references/memory-patterns.md) when you need: - examples of good and bad note construction, - category and tag heuristics, - guidance on conservative memory evolution, - suggestions for integrating this pattern into an agent loop.

path: agents/openai.yaml
content: interface:
  display_name: "A-MEM Memory Organization"
  short_description: "Organize durable notes with links and evolution."
  default_prompt: "Use $a-mem-memory-organization to structure this project's memory into durable notes with links and conservative evolution."

policy:
  allow_implicit_invocation: true


path: references/memory-patterns.md
content: # Memory Patterns

## Good Note Construction

Good notes are:

- atomic,
- specific,
- retrievable,
- linkable,
- easy to update conservatively.

Example:

```json
{
  "content": "The user prefers concise technical explanations and dislikes repetitive UI wording.",
  "context": "Communication preference for future coding and product responses.",
  "keywords": ["concise explanations", "technical writing", "UI wording"],
  "tags": ["preference", "communication", "ui-ux"],
  "category": "Preference"
}
```

Bad version:

```json
{
  "content": "The user said some things about style and also memory and maybe UI preferences.",
  "context": "General",
  "keywords": [],
  "tags": []
}
```

## Tag Heuristics

Use `keywords` for precise terms and entities.

Use `tags` for broader retrieval classes such as:

- `preference`
- `project-context`
- `decision`
- `bug`
- `research`
- `workflow`
- `architecture`
- `tooling`
- `ui-ux`
- `evaluation`

Do not create too many synonymous tags. Prefer a stable small vocabulary.

## Category Heuristics

Useful default categories:

- `Preference`
- `Project`
- `Decision`
- `Fact`
- `Workflow`
- `Bug`
- `Research`

## Linking Rules

Add links when:

- two notes refer to the same entity or subsystem,
- one note is a consequence of another,
- one note refines or supersedes another,
- one note is repeatedly retrieved alongside another.

Do not add links only because embeddings are vaguely similar.

## Conservative Evolution

Prefer these strategies in order:

1. Add a new note.
2. Link it to relevant prior notes.
3. Update tags/context on an older note only if confidence is high.
4. Mark older notes as superseded instead of overwriting the original claim.

This reduces semantic drift and memory pollution.

## Minimal Agent Integration

For an agent loop, integrate memory in four places:

1. Before response generation: retrieve relevant notes.
2. After response/tool completion: extract durable observations.
3. Before persistence: enrich note fields and search for neighbors.
4. Periodically: run conservative evolution over high-confidence clusters.

## Minimal File-Based Storage

If no DB exists yet, store notes in:

- `memory/notes.json`

Suggested layout:

```json
{
  "notes": [
    {
      "id": "note-001",
      "content": "Project uses FastAPI for the backend.",
      "context": "Repository architecture decision.",
      "keywords": ["FastAPI", "backend", "architecture"],
      "tags": ["project-context", "architecture", "backend"],
      "category": "Project",
      "timestamp": "202603161100",
      "links": []
    }
  ]
}
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)