universal-memory 0.1.0__tar.gz

universal_memory-0.1.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.3
+Name: universal-memory
+Version: 0.1.0
+Summary: Vendor-agnostic cognitive persistence layer for AI agents.
+Author: Yan L. Amorelli
+Author-email: Yan L. Amorelli <dev@amorelliaoyan.com>
+License: MIT
+Requires-Dist: fastmcp>=0.1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=15.0.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: typer>=0.9.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/YanAmorelli/universal-memory
+Project-URL: Repository, https://github.com/YanAmorelli/universal-memory
+Description-Content-Type: text/markdown
+
+# Universal Memory (umem)
+
+[![PyPI version](https://img.shields.io/pypi/v/universal-memory.svg)](https://pypi.org/project/universal-memory/)
+[![Python Version](https://img.shields.io/pypi/pyversions/universal-memory.svg)](https://img.shields.io/project/universal-memory/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A vendor-agnostic cognitive persistence layer for AI agents. Eliminate the "repetition tax" by transporting your context, preferences, guidelines, and history seamlessly across sessions, IDEs, and LLM models.
+
+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/UNIVERSAL-MEMORY-MVP-PROPOSAL.png)
+
+### Diagram Breakdown (English Translation)
+
+*   **Short-Term Memory (Ephemeral):** Project-specific (folder-level) memories. A simple summary of recent changes, pending tasks, and project or task-level constraints.
+*   **Agents Behaviours:** Comports the user's expected agent behaviors. Instead of requesting the same settings in every session, the agent understands the user by their traits, thoughts, and any context key to enhancing the overall experience. This encompasses:
+    *   **Long-Term Memory**
+    *   **Short-Term Memory**
+    *   **User Preferences**
+*   **Skill Creator:** Encapsulates understanding of specific workflows. When a user explains a task pattern multiple times, the system translates it into structured, reusable agent skills.
+*   **Unified Instruction File (`AGENT.MD`):** The shared persistence endpoint consumed by all local agent instances (e.g., Agent A, Agent B, Agent C).
+
+---
+
+## The Problem: The "Repetition Tax"
+
+Every time you open a new session in Claude Code, start a new chat in Cursor, spin up a terminal with OpenCode, or invoke a local AI assistant, you pay a steep cognitive tax:
+* Re-explaining your stack (e.g., "We use Python 3.12, Typer, and Ruff").
+* Repeating coding style preferences (e.g., "Prefer functional design, do not write docstrings unless requested").
+* Copy-pasting database connection schemas or module layouts.
+* Explaining workflow methodologies (e.g., "We follow Spec-Driven Development (SDD)").
+
+Universal Memory acts as a local "Cognitive USB Drive" that automatically connects to your AI runtimes, aligning them to your exact workflow, context, and rules with zero friction.
+
+---
+
+## Key Architectural Concepts
+
+### 1. Dual-Memory Model
+*   **Short-Term Memory (Project Scope):** Ephemeral, directory-specific context. Tracks what you did 10 minutes ago, current active tasks, and immediate constraints.
+*   **Universal Memory (Global Scope):** Long-lived preferences, style guidelines, tool configurations, and identity.
+
+### 2. Auto-Adaptation Engine
+Instead of copy-pasting instructions, `umem` monitors your session context and automatically updates active project instruction manifests (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, etc.), enforcing operational consistency across all agents.
+
+### 3. Model Context Protocol (MCP) Integration
+Integrate `umem` natively with any client supporting the standard MCP (such as Claude Desktop or Cursor). AI agents can programmatically retrieve context, learn new facts, and suggest skills on the fly.
+
+### 4. Agent Skills Standard
+Encapsulates complex, repetitive procedural instructions into formal Agent Skills (conforming to the [agentskills.io](https://agentskills.io) standard), complete with structured directories containing `SKILL.md` instructions, helper `scripts/`, and documentation `references/`.
+
+---
+
+## Installation & Setup
+
+Ensure you have Python 3.12+ installed. You can run or install `umem` using your preferred package manager.
+
+### Run instantly with `uv` (Recommended)
+You don't even need to install it permanently:
+```bash
+uvx umem --help
+```
+
+### Install via PyPI
+```bash
+pip install universal-memory
+```
+
+---
+
+## Quick Start Guide
+
+### 1. Initialize your project
+Initialize `umem` in the current directory and hook it to your preferred runtimes/agents:
+```bash
+umem init --runtime claude-code --runtime opencode --runtime cursor
+```
+This sets up a local repository configuration, hooks up the necessary workspace instructions (`AGENTS.md`, `CLAUDE.md`), and prepares native skill folders.
+
+### 2. Save your first preferences and facts
+Tell `umem` what to keep in mind. You can target either the project scope (this folder) or the global scope (across all projects):
+```bash
+# Save a global preference
+umem remember --scope global "Yan is a solutions architect specializing in AI applications"
+
+# Save a project-specific constraint
+umem remember --scope project "Always use Tomllib instead of PyYAML for configuration files" --tag config
+```
+
+### 3. Retrieve Context
+Verify the consolidated context summary generated by combining short-term facts, rules, and global preferences:
+```bash
+umem context --scope project
+```
+
+### 4. Check status and health
+```bash
+umem status
+```
+
+---
+
+## Host Integration & Support Matrix
+
+`umem` maps cognitive context and agent skills directly into native runtime paths:
+
+| Runtime / Host | Support Tier | Config / Instructions Target |
+| --- | --- | --- |
+| **Claude Code** | Tier 1 (Full) | `CLAUDE.md`, `.claude/`, `~/.claude/` |
+| **OpenCode** | Tier 1 (Full) | `AGENTS.md`, `.opencode/`, `~/.config/opencode/` |
+| **Codex (OpenAI)** | Tier 1 (Full) | `AGENTS.md`, workspace configuration files |
+| **Cursor** | Tier 2 (Basic) | `.cursor/rules/`, `~/.cursor/` |
+| **Antigravity / Gemini** | Tier 2 (Basic) | `GEMINI.md`, `~/.gemini/` |
+
+---
+
+## Running as an Model Context Protocol (MCP) Server
+
+AI agents can interact directly with your memory over the Model Context Protocol.
+
+### CLI Launch Command
+```bash
+umem-mcp
+```
+
+### Example Config: Claude Desktop (`claude_desktop_config.json`)
+```json
+{
+  "mcpServers": {
+    "universal-memory": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--package",
+        "universal-memory",
+        "umem-mcp"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Safety & Guardrails
+
+*   **API Secret Scanner:** `umem` passes all incoming facts through a passive scanner to block API keys, tokens, or credentials from being stored in your persistent cognitive base.
+*   **Snapshots & Rollbacks:** Every automated update to your config files (`AGENTS.md`, `CLAUDE.md`) is preceded by a snapshot backup. You can rollback anytime:
+    ```bash
+    # View audit logs
+    umem audit list --scope project
+    
+    # Revert last automated modification
+    umem rollback --scope project
+    ```
+*   **Update Conflict Warnings:** When updating canonical skills, if `umem` detects manual edits in local runtime rule directories (e.g. `.cursor/rules/sdd-rules.md`), it prompts you interactivelly to choose whether to keep your local edits or overwrite them, preventing workflow disruption.
+
+---
+
+## Managing Agent Skills
+
+You can create, list, and sync specialized behaviors:
+```bash
+# List all active skills
+umem skills list
+
+# Synchronize skills into active native runtime folders
+umem update --skills
+
+# Generate a new skill template from a latent skill proposal
+umem skills generate --name build-standard
+```
+
+---
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for more information.

universal_memory-0.1.0/README.md

@@ -0,0 +1,178 @@
+# Universal Memory (umem)
+
+[![PyPI version](https://img.shields.io/pypi/v/universal-memory.svg)](https://pypi.org/project/universal-memory/)
+[![Python Version](https://img.shields.io/pypi/pyversions/universal-memory.svg)](https://img.shields.io/project/universal-memory/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A vendor-agnostic cognitive persistence layer for AI agents. Eliminate the "repetition tax" by transporting your context, preferences, guidelines, and history seamlessly across sessions, IDEs, and LLM models.
+
+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/UNIVERSAL-MEMORY-MVP-PROPOSAL.png)
+
+### Diagram Breakdown (English Translation)
+
+*   **Short-Term Memory (Ephemeral):** Project-specific (folder-level) memories. A simple summary of recent changes, pending tasks, and project or task-level constraints.
+*   **Agents Behaviours:** Comports the user's expected agent behaviors. Instead of requesting the same settings in every session, the agent understands the user by their traits, thoughts, and any context key to enhancing the overall experience. This encompasses:
+    *   **Long-Term Memory**
+    *   **Short-Term Memory**
+    *   **User Preferences**
+*   **Skill Creator:** Encapsulates understanding of specific workflows. When a user explains a task pattern multiple times, the system translates it into structured, reusable agent skills.
+*   **Unified Instruction File (`AGENT.MD`):** The shared persistence endpoint consumed by all local agent instances (e.g., Agent A, Agent B, Agent C).
+
+---
+
+## The Problem: The "Repetition Tax"
+
+Every time you open a new session in Claude Code, start a new chat in Cursor, spin up a terminal with OpenCode, or invoke a local AI assistant, you pay a steep cognitive tax:
+* Re-explaining your stack (e.g., "We use Python 3.12, Typer, and Ruff").
+* Repeating coding style preferences (e.g., "Prefer functional design, do not write docstrings unless requested").
+* Copy-pasting database connection schemas or module layouts.
+* Explaining workflow methodologies (e.g., "We follow Spec-Driven Development (SDD)").
+
+Universal Memory acts as a local "Cognitive USB Drive" that automatically connects to your AI runtimes, aligning them to your exact workflow, context, and rules with zero friction.
+
+---
+
+## Key Architectural Concepts
+
+### 1. Dual-Memory Model
+*   **Short-Term Memory (Project Scope):** Ephemeral, directory-specific context. Tracks what you did 10 minutes ago, current active tasks, and immediate constraints.
+*   **Universal Memory (Global Scope):** Long-lived preferences, style guidelines, tool configurations, and identity.
+
+### 2. Auto-Adaptation Engine
+Instead of copy-pasting instructions, `umem` monitors your session context and automatically updates active project instruction manifests (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, etc.), enforcing operational consistency across all agents.
+
+### 3. Model Context Protocol (MCP) Integration
+Integrate `umem` natively with any client supporting the standard MCP (such as Claude Desktop or Cursor). AI agents can programmatically retrieve context, learn new facts, and suggest skills on the fly.
+
+### 4. Agent Skills Standard
+Encapsulates complex, repetitive procedural instructions into formal Agent Skills (conforming to the [agentskills.io](https://agentskills.io) standard), complete with structured directories containing `SKILL.md` instructions, helper `scripts/`, and documentation `references/`.
+
+---
+
+## Installation & Setup
+
+Ensure you have Python 3.12+ installed. You can run or install `umem` using your preferred package manager.
+
+### Run instantly with `uv` (Recommended)
+You don't even need to install it permanently:
+```bash
+uvx umem --help
+```
+
+### Install via PyPI
+```bash
+pip install universal-memory
+```
+
+---
+
+## Quick Start Guide
+
+### 1. Initialize your project
+Initialize `umem` in the current directory and hook it to your preferred runtimes/agents:
+```bash
+umem init --runtime claude-code --runtime opencode --runtime cursor
+```
+This sets up a local repository configuration, hooks up the necessary workspace instructions (`AGENTS.md`, `CLAUDE.md`), and prepares native skill folders.
+
+### 2. Save your first preferences and facts
+Tell `umem` what to keep in mind. You can target either the project scope (this folder) or the global scope (across all projects):
+```bash
+# Save a global preference
+umem remember --scope global "Yan is a solutions architect specializing in AI applications"
+
+# Save a project-specific constraint
+umem remember --scope project "Always use Tomllib instead of PyYAML for configuration files" --tag config
+```
+
+### 3. Retrieve Context
+Verify the consolidated context summary generated by combining short-term facts, rules, and global preferences:
+```bash
+umem context --scope project
+```
+
+### 4. Check status and health
+```bash
+umem status
+```
+
+---
+
+## Host Integration & Support Matrix
+
+`umem` maps cognitive context and agent skills directly into native runtime paths:
+
+| Runtime / Host | Support Tier | Config / Instructions Target |
+| --- | --- | --- |
+| **Claude Code** | Tier 1 (Full) | `CLAUDE.md`, `.claude/`, `~/.claude/` |
+| **OpenCode** | Tier 1 (Full) | `AGENTS.md`, `.opencode/`, `~/.config/opencode/` |
+| **Codex (OpenAI)** | Tier 1 (Full) | `AGENTS.md`, workspace configuration files |
+| **Cursor** | Tier 2 (Basic) | `.cursor/rules/`, `~/.cursor/` |
+| **Antigravity / Gemini** | Tier 2 (Basic) | `GEMINI.md`, `~/.gemini/` |
+
+---
+
+## Running as an Model Context Protocol (MCP) Server
+
+AI agents can interact directly with your memory over the Model Context Protocol.
+
+### CLI Launch Command
+```bash
+umem-mcp
+```
+
+### Example Config: Claude Desktop (`claude_desktop_config.json`)
+```json
+{
+  "mcpServers": {
+    "universal-memory": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--package",
+        "universal-memory",
+        "umem-mcp"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Safety & Guardrails
+
+*   **API Secret Scanner:** `umem` passes all incoming facts through a passive scanner to block API keys, tokens, or credentials from being stored in your persistent cognitive base.
+*   **Snapshots & Rollbacks:** Every automated update to your config files (`AGENTS.md`, `CLAUDE.md`) is preceded by a snapshot backup. You can rollback anytime:
+    ```bash
+    # View audit logs
+    umem audit list --scope project
+    
+    # Revert last automated modification
+    umem rollback --scope project
+    ```
+*   **Update Conflict Warnings:** When updating canonical skills, if `umem` detects manual edits in local runtime rule directories (e.g. `.cursor/rules/sdd-rules.md`), it prompts you interactivelly to choose whether to keep your local edits or overwrite them, preventing workflow disruption.
+
+---
+
+## Managing Agent Skills
+
+You can create, list, and sync specialized behaviors:
+```bash
+# List all active skills
+umem skills list
+
+# Synchronize skills into active native runtime folders
+umem update --skills
+
+# Generate a new skill template from a latent skill proposal
+umem skills generate --name build-standard
+```
+
+---
+
+## License
+
+Distributed under the MIT License. See [LICENSE](LICENSE) for more information.

universal_memory-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "universal-memory"
+version = "0.1.0"
+description = "Vendor-agnostic cognitive persistence layer for AI agents."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Yan L. Amorelli", email = "dev@amorelliaoyan.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "fastmcp>=0.1.0",
+    "pydantic>=2.0",
+    "rich>=15.0.0",
+    "tomli-w>=1.0.0",
+    "typer>=0.9.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/YanAmorelli/universal-memory"
+Repository = "https://github.com/YanAmorelli/universal-memory"
+
+[project.scripts]
+umem = "universal_memory.bootstrap.cli:main"
+universal-memory = "universal_memory.bootstrap.cli:main"
+umem-mcp = "universal_memory.bootstrap.mcp:main"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.350",
+    "pytest>=8.0.0",
+    "ruff>=0.3.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "PL", "RUF", "B", "S"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["S101"]
+"src/universal_memory/interfaces/cli/init_command.py" = ["E501"]
+
+
+[tool.pyright]
+include = ["src", "tests", "benchmarks"]
+pythonVersion = "3.12"
+typeCheckingMode = "standard"
+venvPath = "."
+venv = ".venv"

universal_memory-0.1.0/src/universal_memory/__init__.py

@@ -0,0 +1,8 @@
+"""Universal Memory package."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("universal-memory")
+except PackageNotFoundError:
+    __version__ = "0.1.0"

universal_memory-0.1.0/src/universal_memory/__main__.py

@@ -0,0 +1,4 @@
+from universal_memory.bootstrap.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

universal_memory-0.1.0/src/universal_memory/application/__init__.py

@@ -0,0 +1 @@
+"""Application layer for universal-memory."""

universal_memory-0.1.0/src/universal_memory/application/host/__init__.py

@@ -0,0 +1,25 @@
+from universal_memory.application.host.setup_host_use_case import (
+    ConfigureHostCommand,
+    ConfigureHostResult,
+    ConfigureHostUseCase,
+    InstructionBlock,
+    InstructionPartition,
+    partition_instruction_blocks,
+)
+from universal_memory.application.host.sync_instructions_use_case import (
+    SyncInstructionsCommand,
+    SyncInstructionsResult,
+    SyncInstructionsUseCase,
+)
+
+__all__ = [
+    "ConfigureHostCommand",
+    "ConfigureHostResult",
+    "ConfigureHostUseCase",
+    "InstructionBlock",
+    "InstructionPartition",
+    "SyncInstructionsCommand",
+    "SyncInstructionsResult",
+    "SyncInstructionsUseCase",
+    "partition_instruction_blocks",
+]

universal_memory-0.1.0/src/universal_memory/application/host/drift_detector.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import re
+
+
+class InstructionDriftDetector:
+    def detect(self, *, agents_content: str, claude_content: str) -> list[str]:
+        if not agents_content or not claude_content:
+            return []
+        agents_lines = _instruction_lines(agents_content)
+        claude_lines = _instruction_lines(claude_content)
+        warnings: list[str] = []
+
+        agents_by_normalized = {_normalize_line(line): line for line in agents_lines}
+        for claude_line in claude_lines:
+            normalized = _normalize_line(claude_line)
+            if normalized in agents_by_normalized:
+                warnings.append(
+                    "Instrucao duplicada em AGENTS.md e CLAUDE.md: "
+                    f"{agents_by_normalized[normalized]}"
+                )
+
+        contradiction_warnings = _detect_always_never_contradictions(
+            agents_lines,
+            claude_lines,
+        )
+        warnings.extend(contradiction_warnings)
+        return warnings
+
+
+def _instruction_lines(content: str) -> list[str]:
+    lines: list[str] = []
+    for raw_line in content.splitlines():
+        line = raw_line.strip()
+        if not line or "<!--" in line or "-->" in line or line.startswith(("#", ">")):
+            continue
+        line = re.sub(r"^[-*]\s*", "", line)
+        line = re.sub(r"^\([a-z_-]+\)\s*", "", line).strip()
+        if line:
+            lines.append(line)
+    return lines
+
+
+def _normalize_line(line: str) -> str:
+    return re.sub(r"\s+", " ", line).strip().rstrip(".").casefold()
+
+
+def _detect_always_never_contradictions(
+    agents_lines: list[str],
+    claude_lines: list[str],
+) -> list[str]:
+    warnings: list[str] = []
+    agents_norms = [_normalize_line(line) for line in agents_lines]
+    agents_rules = {}
+    for line, norm in zip(agents_lines, agents_norms, strict=True):
+        if _rule_polarity(norm):
+            body = _rule_body(norm)
+            if body:
+                agents_rules[body] = (line, norm)
+
+    for claude_line in claude_lines:
+        norm = _normalize_line(claude_line)
+        claude_polarity = _rule_polarity(norm)
+        if claude_polarity is None:
+            continue
+        body = _rule_body(norm)
+        if not body:
+            continue
+        matched = agents_rules.get(body)
+        if matched is None:
+            continue
+        agents_line, agents_norm = matched
+        agents_polarity = _rule_polarity(agents_norm)
+        if agents_polarity != claude_polarity:
+            warnings.append(
+                f"Contradicao explicita entre AGENTS.md e CLAUDE.md: {agents_line} / {claude_line}"
+            )
+    return warnings
+
+
+def _rule_polarity(normalized: str) -> str | None:
+    if normalized.startswith(("always ", "sempre ")):
+        return "positive"
+    if normalized.startswith(("never ", "nunca ")):
+        return "negative"
+    return None
+
+
+def _rule_body(normalized: str) -> str:
+    for prefix in ("always ", "never ", "sempre ", "nunca "):
+        if normalized.startswith(prefix):
+            return normalized.removeprefix(prefix)
+    return normalized