universal-memory 0.2.0__tar.gz → 0.3.0__tar.gz

{universal_memory-0.2.0 → universal_memory-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: universal-memory
-Version: 0.2.0
+Version: 0.3.0
 Summary: Vendor-agnostic cognitive persistence layer for AI agents.
 Keywords: agent-memory,ai,ai-agents,agent-skills,claude-code,codex,context-engineering,developer-tools,llm,mcp,memory
 Author: Yan L. Amorelli
@@ -27,7 +27,7 @@ Project-URL: Repository, https://github.com/YanAmorelli/universal-memory
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="docs/assets/umem-logo-lockup.svg" alt="UMem logo" width="720">
+  <img src="https://raw.githubusercontent.com/YanAmorelli/universal-memory/main/docs/assets/umem-logo-lockup.svg" alt="UMem logo" width="720">
 </p>
 
 # Universal Memory (UMem)
@@ -42,7 +42,7 @@ A vendor-agnostic cognitive persistence layer for AI agents. Eliminate the "repe
 
 To see the core idea visually, check out the [Excalidraw design](https://excalidraw.com/#json=j3XjQIWMYEnkIzHpypuBb,rNJaVOECDGZ3WSuEYcCDjQ) or the proposal structure:
 
-![Universal Memory MVP Proposal](docs/assets/diagrams/UNIVERSAL-MEMORY-MVP-PROPOSAL.png)
+![Universal Memory MVP Proposal](https://raw.githubusercontent.com/YanAmorelli/universal-memory/main/docs/assets/diagrams/UNIVERSAL-MEMORY-MVP-PROPOSAL.png)
 
 ### Diagram Breakdown
 
@@ -171,21 +171,37 @@ umem context --scope project
 
 ### 4. Adopt or create an Agent Skill
 
-If a skill already exists in a native runtime directory, import it into UMEM and sync it
-back out to configured runtimes:
+If a skill already exists, choose the safest adoption path first. Use `adopt` for an
+existing `.umem/skills/<slug>` directory; use `import` for native runtime directories
+such as `.agents/skills/<slug>` and sync it back out to configured runtimes:
 
 ```bash
+umem skills adopt .umem/skills/review-protocol --scope project
 umem skills import .agents/skills/review-protocol --scope project --sync
 umem skills detail review-protocol
 ```
 
-If you are starting from scratch, create the canonical skill first:
+If you are starting from scratch, draft and publish it without native side effects:
 
 ```bash
-umem skills create \
+umem skills draft create \
   --name "Review Protocol" \
   --description "Reusable review workflow" \
   --trigger "when reviewing code"
+umem skills draft validate review-protocol
+umem skills publish review-protocol --format summary
+```
+
+For a one-step workflow, create the canonical skill. It is canonical-only by default;
+request sync explicitly when native runtime targets should be written:
+
+```bash
+umem skills create \
+  --name "Review Protocol" \
+  --description "Reusable review workflow" \
+  --trigger "when reviewing code" \
+  --format summary
+umem skills sync review-protocol --check-gitignore --format summary
 ```
 
 After editing `.umem/skills/review-protocol/SKILL.md`, refresh one runtime skill with:
@@ -291,7 +307,7 @@ your shell `PATH`.
 
 ## Managing Agent Skills
 
-You can create, import, list, inspect, and sync specialized behaviors:
+You can draft, create, adopt, import, validate, maintain, and sync specialized behaviors:
 ```bash
 # List all active skills
 umem skills list
@@ -299,14 +315,30 @@ umem skills list
 # Inspect one skill
 umem skills detail review-protocol
 
-# Create a new canonical skill
-umem skills create --name "Review Protocol" --description "Reusable review workflow"
+# Draft, validate, and publish without native runtime writes
+umem skills draft create --name "Review Protocol" --description "Reusable review workflow"
+umem skills draft validate review-protocol
+umem skills publish review-protocol
+
+# Create a new canonical skill and explicitly sync native targets
+umem skills create --name "Review Protocol" --description "Reusable review workflow" --sync
 
-# Adopt an existing native skill and distribute complete runtime copies
+# Adopt existing canonical work
+umem skills adopt .umem/skills/review-protocol --scope project
+
+# Import an existing native skill and distribute complete runtime copies
 umem skills import .agents/skills/review-protocol --scope project --sync
 
+# Validate and maintain canonical skills
+umem skills validate review-protocol
+umem skills canonical update review-protocol --file .umem/skills/review-protocol/SKILL.md
+umem skills rename review-protocol --slug review-checklist
+umem skills cleanup review-checklist --targets --format summary
+umem skills cleanup review-checklist --targets --apply
+umem skills repair --remove-orphan-targets --format summary
+
 # Synchronize one canonical skill into active native runtime folders
-umem skills sync review-protocol
+umem skills sync review-protocol --check-gitignore --format summary
 
 # Synchronize all active canonical skills during maintenance
 umem update --skills

{universal_memory-0.2.0 → universal_memory-0.3.0}/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/assets/umem-logo-lockup.svg" alt="UMem logo" width="720">
+  <img src="https://raw.githubusercontent.com/YanAmorelli/universal-memory/main/docs/assets/umem-logo-lockup.svg" alt="UMem logo" width="720">
 </p>
 
 # Universal Memory (UMem)
@@ -14,7 +14,7 @@ A vendor-agnostic cognitive persistence layer for AI agents. Eliminate the "repe
 
 To see the core idea visually, check out the [Excalidraw design](https://excalidraw.com/#json=j3XjQIWMYEnkIzHpypuBb,rNJaVOECDGZ3WSuEYcCDjQ) or the proposal structure:
 
-![Universal Memory MVP Proposal](docs/assets/diagrams/UNIVERSAL-MEMORY-MVP-PROPOSAL.png)
+![Universal Memory MVP Proposal](https://raw.githubusercontent.com/YanAmorelli/universal-memory/main/docs/assets/diagrams/UNIVERSAL-MEMORY-MVP-PROPOSAL.png)
 
 ### Diagram Breakdown
 
@@ -143,21 +143,37 @@ umem context --scope project
 
 ### 4. Adopt or create an Agent Skill
 
-If a skill already exists in a native runtime directory, import it into UMEM and sync it
-back out to configured runtimes:
+If a skill already exists, choose the safest adoption path first. Use `adopt` for an
+existing `.umem/skills/<slug>` directory; use `import` for native runtime directories
+such as `.agents/skills/<slug>` and sync it back out to configured runtimes:
 
 ```bash
+umem skills adopt .umem/skills/review-protocol --scope project
 umem skills import .agents/skills/review-protocol --scope project --sync
 umem skills detail review-protocol
 ```
 
-If you are starting from scratch, create the canonical skill first:
+If you are starting from scratch, draft and publish it without native side effects:
 
 ```bash
-umem skills create \
+umem skills draft create \
   --name "Review Protocol" \
   --description "Reusable review workflow" \
   --trigger "when reviewing code"
+umem skills draft validate review-protocol
+umem skills publish review-protocol --format summary
+```
+
+For a one-step workflow, create the canonical skill. It is canonical-only by default;
+request sync explicitly when native runtime targets should be written:
+
+```bash
+umem skills create \
+  --name "Review Protocol" \
+  --description "Reusable review workflow" \
+  --trigger "when reviewing code" \
+  --format summary
+umem skills sync review-protocol --check-gitignore --format summary
 ```
 
 After editing `.umem/skills/review-protocol/SKILL.md`, refresh one runtime skill with:
@@ -263,7 +279,7 @@ your shell `PATH`.
 
 ## Managing Agent Skills
 
-You can create, import, list, inspect, and sync specialized behaviors:
+You can draft, create, adopt, import, validate, maintain, and sync specialized behaviors:
 ```bash
 # List all active skills
 umem skills list
@@ -271,14 +287,30 @@ umem skills list
 # Inspect one skill
 umem skills detail review-protocol
 
-# Create a new canonical skill
-umem skills create --name "Review Protocol" --description "Reusable review workflow"
+# Draft, validate, and publish without native runtime writes
+umem skills draft create --name "Review Protocol" --description "Reusable review workflow"
+umem skills draft validate review-protocol
+umem skills publish review-protocol
+
+# Create a new canonical skill and explicitly sync native targets
+umem skills create --name "Review Protocol" --description "Reusable review workflow" --sync
 
-# Adopt an existing native skill and distribute complete runtime copies
+# Adopt existing canonical work
+umem skills adopt .umem/skills/review-protocol --scope project
+
+# Import an existing native skill and distribute complete runtime copies
 umem skills import .agents/skills/review-protocol --scope project --sync
 
+# Validate and maintain canonical skills
+umem skills validate review-protocol
+umem skills canonical update review-protocol --file .umem/skills/review-protocol/SKILL.md
+umem skills rename review-protocol --slug review-checklist
+umem skills cleanup review-checklist --targets --format summary
+umem skills cleanup review-checklist --targets --apply
+umem skills repair --remove-orphan-targets --format summary
+
 # Synchronize one canonical skill into active native runtime folders
-umem skills sync review-protocol
+umem skills sync review-protocol --check-gitignore --format summary
 
 # Synchronize all active canonical skills during maintenance
 umem update --skills

{universal_memory-0.2.0 → universal_memory-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "universal-memory"
-version = "0.2.0"
+version = "0.3.0"
 description = "Vendor-agnostic cognitive persistence layer for AI agents."
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -95,3 +95,6 @@ pythonVersion = "3.12"
 typeCheckingMode = "standard"
 venvPath = "."
 venv = ".venv"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

{universal_memory-0.2.0 → universal_memory-0.3.0}/src/universal_memory/__init__.py

@@ -5,4 +5,4 @@ from importlib.metadata import PackageNotFoundError, version
 try:
     __version__ = version("universal-memory")
 except PackageNotFoundError:
-    __version__ = "0.2.0"
+    __version__ = "0.3.0"

{universal_memory-0.2.0 → universal_memory-0.3.0}/src/universal_memory/application/onboarding/setup_project.py

@@ -273,7 +273,9 @@ approval, generation, activation, deactivation, and updates.
 ## Use Cases
 
 - Track a recurring workflow or methodology as a latent skill candidate.
+- Draft a skill when content may need validation before publish.
 - Create a skill directly when the user already knows the desired skill.
+- Adopt existing canonical work in place when it already lives under `.umem/skills/<slug>/`.
 - Import an existing local or native skill directory into the canonical `.umem/skills`
   registry.
 - Sync canonical skills into supported native runtime targets after import or changes.
@@ -290,8 +292,20 @@ approval, generation, activation, deactivation, and updates.
 ```bash
 umem skills list --format json
 umem skills detail <skill-id-or-name> --format json
-umem skills create --name "Skill name" --description "What the skill does." --scope project --trigger "when to use it" --format json
+umem skills draft create --name "Skill name" --description "What the skill does." --scope project --trigger "when to use it" --format json
+umem skills draft validate <draft-or-path> --format json
+umem skills publish <draft-or-path> --format summary
+umem skills create --name "Skill name" --description "What the skill does." --scope project --trigger "when to use it" --format summary
+umem skills adopt .umem/skills/<skill-name> --scope project --format summary
 umem skills import .agents/skills/<skill-name> --scope project --sync --format json
+umem skills validate <skill-id-or-name-or-path> --format json
+umem skills canonical update <skill-id-or-name> --file <relative-markdown-path> --format json
+umem skills rename <skill-id-or-name> --slug <new-slug> --format json
+umem skills cleanup <skill-id-or-name> --targets --format summary
+umem skills cleanup <skill-id-or-name> --targets --apply --format summary
+umem skills repair --remove-orphan-targets --format summary
+umem skills repair --remove-orphan-targets --apply --format summary
+umem skills sync <skill-id-or-name> --check-gitignore --format summary
 umem skills import .agents/skills/<skill-name>/SKILL.md --scope project --replace-native --sync --format json
 umem skills sync <skill-id-or-name> --format json
 umem skills track --name "Skill name" --description "What the skill does." --scope project --evidence-summary "Why this pattern recurred." --tag workflow --format json
@@ -336,13 +350,27 @@ and does not prompt for overwrite. Use explicit `umem skills sync <skill-id-or-n
 - `--trigger <text>`: repeatable trigger used in generated skill frontmatter.
 - `--file <relative-markdown-path>`: complete replacement markdown for `SKILL.md`.
 - `--format json`: canonical automation output.
+- `--format summary`: concise human and agent-facing output with status, paths, warnings,
+  dry-run/apply status, and next steps.
+- `--check-gitignore`: sync diagnostic that warns when generated native runtime targets
+  are tracked by git or not covered by ignore rules. The check runs after target planning/writes
+  and is diagnostic only: do not edit `.gitignore` or untrack files from this warning alone.
+  In automation, report the warning and let repository policy decide whether ignore rules should change.
 
 ## MCP Equivalents
 
 - `list_skills()`
 - `get_skill_detail(name_or_id="<skill-id-or-name>")`
-- `create_skill(name="Skill name", description="What the skill does.", scope="project", raw_markdown="<complete SKILL.md content>")`
+- `create_skill_draft(name="Skill name", description="What the skill does.", scope="project")`
+- `validate_skill(skill_or_path="<skill-id-or-name-or-path>")`
+- `publish_skill(draft_or_path="<draft-or-path>", sync=false)`
+- `create_skill(name="Skill name", description="What the skill does.", scope="project", raw_markdown="<complete SKILL.md content>", sync=false)`
+- `adopt_skill(path=".umem/skills/<skill-name>", scope="project", sync_after_adopt=false)`
 - `import_skill(path=".agents/skills/<skill-name>", scope="project", replace_native=false, sync_after_import=true)`
+- `update_canonical_skill(skill_id_or_name="<skill-id-or-name>", raw_markdown="<complete SKILL.md content>", sync=false)`
+- `rename_skill(skill_id_or_name="<skill-id-or-name>", slug="<new-slug>")`
+- `cleanup_skill(skill_id_or_name="<skill-id-or-name>", targets=true, dry_run=true)`
+- `repair_skills(remove_orphan_targets=true, dry_run=true)`
 - `sync_skills(skill_id_or_name="<skill-id-or-name>", targets=null, drift_decision="keep")`
 - `track_latent_skill(name="Skill name", description="What the skill does.", scope="project", evidence_summary="Why this pattern recurred.", tags=["workflow"])`
 - `recommend_skills(scope="project", min_recurrence=null, dry_run=true)`
@@ -361,14 +389,25 @@ and does not prompt for overwrite. Use explicit `umem skills sync <skill-id-or-n
 - `skills list` returns active, candidate, and disabled skills with relative paths when
   materialized.
 - `skills detail` returns triggers and metadata without loading large references.
-- `skills create` writes a requested canonical skill directly; use it when the user asks
-  for a known skill instead of routing through latent tracking.
+- `skills draft create` writes editable draft content only; validate and publish before sync.
+- `skills create` writes a requested canonical skill directly and does not sync native
+  targets unless `--sync` is present.
+- `skills publish` converts a draft to canonical and does not sync native targets unless
+  `--sync` is present.
+- `skills adopt` registers existing `.umem/skills/<slug>` work in place without creating a suffixed duplicate.
+- Use `skills import`, not `skills adopt`, for existing native runtime directories such
+  as `.agents/skills/<slug>` or `.opencode/skills/<slug>`.
+- `skills validate`, `skills canonical update`, `skills rename`, `skills cleanup`, and
+  `skills repair` are the supported maintenance path for canonical skills.
 - `skills import` is the normal path for an existing `.agents/skills/...`, `.opencode/skills/...`,
   or other local Agent Skills directory. It registers a canonical UMEM skill and copies
   the source directory into `.umem/skills/<slug>/`.
 - `skills sync` materializes canonical skills into configured native runtime targets;
   importing a skill does not necessarily make it available to every runtime until sync
   runs.
+- `skills sync --check-gitignore --format summary` is the preferred interactive safety
+  check when a user wants actionable warnings about tracked or unignored runtime targets.
+  It warns after sync planning/writes and never edits `.gitignore` or untracks files.
 - `skills sync` can create or update runtime directories such as `.opencode/skills/...`,
   `.agents/skills/...`, or `.antigravity/...` depending on configured runtimes. Treat these
   as intentional worktree changes and review whether repository ignore rules should include
@@ -386,10 +425,13 @@ and does not prompt for overwrite. Use explicit `umem skills sync <skill-id-or-n
 - `skills generate` creates canonical files under `.umem/skills/` for project skills.
 - `skills deactivate` preserves files and changes status to disabled.
 - `skills activate` requires a readable, valid `SKILL.md`.
-- `skills update`, `activate`, and `deactivate` currently operate on latent/generated skill
-  IDs, not the canonical `skill_id` returned by imported Agent Skills. If you have a
-  canonical skill under `.umem/skills/<slug>/`, edit that `SKILL.md` through the normal file
-  workflow, then run `umem skills sync <slug> --format json` to refresh native targets.
+- `skills update`, `activate`, and `deactivate` operate on latent/generated skill IDs.
+  For canonical Agent Skills, use `skills canonical update`, `skills rename`, `skills cleanup`,
+  `skills repair`, and `skills sync`.
+- `skills cleanup` previews cleanup for one canonical skill by default; add `--apply`
+  only after reviewing removable and blocked paths.
+- `skills repair` previews project-wide orphan target cleanup by default; add
+  `--remove-orphan-targets --apply` only after reviewing the summary.
 - `host sync --apply` should be non-interactive in agent automation: use
   `umem host sync --apply --yes --format json`.
 
@@ -618,6 +660,15 @@ CLI commands with `--format json` and MCP tools should return equivalent payload
 | Host sync | `umem host sync --apply --yes --format json` | `sync_instructions(apply=true)` |
 | Skills list | `umem skills list --format json` | `list_skills()` |
 | Skill detail | `umem skills detail <skill-id-or-name> --format json` | `get_skill_detail(name_or_id="<skill-id-or-name>")` |
+| Skill draft create | `umem skills draft create ... --format json` | `create_skill_draft(...)` |
+| Skill validate | `umem skills validate <skill-or-path> --format json` | `validate_skill(skill_or_path="<skill-or-path>")` |
+| Skill publish | `umem skills publish <draft-or-path> --format json` | `publish_skill(draft_or_path="<draft-or-path>")` |
+| Skill create | `umem skills create ... --format json` | `create_skill(...)` |
+| Skill adopt | `umem skills adopt <path> --format json` | `adopt_skill(path="<path>")` |
+| Skill canonical update | `umem skills canonical update <skill> --file <path> --format json` | `update_canonical_skill(...)` |
+| Skill rename | `umem skills rename <skill> --slug <slug> --format json` | `rename_skill(...)` |
+| Skill cleanup | `umem skills cleanup <skill> --targets --format json` | `cleanup_skill(...)` |
+| Skill repair | `umem skills repair --remove-orphan-targets --format json` | `repair_skills(...)` |
 | Track skill | `umem skills track ... --format json` | `track_latent_skill(...)` |
 | Recommend skills | `umem skills recommend --scope project --format json` | `recommend_skills(scope="project", dry_run=true)` |
 | Propose skill | `umem skills propose <latent-skill-id> --decision yes --format json` | `propose_skill(latent_skill_id="<latent-skill-id>", decision="yes")` |
@@ -625,7 +676,7 @@ CLI commands with `--format json` and MCP tools should return equivalent payload
 | Generate skill | `umem skills generate <latent-skill-id> --yes --format json` | `generate_skill(latent_skill_id="<latent-skill-id>")` |
 | Activate skill | `umem skills activate <latent-skill-id> --format json` | `activate_skill(latent_skill_id="<latent-skill-id>")` |
 | Deactivate skill | `umem skills deactivate <latent-skill-id> --format json` | `deactivate_skill(latent_skill_id="<latent-skill-id>")` |
-| Update skill | `umem skills update <latent-skill-id> ... --format json` | `update_skill(...)` |
+| Update latent/generated skill | `umem skills update <latent-skill-id> ... --format json` | `update_skill(...)` |
 
 ## Error Mapping
 

{universal_memory-0.2.0 → universal_memory-0.3.0}/src/universal_memory/application/skills/__init__.py

@@ -1,8 +1,30 @@
+from universal_memory.application.skills.adopt_skill import (
+    AdoptSkillCommand,
+    AdoptSkillResult,
+    AdoptSkillUseCase,
+)
+from universal_memory.application.skills.cleanup_skill import (
+    CleanupPlan,
+    CleanupSkillCommand,
+    CleanupSkillResult,
+    CleanupSkillUseCase,
+    RepairSkillsCommand,
+    RepairSkillsResult,
+    RepairSkillsUseCase,
+)
 from universal_memory.application.skills.create_skill import (
     CreateSkillCommand,
     CreateSkillResult,
     CreateSkillUseCase,
 )
+from universal_memory.application.skills.draft_skill import (
+    CreateSkillDraftCommand,
+    CreateSkillDraftUseCase,
+    DraftSkillResult,
+    PublishSkillCommand,
+    PublishSkillResult,
+    PublishSkillUseCase,
+)
 from universal_memory.application.skills.generate_skill import (
     GenerateSkillCommand,
     GenerateSkillResult,
@@ -39,6 +61,11 @@ from universal_memory.application.skills.recommend_skills import (
     RecommendSkillsUseCase,
     SkillRecommendationItem,
 )
+from universal_memory.application.skills.rename_skill import (
+    RenameSkillCommand,
+    RenameSkillResult,
+    RenameSkillUseCase,
+)
 from universal_memory.application.skills.sync_skills import (
     SyncSkillResult,
     SyncSkillsCommand,
@@ -57,21 +84,41 @@ from universal_memory.application.skills.update_skill import (
     DeactivateSkillCommand,
     DeactivateSkillResult,
     DeactivateSkillUseCase,
+    UpdateCanonicalSkillCommand,
+    UpdateCanonicalSkillResult,
+    UpdateCanonicalSkillUseCase,
     UpdateSkillCommand,
     UpdateSkillResult,
     UpdateSkillUseCase,
 )
+from universal_memory.application.skills.validate_skill import (
+    SkillValidationCheck,
+    SkillValidationReport,
+    ValidateSkillCommand,
+    ValidateSkillResult,
+    ValidateSkillUseCase,
+)
 
 __all__ = [
     "ActivateSkillCommand",
     "ActivateSkillResult",
     "ActivateSkillUseCase",
+    "AdoptSkillCommand",
+    "AdoptSkillResult",
+    "AdoptSkillUseCase",
+    "CleanupPlan",
+    "CleanupSkillCommand",
+    "CleanupSkillResult",
+    "CleanupSkillUseCase",
     "CreateSkillCommand",
+    "CreateSkillDraftCommand",
+    "CreateSkillDraftUseCase",
     "CreateSkillResult",
     "CreateSkillUseCase",
     "DeactivateSkillCommand",
     "DeactivateSkillResult",
     "DeactivateSkillUseCase",
+    "DraftSkillResult",
     "GenerateSkillCommand",
     "GenerateSkillResult",
     "GenerateSkillUseCase",
@@ -91,11 +138,22 @@ __all__ = [
     "ProposeSkillDecision",
     "ProposeSkillResult",
     "ProposeSkillUseCase",
+    "PublishSkillCommand",
+    "PublishSkillResult",
+    "PublishSkillUseCase",
     "RecommendSkillsCommand",
     "RecommendSkillsResult",
     "RecommendSkillsUseCase",
+    "RenameSkillCommand",
+    "RenameSkillResult",
+    "RenameSkillUseCase",
+    "RepairSkillsCommand",
+    "RepairSkillsResult",
+    "RepairSkillsUseCase",
     "SkillListItem",
     "SkillRecommendationItem",
+    "SkillValidationCheck",
+    "SkillValidationReport",
     "SyncSkillResult",
     "SyncSkillsCommand",
     "SyncSkillsResult",
@@ -103,7 +161,13 @@ __all__ = [
     "TrackLatentSkillCommand",
     "TrackLatentSkillResult",
     "TrackLatentSkillUseCase",
+    "UpdateCanonicalSkillCommand",
+    "UpdateCanonicalSkillResult",
+    "UpdateCanonicalSkillUseCase",
     "UpdateSkillCommand",
     "UpdateSkillResult",
     "UpdateSkillUseCase",
+    "ValidateSkillCommand",
+    "ValidateSkillResult",
+    "ValidateSkillUseCase",
 ]