Metadata-Version: 2.4
Name: rememb
Version: 0.1.4
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
License-File: LICENSE
Requires-Dist: typer>=0.12.0
Requires-Dist: rich>=13.0.0
Provides-Extra: semantic
Requires-Dist: sentence-transformers>=3.0.0; extra == "semantic"
Requires-Dist: numpy>=1.24.0; extra == "semantic"
Provides-Extra: pdf
Requires-Dist: pypdf>=4.0.0; extra == "pdf"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# rememb

> **Persistent memory for AI agents — local, portable, zero config.**

![rememb demo](https://raw.githubusercontent.com/LuizEduPP/rememb/main/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
pip install rememb
```

For semantic search support:

```bash
pip install rememb[semantic]
```

---

## 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 import <folder>   Import .md/.txt/.pdf files into memory (--section, --recursive, --dry-run)
rememb rules [editor]    Print agent rules for windsurf/cursor/claude/continue/vscode
```

---

## 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

### Coming soon
- [x] `rememb import <folder>` — import `.md`, `.txt`, `.pdf` files into memory (`--section`, `--recursive`, `--dry-run`)
- [ ] `rememb delete <id>` — remove a memory entry
- [ ] `rememb edit <id>` — update an existing entry
- [ ] `rememb export` — export memory to Markdown / Obsidian / Notion

### Planned
- [ ] MCP server (`rememb mcp`) — native IDE integration, no CLI required
- [ ] `rememb sync` — sync `~/.rememb/` across machines via private git
- [ ] `rememb web` — local browser UI to manage memories visually
- [ ] 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
