rememb 0.1.0__tar.gz

rememb-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include LICENSE
+recursive-include rules *.md
+recursive-include demo *.gif

rememb-0.1.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: rememb
+Version: 0.1.0
+Summary: Persistent memory standard for AI agents — local, portable, zero config
+License: MIT
+Project-URL: Homepage, https://github.com/LuizEduPP/rememb
+Project-URL: Repository, https://github.com/LuizEduPP/rememb
+Project-URL: Issues, https://github.com/LuizEduPP/rememb/issues
+Keywords: ai,agents,memory,llm,mcp,windsurf,cursor,claude,copilot,continue,vscode,persistent-memory,ai-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sentence-transformers>=3.0.0
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# rememb
+
+> **Persistent memory for AI agents — local, portable, zero config.**
+
+![rememb demo](demo/demo.gif)
+
+AI agents (Windsurf, Cursor, Claude, Continue) forget everything between sessions.  
+`rememb` gives them a structured memory that lives in your project, belongs to you, and works with any agent.
+
+---
+
+## The problem
+
+Every developer using AI agents hits this wall:
+
+```
+Session 1: "We're using PostgreSQL, the auth module is at src/auth/, prefer async patterns."
+Session 2: Agent starts from zero. You explain everything again.
+Session 3: Same thing.
+```
+
+Existing solutions (Mem0, Zep, Letta) require servers, API keys, cloud accounts, and framework lock-in.  
+You just want the agent to **remember your project**.
+
+---
+
+## The solution
+
+```
+.rememb/
+  entries.json   ← structured memory (project, actions, systems, user, context)
+  meta.json      ← project metadata
+```
+
+That's it. A JSON file in your project. Your agent reads it at the start of every session.
+
+---
+
+## Install
+
+```bash
+git clone https://github.com/LuizEduPP/rememb.git
+cd rememb
+pip install -e .
+```
+
+---
+
+## Quickstart
+
+```bash
+# Initialize in your project
+rememb init
+
+# Write memories
+rememb write "Project uses FastAPI + PostgreSQL + async patterns" --section project
+rememb write "User prefers direct answers, no filler text" --section user
+rememb write "Auth module lives at src/auth/, JWT-based" --section systems
+
+# Read everything (for the agent)
+rememb read --agent
+
+# Search semantically
+rememb search "authentication"
+
+# Get ready-to-use rules for your editor
+rememb rules windsurf
+rememb rules cursor
+rememb rules claude
+rememb rules continue
+rememb rules vscode
+```
+
+---
+
+## Agent integration
+
+**Configure once. Works forever.**
+
+Run `rememb rules <editor>` to get the instructions for your editor, then paste them once. From that point on, your agent automatically reads and writes memory on every session.
+
+```bash
+rememb rules windsurf   # Windsurf / Cascade
+rememb rules cursor     # Cursor
+rememb rules claude     # Claude Code
+rememb rules continue   # Continue.dev
+rememb rules vscode     # VS Code + Copilot
+```
+
+| Editor | Where to paste |
+|--------|---------------|
+| **Windsurf / Cascade** | `.windsurfrules` at project root — or Settings → Cascade → Custom Instructions |
+| **Cursor** | `.cursorrules` at project root — or Settings → Rules for AI |
+| **Claude Code** | `CLAUDE.md` at project root (auto-read every session) |
+| **Continue.dev** | `config.json` → `models[].systemMessage` |
+| **VS Code + Copilot** | `.github/copilot-instructions.md` at project root (auto-read by Copilot) |
+
+---
+
+## Memory sections
+
+| Section | What to store |
+|---------|---------------|
+| `project` | Tech stack, architecture, goals |
+| `actions` | What was done, decisions made |
+| `systems` | Services, modules, integrations |
+| `requests` | User preferences, recurring asks |
+| `user` | Name, style, expertise, preferences |
+| `context` | Anything else relevant |
+
+---
+
+## Commands
+
+```
+rememb init              Initialize .rememb/ in current project
+rememb write <text>      Write a memory entry (--section, --tags)
+rememb read              Read all entries (--section, --agent, --raw)
+rememb search <query>    Semantic search (falls back to keyword)
+rememb rules [editor]    Print agent rules for windsurf/cursor/claude/continue
+```
+
+---
+
+## How search works
+
+`rememb search` uses `sentence-transformers` for semantic similarity search locally.  
+No API calls. No embeddings sent to the cloud. Falls back to keyword search if the model isn't available.
+
+---
+
+## Design principles
+
+- **Local first** — everything is a JSON file in your project
+- **Portable** — copy `.rememb/` and it works anywhere
+- **Agnostic** — works with any agent that can run CLI commands
+- **Zero config** — `pip install rememb && rememb init` and you're done
+- **No lock-in** — plain JSON, read it with anything
+
+---
+
+## Roadmap
+
+- [ ] MCP server (`rememb mcp`) for native IDE integration
+- [ ] `rememb sync` — optional encrypted remote backup
+- [ ] `rememb export` — export to Markdown, Obsidian, Notion
+- [ ] VS Code / Windsurf extension
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/LuizEduPP/rememb
+cd rememb
+pip install -e ".[dev]"
+```
+
+PRs welcome. Issues welcome. Stars welcome. 🌟
+
+---
+
+## License
+
+MIT

rememb-0.1.0/README.md

@@ -0,0 +1,165 @@
+# rememb
+
+> **Persistent memory for AI agents — local, portable, zero config.**
+
+![rememb demo](demo/demo.gif)
+
+AI agents (Windsurf, Cursor, Claude, Continue) forget everything between sessions.  
+`rememb` gives them a structured memory that lives in your project, belongs to you, and works with any agent.
+
+---
+
+## The problem
+
+Every developer using AI agents hits this wall:
+
+```
+Session 1: "We're using PostgreSQL, the auth module is at src/auth/, prefer async patterns."
+Session 2: Agent starts from zero. You explain everything again.
+Session 3: Same thing.
+```
+
+Existing solutions (Mem0, Zep, Letta) require servers, API keys, cloud accounts, and framework lock-in.  
+You just want the agent to **remember your project**.
+
+---
+
+## The solution
+
+```
+.rememb/
+  entries.json   ← structured memory (project, actions, systems, user, context)
+  meta.json      ← project metadata
+```
+
+That's it. A JSON file in your project. Your agent reads it at the start of every session.
+
+---
+
+## Install
+
+```bash
+git clone https://github.com/LuizEduPP/rememb.git
+cd rememb
+pip install -e .
+```
+
+---
+
+## Quickstart
+
+```bash
+# Initialize in your project
+rememb init
+
+# Write memories
+rememb write "Project uses FastAPI + PostgreSQL + async patterns" --section project
+rememb write "User prefers direct answers, no filler text" --section user
+rememb write "Auth module lives at src/auth/, JWT-based" --section systems
+
+# Read everything (for the agent)
+rememb read --agent
+
+# Search semantically
+rememb search "authentication"
+
+# Get ready-to-use rules for your editor
+rememb rules windsurf
+rememb rules cursor
+rememb rules claude
+rememb rules continue
+rememb rules vscode
+```
+
+---
+
+## Agent integration
+
+**Configure once. Works forever.**
+
+Run `rememb rules <editor>` to get the instructions for your editor, then paste them once. From that point on, your agent automatically reads and writes memory on every session.
+
+```bash
+rememb rules windsurf   # Windsurf / Cascade
+rememb rules cursor     # Cursor
+rememb rules claude     # Claude Code
+rememb rules continue   # Continue.dev
+rememb rules vscode     # VS Code + Copilot
+```
+
+| Editor | Where to paste |
+|--------|---------------|
+| **Windsurf / Cascade** | `.windsurfrules` at project root — or Settings → Cascade → Custom Instructions |
+| **Cursor** | `.cursorrules` at project root — or Settings → Rules for AI |
+| **Claude Code** | `CLAUDE.md` at project root (auto-read every session) |
+| **Continue.dev** | `config.json` → `models[].systemMessage` |
+| **VS Code + Copilot** | `.github/copilot-instructions.md` at project root (auto-read by Copilot) |
+
+---
+
+## Memory sections
+
+| Section | What to store |
+|---------|---------------|
+| `project` | Tech stack, architecture, goals |
+| `actions` | What was done, decisions made |
+| `systems` | Services, modules, integrations |
+| `requests` | User preferences, recurring asks |
+| `user` | Name, style, expertise, preferences |
+| `context` | Anything else relevant |
+
+---
+
+## Commands
+
+```
+rememb init              Initialize .rememb/ in current project
+rememb write <text>      Write a memory entry (--section, --tags)
+rememb read              Read all entries (--section, --agent, --raw)
+rememb search <query>    Semantic search (falls back to keyword)
+rememb rules [editor]    Print agent rules for windsurf/cursor/claude/continue
+```
+
+---
+
+## How search works
+
+`rememb search` uses `sentence-transformers` for semantic similarity search locally.  
+No API calls. No embeddings sent to the cloud. Falls back to keyword search if the model isn't available.
+
+---
+
+## Design principles
+
+- **Local first** — everything is a JSON file in your project
+- **Portable** — copy `.rememb/` and it works anywhere
+- **Agnostic** — works with any agent that can run CLI commands
+- **Zero config** — `pip install rememb && rememb init` and you're done
+- **No lock-in** — plain JSON, read it with anything
+
+---
+
+## Roadmap
+
+- [ ] MCP server (`rememb mcp`) for native IDE integration
+- [ ] `rememb sync` — optional encrypted remote backup
+- [ ] `rememb export` — export to Markdown, Obsidian, Notion
+- [ ] VS Code / Windsurf extension
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/LuizEduPP/rememb
+cd rememb
+pip install -e ".[dev]"
+```
+
+PRs welcome. Issues welcome. Stars welcome. 🌟
+
+---
+
+## License
+
+MIT

