Metadata-Version: 2.4
Name: memoria-ai
Version: 0.1.0
Summary: A private AI mirror for personal reflection - based on Matthew McConaughey's Aspirational Self concept
Author: Your Name
License: MIT
Keywords: ai,journal,reflection,personal,ollama
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
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: Topic :: Text Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: python-frontmatter>=1.0
Requires-Dist: ollama>=0.1.0
Requires-Dist: markdown>=3.5
Requires-Dist: watchdog>=3.0
Requires-Dist: flask>=3.0
Requires-Dist: flask-cors>=4.0
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == "embeddings"
Requires-Dist: numpy>=1.24.0; extra == "embeddings"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Dynamic: license-file

# Memoria - GitHub-Based User Memory System

Extracts user preferences and patterns from GitHub data to build a personalized memory profile.

## Purpose

Memoria analyzes a user's GitHub activity to understand:
- **Programming language preferences**
- **Framework and library choices**
- **Commit patterns and work style**
- **Project domains and interests**
- **Collaboration patterns**
- **Code style preferences**

This data is stored as "memories" that can be used for:
- Personalized recommendations
- Automated decision-making
- Context-aware assistance
- Predictive suggestions

## Architecture

```
memoria/
├── src/
│   ├── github_fetcher.py    # Fetch GitHub user data
│   ├── pattern_analyzer.py   # Analyze code patterns
│   ├── preference_extractor.py # Extract user preferences
│   └── memory_builder.py    # Build memory profile
├── data/
│   ├── users/               # Per-user memory profiles
│   │   └── {username}.json
│   ├── patterns.json         # Common coding patterns
│   └── preferences.json      # Preference taxonomy
├── memory/
│   ├── short_term/          # Recent context (session-based)
│   └── long_term/          # Persistent preferences
├── tests/
│   └── test_memoria.py      # Unit tests
├── requirements.txt
└── README.md
```

## Memory Types

### Short-Term Memory
- Current working directory
- Active files being edited
- Recent commands/actions
- Current task context
- **Lifespan**: ~1-4 hours

### Long-Term Memory
- Language preferences (Python, Rust, Go, etc.)
- Framework choices (React, Next.js, Svelte, etc.)
- Testing frameworks (pytest, Jest, etc.)
- CI/CD tools (GitHub Actions, CircleCI, etc.)
- Cloud providers (AWS, GCP, Azure)
- Editor preferences (VS Code, Vim, etc.)
- **Lifespan**: Persistent until explicitly updated

## Usage

```bash
# Analyze a GitHub user and build memory
python3 -m src.memory_builder --username jasperan

# Query user memory
python3 -m src.memory_query --username jasperan --query language_preference

# Update specific memory entry
python3 -m src.memory_update --username jasperan --key language_preference --value Rust

# Export memory profile
python3 -m src.memory_export --username jasperan --format json
```

## Data Sources

### GitHub API Endpoints
- `/users/{username}` - Basic profile
- `/repos` - Repository list
- `/repos/{owner}/{repo}/languages` - Language usage
- `/repos/{owner}/{repo}/commits` - Commit patterns
- `/repos/{owner}/{repo}/contents/.editorconfig` - Editor config
- `/repos/{owner}/{repo}/contents/{path}` - File analysis

## Preference Taxonomy

### Language Preferences
- Primary languages (by LOC)
- Secondary languages (by repo count)
- New languages learning (recent repos)

### Framework Preferences
- Frontend: React, Vue, Svelte, Angular
- Backend: Express, Django, FastAPI, Flask
- Database: PostgreSQL, MongoDB, Redis

### Tool Preferences
- Version control: Git, GitHub actions
- Testing: pytest, jest, mocha
- Deployment: Docker, Kubernetes
- Package managers: npm, cargo, pip, go

### Style Preferences
- Code formatting (black, prettier, rustfmt)
- Linting (eslint, pylint, clippy)
- Naming conventions (snake_case, camelCase, etc.)

## Example Memory Profile

```json
{
  "user_id": "jasperan",
  "last_updated": "2026-02-11T10:00:00Z",
  "languages": {
    "python": 0.45,
    "rust": 0.35,
    "javascript": 0.15,
    "go": 0.05
  },
  "frameworks": {
    "frontend": ["Next.js", "React"],
    "backend": ["FastAPI", "Django"],
    "database": ["PostgreSQL", "Redis"]
  },
  "tools": {
    "testing": ["pytest", "jest"],
    "deployment": ["Docker", "GitHub Actions"],
    "editor": "VS Code"
  },
  "patterns": {
    "commit_frequency": "medium",
    "repo_size": "small_to_medium",
    "collaboration_style": "mixed"
  },
  "domains": [
    "machine_learning",
    "web_development",
    "ai_agents",
    "trading_bots"
  ]
}
```

## API

### Memory Query API

```python
from src.memory import Memory

memory = Memory.load("jasperan")

# Query preferences
language = memory.get("languages.primary")  # "python"
framework = memory.get("frameworks.backend")  # ["FastAPI", "Django"]

# Suggest based on memory
suggestion = memory.suggest("testing_framework")  # "pytest"

# Update memory
memory.set("tools.editor", "Neovim")
memory.save()
```

## Integration with OpenClaw

Memoria can be used by OpenClaw agents to:
- Make personalized suggestions
- Choose appropriate tools for tasks
- Understand user's coding style
- Predict preferences based on patterns

```python
# In an OpenClaw agent
from memoria import Memory

memory = Memory.load(user_id)

# Suggest testing framework
if memory.get("languages.primary") == "python":
    return "Use pytest"
elif memory.get("languages.primary") == "rust":
    return "Use cargo test"
```

## Privacy

- Memory data stored locally (`memory/long_term/`)
- GitHub API calls authenticated (requires GITHUB_TOKEN)
- User can delete memory profiles
- No data shared with external services

## PROJECT_UPDATES

See `PROJECT_UPDATES.md` for recent changes.

## License

MIT
