memclaw 0.1.0__tar.gz

memclaw-0.1.0/.env.example

@@ -0,0 +1,9 @@
+# Required for embeddings and image descriptions
+OPENAI_API_KEY=your-openai-key
+
+# Required for the Claude agent (interactive mode + /ask command)
+ANTHROPIC_API_KEY=your-anthropic-key
+
+# Telegram bot settings
+TELEGRAM_BOT_TOKEN=your-telegram-bot-token
+ALLOWED_USER_IDS=123456789,987654321

memclaw-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest

memclaw-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

memclaw-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.env
+.envrc
+.venv
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDEs
+.idea/
+.vscode/
+.cursorignore
+.cursorindexingignore
+
+# Type checkers / linters
+.mypy_cache/
+.ruff_cache/
+
+# Memclaw local data
+.memclaw/

memclaw-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,38 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainers at emanuilo.jovanovic@hotmail.com. All
+complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

memclaw-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,76 @@
+# Contributing to Memclaw
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+```bash
+git clone https://github.com/emanuilo/memclaw.git
+cd memclaw
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Copy the environment template and fill in your keys:
+
+```bash
+cp .env.example .env
+```
+
+## Running Tests
+
+```bash
+pytest
+```
+
+All tests should pass before submitting a PR. The test suite mocks external API calls, so no API keys are needed to run tests.
+
+## Code Style
+
+- Follow PEP 8 conventions
+- Use type hints for function signatures
+- Keep functions focused and small
+- Run `ruff check .` before committing
+
+## Making Changes
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Make your changes
+4. Add or update tests as needed
+5. Run the test suite (`pytest`)
+6. Run the linter (`ruff check .`)
+7. Commit with a clear message (`git commit -m 'feat: add my feature'`)
+8. Push to your fork (`git push origin feature/my-feature`)
+9. Open a Pull Request
+
+## Commit Messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) style:
+
+- `feat:` new feature
+- `fix:` bug fix
+- `docs:` documentation only
+- `test:` adding or updating tests
+- `chore:` maintenance, dependencies, CI
+
+## Pull Requests
+
+- Keep PRs focused on a single change
+- Include tests for new functionality
+- Update documentation if behavior changes
+- Link related issues in the PR description
+
+## Reporting Bugs
+
+Open an issue with:
+
+- Steps to reproduce
+- Expected vs actual behavior
+- Python version and OS
+- Relevant logs or error messages
+
+## Questions?
+
+Open a [discussion](https://github.com/emanuilo/memclaw/issues) or reach out in an issue.

memclaw-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Memclaw Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memclaw-0.1.0/PKG-INFO

@@ -0,0 +1,324 @@
+Metadata-Version: 2.4
+Name: memclaw
+Version: 0.1.0
+Summary: A lightweight, local-first personal memory assistant powered by AI
+Project-URL: Repository, https://github.com/emanuilo/memclaw
+Project-URL: Issues, https://github.com/emanuilo/memclaw/issues
+Author-email: Emanuilo Jovanovic <emanuilo.jovanovic@hotmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,assistant,memory,personal-knowledge,second-brain,vector-search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: claude-agent-sdk>=0.1.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: loguru>=0.7.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: python-telegram-bot>=21.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=1.0.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Memclaw
+
+**Your personal memory vault, powered by AI.**
+
+Store your thoughts. Save your images and links. Ask anything, anytime.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Claude Agent SDK](https://img.shields.io/badge/Claude-Agent_SDK-blueviolet.svg)](https://platform.claude.com/docs/en/agent-sdk/overview)
+[![Telegram Bot](https://img.shields.io/badge/Telegram-Bot-26A5E4.svg)](https://core.telegram.org/bots)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+
+</div>
+
+---
+
+Memclaw is a lightweight, local-first personal memory assistant. It stores your thoughts, notes, images, and links as **plain Markdown files** and makes them instantly searchable through **hybrid vector + keyword search**.
+
+Think of it as your second brain — one that actually remembers.
+
+## Why Memclaw?
+
+[OpenClaw](https://github.com/openclaw/openclaw) is great — but it connects to dozens of tools, reads your filesystem, runs shell commands, and does a hundred things you didn't ask for. That makes it slow, expensive, and a security surface you have to think about every time you use it.
+
+Memclaw takes one slice of what OpenClaw does — **memory** — and does it really well, without the rest.
+
+**Total recall.** Save a thought today, retrieve it six months later with a vague description. *"What was that restaurant Alex told me about?"* — Memclaw finds it. Hybrid vector + keyword search means you don't need to remember exact words.
+
+**Visual memory.** Send an image and Memclaw generates an AI caption, indexes it, and stores it. Later, just ask *"that food recipe photo"* or *"the whiteboard from last sprint"* and it comes right back.
+
+**Link memory.** Drop a link and Memclaw fetches the page, summarizes it, and indexes the content. Months later, ask *"that article about distributed databases"* and it surfaces the link with context — no bookmarking app needed.
+
+**Sandboxed by design.** Memclaw only touches `~/.memclaw/`. No filesystem access, no shell commands, no path traversal. You don't need to trust it with your whole computer — it can't see it.
+
+**Lightweight and cheap.** No Docker. No Postgres. No sprawling tool graph burning tokens. Just Python, SQLite, and two API keys. Fast responses, minimal cost.
+
+## Quick Start
+
+```bash
+pip install memclaw
+memclaw
+```
+
+On first run, Memclaw will prompt you for your API keys and save them to `~/.memclaw/.env`. You can update them anytime with `memclaw configure`.
+
+## Telegram Bot
+
+The main way to use Memclaw. Just talk to it naturally — no commands needed. Send text, photos, voice messages, or links. The agent figures out what to do: store it, search your memories, retrieve images, or just chat.
+
+The bot shows a **typing indicator** while processing so you know it's working on your request.
+
+### Setup
+
+1. Create a bot via [@BotFather](https://t.me/BotFather) and copy the token.
+2. Get your Telegram user ID (e.g. via [@userinfobot](https://t.me/userinfobot)).
+3. Start the bot — on first run you'll be prompted for all keys:
+
+```bash
+memclaw bot
+```
+
+To update keys later: `memclaw configure`.
+
+### What it handles
+
+| Message type | What happens |
+|-------------|-------------|
+| **Text** | Agent decides: store as memory, search existing memories, or both. Links are extracted, fetched, and summarized automatically. |
+| **Photo** | AI-described via vision model, stored and indexed. Agent acknowledges and responds. File ID saved for later retrieval. |
+| **Voice** | Transcribed via Whisper, stored as text. Agent responds to the content. Links extracted. |
+
+### Examples
+
+```
+> Just had coffee with Alex. She's moving to Berlin for a role at Stripe.
+Got it! I've saved that Alex is moving to Berlin for a new role at Stripe.
+
+> Who is Alex?
+Based on your memories, Alex is someone you had coffee with recently.
+She's moving to Berlin for a new role at Stripe.
+
+> Show me the whiteboard photo from last week
+[sends the matching photo]
+Here's the sprint planning whiteboard you saved last week.
+```
+
+## How It Works
+
+```mermaid
+flowchart LR
+    You -->|text / images / links| Agent[Memclaw Agent]
+
+    subgraph sandbox ["~/.memclaw/"]
+        Agent -->|save| Tools1["memory_save<br>image_save<br>file_write"]
+        Tools1 --> Files["MEMORY.md<br>daily/*.md<br>AGENTS.md"]
+        Files --> DB[("SQLite<br>FTS5 + Vectors")]
+        DB --> Tools2["memory_search<br>image_search"]
+        Tools2 -->|results| Agent
+    end
+
+    Agent -->|response + images| You
+```
+
+Memclaw draws inspiration from [OpenClaw](https://github.com/openclaw/openclaw)'s memory architecture and is built with the [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview).
+
+### Storage Layer
+
+All memories are plain Markdown — human-readable, editable, and git-friendly.
+
+| File | Purpose |
+|------|---------|
+| `~/.memclaw/MEMORY.md` | Curated long-term facts and preferences |
+| `~/.memclaw/AGENTS.md` | Customizable agent instructions and user preferences |
+| `~/.memclaw/memory/YYYY-MM-DD.md` | Timestamped daily entries |
+| `~/.memclaw/memclaw.db` | SQLite index (vector embeddings + FTS5) |
+
+### Search Layer
+
+Every memory is chunked, embedded, and indexed in SQLite. Retrieval combines two signals:
+
+- **Vector search** (70% weight) — cosine similarity via OpenAI embeddings finds semantically related memories even when wording differs
+- **Keyword search** (30% weight) — BM25 via SQLite FTS5 catches exact tokens, names, and identifiers
+- **Temporal decay** — recent memories score higher (30-day half-life), MEMORY.md entries are evergreen
+- **MMR deduplication** — removes near-duplicate results to keep search diverse
+
+### Agent Layer
+
+Powered by Claude via the [Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview). The agent maintains a rolling 10-message-pair conversation history and decides when to **store** vs **search** based on your intent.
+
+| Tool | What it does |
+|------|-------------|
+| `memory_save` | Writes a new entry to today's daily file or MEMORY.md |
+| `memory_search` | Hybrid search across all indexed memories |
+| `image_save` | Generates an AI description of an image and stores it |
+| `image_search` | Retrieves previously stored images by description |
+| `file_write` / `file_read` | Sandboxed file operations within `~/.memclaw/` |
+| `update_instructions` | Appends user preferences to AGENTS.md |
+
+## Usage
+
+### Interactive Mode (default)
+
+```bash
+memclaw
+```
+
+Chat naturally:
+
+```
+> Just had coffee with Alex. She's moving to Berlin next month for a new role at Stripe.
+✓ Memory saved
+
+> Who is Alex?
+Based on your memories, Alex is someone you had coffee with recently.
+She's moving to Berlin for a new role at Stripe.
+
+> /quit
+```
+
+### Direct Commands
+
+These work without the Claude agent — only the OpenAI key is needed for embeddings.
+
+```bash
+# Save a quick note
+memclaw save "Meeting at 3pm with the design team about the rebrand"
+
+# Search your memories
+memclaw search "design team meetings"
+
+# Consolidate daily files into MEMORY.md
+memclaw consolidate
+
+# Rebuild the search index
+memclaw index
+
+# Check your memory vault
+memclaw status
+```
+
+### Saving Images
+
+In interactive mode, tell the agent to save an image:
+
+```
+> Save the image at ~/photos/whiteboard.jpg — it's our sprint planning board
+✓ Image saved: A whiteboard showing a sprint planning layout with colorful sticky notes...
+```
+
+The image is described by an AI vision model and the description is stored and indexed like any other memory.
+
+## Configuration
+
+On first run, `memclaw` or `memclaw bot` will launch an interactive setup wizard that saves your keys to `~/.memclaw/.env`. Run `memclaw configure` anytime to update them.
+
+You can also set keys via environment variables or a `.env` in the current directory — these take the usual precedence over the saved config.
+
+```bash
+memclaw --memory-dir ~/my-vault   # override storage location
+```
+
+### API Keys
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OPENAI_API_KEY` | Yes | Embeddings + image descriptions |
+| `ANTHROPIC_API_KEY` | Yes | Powers the Claude agent |
+| `TELEGRAM_BOT_TOKEN` | For Telegram bot | Your Telegram bot token |
+| `ALLOWED_USER_IDS` | For Telegram bot | Comma-separated Telegram user IDs |
+
+### Directory Structure
+
+```
+~/.memclaw/
+├── MEMORY.md              # Permanent / curated memories
+├── AGENTS.md              # Agent instructions + user preferences
+├── memclaw.db             # SQLite index (embeddings + FTS5)
+└── memory/
+    ├── 2025-06-15.md      # Daily notes
+    ├── 2025-06-16.md
+    └── ...
+```
+
+## Architecture
+
+Inspired by [OpenClaw](https://github.com/openclaw/openclaw)'s approach to AI memory:
+
+- **Markdown as source of truth** — all memories live as plain text you can read, edit, and version-control
+- **SQLite for indexing** — zero-config database with FTS5 for keyword search and BLOBs for embeddings
+- **NumPy for vectors** — cosine similarity computed in-memory, no native extensions required
+- **Claude Agent SDK** — intelligent agent loop that autonomously decides how to handle your input
+- **Chunking with overlap** — ~300-word chunks with 60-word overlap preserve context across boundaries
+- **Auto-consolidation** — daily files are periodically distilled into MEMORY.md
+- **Filesystem guardrail** — SDK-level callback blocks all file access outside `~/.memclaw/`
+- **Embedding cache** — SHA-256 content hashing skips redundant API calls
+
+For a deep dive into how memory storage, search, consolidation, and context injection work, see the [Memory Architecture](docs/memory-architecture.md) doc.
+
+## Using as a Library
+
+```python
+import asyncio
+from memclaw.config import MemclawConfig
+from memclaw.store import MemoryStore
+from memclaw.index import MemoryIndex
+from memclaw.search import HybridSearch
+
+async def main():
+    config = MemclawConfig()
+    store = MemoryStore(config)
+    index = MemoryIndex(config)
+    search = HybridSearch(config, index)
+
+    # Save a memory
+    path = store.save("The best pizza in town is at Mario's on 5th Ave")
+    await index.index_file(path)
+
+    # Search
+    results = await search.search("pizza recommendations")
+    for r in results:
+        print(f"{r.score:.2f}: {r.content[:80]}")
+
+    index.close()
+
+asyncio.run(main())
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+## Acknowledgments
+
+- [OpenClaw](https://github.com/openclaw/openclaw) for the memory architecture inspiration
+- [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) for the agent framework
+- [SQLite FTS5](https://www.sqlite.org/fts5.html) for full-text search