rememb-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rememb"
+version = "0.1.0"
+description = "Persistent memory standard for AI agents — local, portable, zero config"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+keywords = ["ai", "agents", "memory", "llm", "mcp", "windsurf", "cursor", "claude", "copilot", "continue", "vscode", "persistent-memory", "ai-tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+    "sentence-transformers>=3.0.0",
+    "numpy>=1.24.0",
+]
+
+[project.scripts]
+rememb = "rememb.cli:app"
+
+[project.optional-dependencies]
+dev = ["build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/LuizEduPP/rememb"
+Repository = "https://github.com/LuizEduPP/rememb"
+Issues = "https://github.com/LuizEduPP/rememb/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"*" = ["*.md", "*.json", "*.gif"]
+
+[tool.setuptools]
+include-package-data = true

rememb-0.1.0/rules/claude.md

@@ -0,0 +1,21 @@
+# rememb
+
+You have access to `rememb`, a CLI tool for persistent memory across sessions.
+Use it to remember and retrieve context about this project and user.
+
+## Reading memory
+Run `rememb read --agent` to load all stored context before responding.
+Run `rememb search "<topic>" --agent` to find specific information.
+
+## Writing memory
+Run `rememb write "<summary>" --section <section>` when you learn something worth remembering.
+Available sections: project | actions | systems | requests | user | context
+
+## Rules
+- Always read memory at the start of a new session
+- Save important context after learning it — do not wait
+- Keep entries short (1-3 sentences)
+- Use --tags to categorize: `rememb write "..." --section project --tags tag1,tag2`
+
+# Where to place (Claude Code)
+- CLAUDE.md at project root (auto-read every session)

rememb-0.1.0/rules/continue.md

@@ -0,0 +1,22 @@
+# rememb
+
+You have access to `rememb`, a CLI tool for persistent memory across sessions.
+Use it to remember and retrieve context about this project and user.
+
+## Reading memory
+Run `rememb read --agent` to load all stored context before responding.
+Run `rememb search "<topic>" --agent` to find specific information.
+
+## Writing memory
+Run `rememb write "<summary>" --section <section>` when you learn something worth remembering.
+Available sections: project | actions | systems | requests | user | context
+
+## Rules
+- Always read memory at the start of a new session
+- Save important context after learning it — do not wait
+- Keep entries short (1-3 sentences)
+- Use --tags to categorize: `rememb write "..." --section project --tags tag1,tag2`
+
+# Where to place (Continue.dev)
+- config.json → models[].systemMessage
+- Or: .continuerc.json → systemMessage

rememb-0.1.0/rules/cursor.md

@@ -0,0 +1,22 @@
+# rememb
+
+You have access to `rememb`, a CLI tool for persistent memory across sessions.
+Use it to remember and retrieve context about this project and user.
+
+## Reading memory
+Run `rememb read --agent` to load all stored context before responding.
+Run `rememb search "<topic>" --agent` to find specific information.
+
+## Writing memory
+Run `rememb write "<summary>" --section <section>` when you learn something worth remembering.
+Available sections: project | actions | systems | requests | user | context
+
+## Rules
+- Always read memory at the start of a new session
+- Save important context after learning it — do not wait
+- Keep entries short (1-3 sentences)
+- Use --tags to categorize: `rememb write "..." --section project --tags tag1,tag2`
+
+# Where to place (Cursor)
+- .cursorrules at project root
+- Or: Settings → Rules for AI

rememb-0.1.0/rules/vscode.md

@@ -0,0 +1,21 @@
+# rememb
+
+You have access to `rememb`, a CLI tool for persistent memory across sessions.
+Use it to remember and retrieve context about this project and user.
+
+## Reading memory
+Run `rememb read --agent` to load all stored context before responding.
+Run `rememb search "<topic>" --agent` to find specific information.
+
+## Writing memory
+Run `rememb write "<summary>" --section <section>` when you learn something worth remembering.
+Available sections: project | actions | systems | requests | user | context
+
+## Rules
+- Always read memory at the start of a new session
+- Save important context after learning it — do not wait
+- Keep entries short (1-3 sentences)
+- Use --tags to categorize: `rememb write "..." --section project --tags tag1,tag2`
+
+# Where to place (VS Code + Copilot)
+- .github/copilot-instructions.md at project root (auto-read by Copilot)

rememb-0.1.0/rules/windsurf.md

@@ -0,0 +1,22 @@
+# rememb
+
+You have access to `rememb`, a CLI tool for persistent memory across sessions.
+Use it to remember and retrieve context about this project and user.
+
+## Reading memory
+Run `rememb read --agent` to load all stored context before responding.
+Run `rememb search "<topic>" --agent` to find specific information.
+
+## Writing memory
+Run `rememb write "<summary>" --section <section>` when you learn something worth remembering.
+Available sections: project | actions | systems | requests | user | context
+
+## Rules
+- Always read memory at the start of a new session
+- Save important context after learning it — do not wait
+- Keep entries short (1-3 sentences)
+- Use --tags to categorize: `rememb write "..." --section project --tags tag1,tag2`
+
+# Where to place (Windsurf / Cascade)
+- Settings → Cascade → Custom Instructions
+- Or: .windsurfrules at project root

rememb-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

rememb-0.1.0/src/rememb/__init__.py

@@ -0,0 +1,3 @@
+"""rememb — Persistent memory standard for AI agents."""
+
+__version__ = "0.1.0"

rememb-0.1.0/src/rememb/cli.py

@@ -0,0 +1,290 @@
+"""rememb CLI — persistent memory for AI agents."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.table import Table
+from rich import box
+
+from rememb import __version__
+from rememb.store import (
+    SECTIONS,
+    find_root,
+    global_root,
+    init,
+    is_initialized,
+    read_entries,
+    search_entries,
+    write_entry,
+)
+
+app = typer.Typer(
+    name="rememb",
+    help="Persistent memory for AI agents — local, portable, zero config.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+)
+console = Console()
+
+
+def _root() -> Path:
+    """Returns memory root. Auto-initializes global ~/.rememb/ if nothing found."""
+    root = find_root()
+    if not is_initialized(root):
+        root = global_root()
+        init(root, project_name="global", global_mode=True)
+    return root
+
+
+@app.command()
+def version():
+    """Show rememb version."""
+    console.print(f"rememb v{__version__}")
+
+
+def init_cmd(
+    path: Optional[Path] = typer.Argument(None, help="Project root (default: current dir)"),
+    name: str = typer.Option("", "--name", "-n", help="Project name"),
+):
+    """Initialize .rememb/ in the current project (or globally with --global)."""
+    root = (path or Path.cwd()).resolve()
+
+    if is_initialized(root):
+        console.print(f"[yellow]Already initialized at {root / '.rememb'}[/yellow]")
+        raise typer.Exit()
+
+    global_mode = root == global_root()
+    rememb = init(root, project_name=name, global_mode=global_mode)
+    console.print(Panel(
+        f"[green]✓[/green] Initialized [bold].rememb/[/bold] at [dim]{rememb}[/dim]\n\n"
+        f"[dim]Sections:[/dim] {', '.join(SECTIONS)}\n\n"
+        f"Next steps:\n"
+        f"  [bold]rememb write[/bold] --section project \"My project does X\"\n"
+        f"  [bold]rememb read[/bold]\n"
+        f"  [bold]rememb rules[/bold]  ← copy rules for your AI editor",
+        title="rememb",
+        border_style="green",
+    ))
+
+
+app.command("init")(init_cmd)
+
+
+
+@app.command()
+def write(
+    content: str = typer.Argument(..., help="Memory content to store"),
+    section: str = typer.Option("context", "--section", "-s", help=f"Section: {', '.join(SECTIONS)}"),
+    tags: Optional[str] = typer.Option(None, "--tags", "-t", help="Comma-separated tags"),
+):
+    """Write a new memory entry."""
+    root = _root()
+    tag_list = [t.strip() for t in tags.split(",")] if tags else []
+
+    try:
+        entry = write_entry(root, section, content, tag_list)
+    except (RuntimeError, ValueError) as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    console.print(
+        f"[green]✓[/green] Saved [bold][{entry['section']}][/bold] "
+        f"[dim]id={entry['id']} at {entry['created_at']}[/dim]"
+    )
+
+
+@app.command()
+def read(
+    section: Optional[str] = typer.Option(None, "--section", "-s", help="Filter by section"),
+    raw: bool = typer.Option(False, "--raw", help="Output raw JSON"),
+    agent: bool = typer.Option(False, "--agent", help="Output optimized for agent consumption"),
+):
+    """Read memory entries."""
+    root = _root()
+
+    try:
+        entries = read_entries(root, section)
+    except RuntimeError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    if not entries:
+        console.print("[dim]No entries found.[/dim]")
+        raise typer.Exit()
+
+    if raw:
+        import json
+        print(json.dumps(entries, indent=2))
+        return
+
+    if agent:
+        _print_agent_format(entries)
+        return
+
+    _print_table(entries)
+
+
+@app.command()
+def search(
+    query: str = typer.Argument(..., help="Search query"),
+    top_k: int = typer.Option(5, "--top", "-k", help="Number of results"),
+    agent: bool = typer.Option(False, "--agent", help="Output optimized for agent consumption"),
+):
+    """Search memory entries semantically (falls back to keyword)."""
+    root = _root()
+
+    try:
+        results = search_entries(root, query, top_k)
+    except RuntimeError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    if not results:
+        console.print("[dim]No results found.[/dim]")
+        raise typer.Exit()
+
+    if agent:
+        _print_agent_format(results)
+        return
+
+    console.print(f"\n[bold]Top {len(results)} results for:[/bold] [italic]{query}[/italic]\n")
+    _print_table(results)
+
+
+@app.command()
+def rules(
+    editor: Optional[str] = typer.Argument(None, help="Editor: windsurf, cursor, claude, continue, vscode, all"),
+):
+    """Print ready-to-use agent rules/instructions for your editor."""
+    _rules = _build_rules()
+
+    editors = {
+        "windsurf": ("Windsurf / Cascade", "windsurf_rules"),
+        "cursor": ("Cursor", "cursor_rules"),
+        "claude": ("Claude / Claude.md", "claude_rules"),
+        "continue": ("Continue.dev", "continue_rules"),
+        "vscode": ("VS Code + Copilot", "vscode_rules"),
+    }
+
+    if not editor:
+        console.print("\n[bold]Available editors:[/bold]\n")
+        for key, (label, _) in editors.items():
+            console.print(f"  [cyan]rememb rules {key}[/cyan]  [dim]→ {label}[/dim]")
+        console.print()
+        return
+
+    if editor.lower() == "all":
+        for key, (label, rule_key) in editors.items():
+            print(_rules[rule_key])
+            print()
+        return
+
+    if editor.lower() not in editors:
+        console.print(f"[red]Unknown editor:[/red] {editor}. Choose from: {', '.join(editors)}")
+        raise typer.Exit(1)
+
+    label, key = editors[editor.lower()]
+    print(_rules[key])
+
+
+def _build_rules() -> dict:
+    base = (
+        "# rememb\n\n"
+        "You have access to `rememb`, a CLI tool for persistent memory across sessions.\n"
+        "Use it to remember and retrieve context about this project and user.\n\n"
+        "## Reading memory\n"
+        "Run `rememb read --agent` to load all stored context before responding.\n"
+        "Run `rememb search \"<topic>\" --agent` to find specific information.\n\n"
+        "## Writing memory\n"
+        "Run `rememb write \"<summary>\" --section <section>` when you learn something worth remembering.\n"
+        "Available sections: project | actions | systems | requests | user | context\n\n"
+        "## Rules\n"
+        "- Always read memory at the start of a new session\n"
+        "- Save important context after learning it — don't wait\n"
+        "- Keep entries short (1-3 sentences)\n"
+        "- Use --tags to categorize: `rememb write \"...\" --section project --tags tag1,tag2`\n"
+    )
+
+    windsurf = (
+        base +
+        "\n# Where to place (Windsurf / Cascade)\n"
+        "- Settings → Cascade → Custom Instructions\n"
+        "- Or: .windsurfrules at project root\n"
+    )
+
+    cursor = (
+        base +
+        "\n# Where to place (Cursor)\n"
+        "- .cursorrules at project root\n"
+        "- Or: Settings → Rules for AI\n"
+    )
+
+    claude = (
+        base +
+        "\n# Where to place (Claude Code)\n"
+        "- CLAUDE.md at project root (auto-read every session)\n"
+    )
+
+    continue_dev = (
+        base +
+        "\n# Where to place (Continue.dev)\n"
+        "- config.json → models[].systemMessage\n"
+        "- Or: .continuerc.json → systemMessage\n"
+    )
+
+    vscode = (
+        base +
+        "\n# Where to place (VS Code + Copilot)\n"
+        "- .github/copilot-instructions.md at project root (auto-read by Copilot)\n"
+    )
+
+    return {
+        "windsurf_rules": windsurf,
+        "cursor_rules": cursor,
+        "claude_rules": claude,
+        "continue_rules": continue_dev,
+        "vscode_rules": vscode,
+    }
+
+
+def _print_table(entries: list[dict]) -> None:
+    table = Table(box=box.ROUNDED, show_header=True, header_style="bold cyan")
+    table.add_column("ID", style="dim", width=10)
+    table.add_column("Section", style="bold", width=12)
+    table.add_column("Content")
+    table.add_column("Tags", style="dim", width=20)
+    table.add_column("Date", style="dim", width=22)
+
+    for e in entries:
+        table.add_row(
+            e["id"],
+            e["section"],
+            e["content"],
+            ", ".join(e.get("tags", [])) or "-",
+            e["created_at"],
+        )
+
+    console.print(table)
+
+
+def _print_agent_format(entries: list[dict]) -> None:
+    """Compact format optimized for LLM context consumption."""
+    by_section: dict[str, list] = {}
+    for e in entries:
+        by_section.setdefault(e["section"], []).append(e)
+
+    output = ["# Memory Context (rememb)\n"]
+    for section, items in by_section.items():
+        output.append(f"## {section.capitalize()}")
+        for item in items:
+            tags = f" [{', '.join(item['tags'])}]" if item.get("tags") else ""
+            output.append(f"- {item['content']}{tags}")
+        output.append("")
+
+    print("\n".join(output))

rememb-0.1.0/src/rememb/store.py

@@ -0,0 +1,175 @@
+"""Core storage engine for .rememb/"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+REMEMB_DIR = ".rememb"
+GLOBAL_REMEMB_DIR = Path.home() / ".rememb"
+ENTRIES_FILE = "entries.json"
+META_FILE = "meta.json"
+
+SECTIONS = ["project", "actions", "systems", "requests", "user", "context"]
+
+
+def global_root() -> Path:
+    """Returns the global memory root: ~/.rememb/"""
+    return Path.home()
+
+
+def _rememb_path(root: Path) -> Path:
+    return root / REMEMB_DIR
+
+
+def _entries_path(root: Path) -> Path:
+    return _rememb_path(root) / ENTRIES_FILE
+
+
+def _meta_path(root: Path) -> Path:
+    return _rememb_path(root) / META_FILE
+
+
+def find_root(start: Optional[Path] = None, local: bool = False) -> Path:
+    """Find .rememb/ root.
+
+    Priority:
+    1. Walk up from start looking for a local .rememb/ (if --local or found naturally)
+    2. Fall back to global ~/.rememb/
+    """
+    current = (start or Path.cwd()).resolve()
+    for parent in [current, *current.parents]:
+        if (parent / REMEMB_DIR).is_dir():
+            return parent
+
+    if local:
+        return current
+
+    return global_root()
+
+
+def is_initialized(root: Path) -> bool:
+    return _entries_path(root).exists()
+
+
+def init(root: Path, project_name: str = "", global_mode: bool = False) -> Path:
+    rememb = _rememb_path(root)
+    rememb.mkdir(parents=True, exist_ok=True)
+
+    entries_file = _entries_path(root)
+    if not entries_file.exists():
+        entries_file.write_text(json.dumps([], indent=2), encoding="utf-8")
+
+    meta_file = _meta_path(root)
+    if not meta_file.exists():
+        meta = {
+            "version": "1",
+            "project": project_name or ("global" if global_mode else root.name),
+            "created_at": _now(),
+            "sections": SECTIONS,
+        }
+        meta_file.write_text(json.dumps(meta, indent=2), encoding="utf-8")
+
+    if not global_mode:
+        gitignore = root / ".gitignore"
+        gitignore_line = ".rememb/embeddings.npy\n"
+        if gitignore.exists():
+            content = gitignore.read_text(encoding="utf-8")
+            if gitignore_line.strip() not in content:
+                gitignore.write_text(content.rstrip() + "\n" + gitignore_line, encoding="utf-8")
+
+    return rememb
+
+
+def write_entry(root: Path, section: str, content: str, tags: list[str] | None = None) -> dict:
+    if not is_initialized(root):
+        raise RuntimeError("rememb not initialized. Run `rememb init` first.")
+
+    section = section.lower()
+    if section not in SECTIONS:
+        raise ValueError(f"Invalid section '{section}'. Choose from: {', '.join(SECTIONS)}")
+
+    entries = _load_entries(root)
+    entry = {
+        "id": str(uuid.uuid4())[:8],
+        "section": section,
+        "content": content,
+        "tags": tags or [],
+        "created_at": _now(),
+    }
+    entries.append(entry)
+    _save_entries(root, entries)
+    return entry
+
+
+def read_entries(root: Path, section: Optional[str] = None) -> list[dict]:
+    if not is_initialized(root):
+        raise RuntimeError("rememb not initialized. Run `rememb init` first.")
+    entries = _load_entries(root)
+    if section:
+        entries = [e for e in entries if e["section"] == section.lower()]
+    return entries
+
+
+def search_entries(root: Path, query: str, top_k: int = 5) -> list[dict]:
+    """Semantic search using sentence-transformers. Falls back to keyword search."""
+    entries = _load_entries(root)
+    if not entries:
+        return []
+
+    try:
+        return _semantic_search(root, entries, query, top_k)
+    except Exception:
+        return _keyword_search(entries, query, top_k)
+
+
+def _semantic_search(root: Path, entries: list[dict], query: str, top_k: int) -> list[dict]:
+    import numpy as np
+    from sentence_transformers import SentenceTransformer
+
+    model = SentenceTransformer("all-MiniLM-L6-v2")
+    texts = [e["content"] for e in entries]
+
+    embeddings_path = _rememb_path(root) / "embeddings.npy"
+    if embeddings_path.exists():
+        embeddings = np.load(str(embeddings_path))
+        if len(embeddings) != len(texts):
+            embeddings = model.encode(texts)
+            np.save(str(embeddings_path), embeddings)
+    else:
+        embeddings = model.encode(texts)
+        np.save(str(embeddings_path), embeddings)
+
+    query_vec = model.encode([query])[0]
+    scores = np.dot(embeddings, query_vec) / (
+        np.linalg.norm(embeddings, axis=1) * np.linalg.norm(query_vec) + 1e-9
+    )
+    top_indices = np.argsort(scores)[::-1][:top_k]
+    return [entries[i] for i in top_indices]
+
+
+def _keyword_search(entries: list[dict], query: str, top_k: int) -> list[dict]:
+    q = query.lower()
+    scored = []
+    for entry in entries:
+        score = entry["content"].lower().count(q)
+        if score > 0:
+            scored.append((score, entry))
+    scored.sort(key=lambda x: x[0], reverse=True)
+    return [e for _, e in scored[:top_k]]
+
+
+def _load_entries(root: Path) -> list[dict]:
+    raw = _entries_path(root).read_text(encoding="utf-8")
+    return json.loads(raw)
+
+
+def _save_entries(root: Path, entries: list[dict]) -> None:
+    _entries_path(root).write_text(json.dumps(entries, indent=2), encoding="utf-8")
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")

rememb-0.1.0/src/rememb.egg-info/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: rememb
+Version: 0.1.0
+Summary: Persistent memory standard for AI agents — local, portable, zero config
+License: MIT
+Project-URL: Homepage, https://github.com/LuizEduPP/rememb
+Project-URL: Repository, https://github.com/LuizEduPP/rememb
+Project-URL: Issues, https://github.com/LuizEduPP/rememb/issues
+Keywords: ai,agents,memory,llm,mcp,windsurf,cursor,claude,copilot,continue,vscode,persistent-memory,ai-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: sentence-transformers>=3.0.0
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# rememb
+
+> **Persistent memory for AI agents — local, portable, zero config.**
+
+![rememb demo](demo/demo.gif)
+
+AI agents (Windsurf, Cursor, Claude, Continue) forget everything between sessions.  
+`rememb` gives them a structured memory that lives in your project, belongs to you, and works with any agent.
+
+---
+
+## The problem
+
+Every developer using AI agents hits this wall:
+
+```
+Session 1: "We're using PostgreSQL, the auth module is at src/auth/, prefer async patterns."
+Session 2: Agent starts from zero. You explain everything again.
+Session 3: Same thing.
+```
+
+Existing solutions (Mem0, Zep, Letta) require servers, API keys, cloud accounts, and framework lock-in.  
+You just want the agent to **remember your project**.
+
+---
+
+## The solution
+
+```
+.rememb/
+  entries.json   ← structured memory (project, actions, systems, user, context)
+  meta.json      ← project metadata
+```
+
+That's it. A JSON file in your project. Your agent reads it at the start of every session.
+
+---
+
+## Install
+
+```bash
+git clone https://github.com/LuizEduPP/rememb.git
+cd rememb
+pip install -e .
+```
+
+---
+
+## Quickstart
+
+```bash
+# Initialize in your project
+rememb init
+
+# Write memories
+rememb write "Project uses FastAPI + PostgreSQL + async patterns" --section project
+rememb write "User prefers direct answers, no filler text" --section user
+rememb write "Auth module lives at src/auth/, JWT-based" --section systems
+
+# Read everything (for the agent)
+rememb read --agent
+
+# Search semantically
+rememb search "authentication"
+
+# Get ready-to-use rules for your editor
+rememb rules windsurf
+rememb rules cursor
+rememb rules claude
+rememb rules continue
+rememb rules vscode
+```
+
+---
+
+## Agent integration
+
+**Configure once. Works forever.**
+
+Run `rememb rules <editor>` to get the instructions for your editor, then paste them once. From that point on, your agent automatically reads and writes memory on every session.
+
+```bash
+rememb rules windsurf   # Windsurf / Cascade
+rememb rules cursor     # Cursor
+rememb rules claude     # Claude Code
+rememb rules continue   # Continue.dev
+rememb rules vscode     # VS Code + Copilot
+```
+
+| Editor | Where to paste |
+|--------|---------------|
+| **Windsurf / Cascade** | `.windsurfrules` at project root — or Settings → Cascade → Custom Instructions |
+| **Cursor** | `.cursorrules` at project root — or Settings → Rules for AI |
+| **Claude Code** | `CLAUDE.md` at project root (auto-read every session) |
+| **Continue.dev** | `config.json` → `models[].systemMessage` |
+| **VS Code + Copilot** | `.github/copilot-instructions.md` at project root (auto-read by Copilot) |
+
+---
+
+## Memory sections
+
+| Section | What to store |
+|---------|---------------|
+| `project` | Tech stack, architecture, goals |
+| `actions` | What was done, decisions made |
+| `systems` | Services, modules, integrations |
+| `requests` | User preferences, recurring asks |
+| `user` | Name, style, expertise, preferences |
+| `context` | Anything else relevant |
+
+---
+
+## Commands
+
+```
+rememb init              Initialize .rememb/ in current project
+rememb write <text>      Write a memory entry (--section, --tags)
+rememb read              Read all entries (--section, --agent, --raw)
+rememb search <query>    Semantic search (falls back to keyword)
+rememb rules [editor]    Print agent rules for windsurf/cursor/claude/continue
+```
+
+---
+
+## How search works
+
+`rememb search` uses `sentence-transformers` for semantic similarity search locally.  
+No API calls. No embeddings sent to the cloud. Falls back to keyword search if the model isn't available.
+
+---
+
+## Design principles
+
+- **Local first** — everything is a JSON file in your project
+- **Portable** — copy `.rememb/` and it works anywhere
+- **Agnostic** — works with any agent that can run CLI commands
+- **Zero config** — `pip install rememb && rememb init` and you're done
+- **No lock-in** — plain JSON, read it with anything
+
+---
+
+## Roadmap
+
+- [ ] MCP server (`rememb mcp`) for native IDE integration
+- [ ] `rememb sync` — optional encrypted remote backup
+- [ ] `rememb export` — export to Markdown, Obsidian, Notion
+- [ ] VS Code / Windsurf extension
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/LuizEduPP/rememb
+cd rememb
+pip install -e ".[dev]"
+```
+
+PRs welcome. Issues welcome. Stars welcome. 🌟
+
+---
+
+## License
+
+MIT

rememb-0.1.0/src/rememb.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+MANIFEST.in
+README.md
+pyproject.toml
+demo/demo.gif
+rules/claude.md
+rules/continue.md
+rules/cursor.md
+rules/vscode.md
+rules/windsurf.md
+src/rememb/__init__.py
+src/rememb/cli.py
+src/rememb/store.py
+src/rememb.egg-info/PKG-INFO
+src/rememb.egg-info/SOURCES.txt
+src/rememb.egg-info/dependency_links.txt
+src/rememb.egg-info/entry_points.txt
+src/rememb.egg-info/requires.txt
+src/rememb.egg-info/top_level.txt

rememb-0.1.0/src/rememb.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rememb-0.1.0/src/rememb.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rememb = rememb.cli:app

rememb-0.1.0/src/rememb.egg-info/requires.txt

@@ -0,0 +1,8 @@
+typer>=0.12.0
+rich>=13.0.0
+sentence-transformers>=3.0.0
+numpy>=1.24.0
+
+[dev]
+build
+twine

rememb-0.1.0/src/rememb.egg-info/top_level.txt

@@ -0,0 +1 @@
+rememb