{"id":46076065,"url":"https://github.com/ry-ops/aiana","last_synced_at":"2026-03-01T14:35:06.428Z","repository":{"id":336042241,"uuid":"1087358411","full_name":"ry-ops/aiana","owner":"ry-ops","description":"AI conversation attendant for Claude Code - monitors and records conversations in real-time via Claude Code API","archived":false,"fork":false,"pushed_at":"2026-02-15T02:25:56.000Z","size":3915,"stargazers_count":1,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-15T09:37:07.591Z","etag":null,"topics":["ai","claude","claude-code","conversation-logging","mcp","mcp-server","memory","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ry-ops.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-31T19:21:18.000Z","updated_at":"2026-02-15T02:24:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ry-ops/aiana","commit_stats":null,"previous_names":["ry-ops/aiana"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/ry-ops/aiana","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Faiana","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Faiana/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Faiana/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Faiana/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ry-ops","download_url":"https://codeload.github.com/ry-ops/aiana/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Faiana/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29971001,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T14:11:48.712Z","status":"ssl_error","status_checked_at":"2026-03-01T14:11:48.352Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude","claude-code","conversation-logging","mcp","mcp-server","memory","python"],"created_at":"2026-03-01T14:35:05.817Z","updated_at":"2026-03-01T14:35:06.416Z","avatar_url":"https://github.com/ry-ops.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cimg src=\"https://github.com/ry-ops/aiana/blob/main/Aiana.png\" width=\"100%\"\u003e\n\n# Aiana\n\n**Personal AI Operations Memory for Claude Code**\n\nAiana transforms Claude Code from stateless sessions into a compound learning system. It captures conversations, embeds them as vectors, and injects relevant context at session start—so your AI assistant remembers YOUR patterns.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/aiana-flow.svg\" alt=\"Aiana Data Flow\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n## The Vision\n\n```\nTraditional: Sessions → Do tasks → Forget\nWith Aiana:  Sessions → Do tasks → Remember → Improve → Compound\n```\n\nEvery session makes future sessions better. Your workflows get encoded. Your preferences persist. Claude learns YOUR way of working.\n\n---\n\n## Architecture\n\n```mermaid\nflowchart TB\n    subgraph CC[\"🖥️ Claude Code\"]\n        sessions[\"Sessions \u0026 Conversations\"]\n    end\n\n    subgraph AIANA[\"🧠 AIANA - Memory Layer\"]\n        direction TB\n        capture[\"📥 Session Capture\"]\n        embed[\"🔢 Embedding Engine\u003cbr/\u003e\u003ci\u003eall-MiniLM-L6-v2\u003c/i\u003e\"]\n        inject[\"💉 Context Injector\"]\n        mcp[\"🔌 MCP Server\"]\n    end\n\n    subgraph STORAGE[\"💾 Storage Backends\"]\n        direction LR\n        sqlite[(\"📄 SQLite\u003cbr/\u003eFTS5 Full-Text\")]\n        redis[(\"⚡ Redis\u003cbr/\u003eSession Cache\")]\n        mem0[(\"🧠 Mem0\u003cbr/\u003eAI Memory\")]\n        qdrant[(\"🔮 Qdrant\u003cbr/\u003eVector Search\")]\n    end\n\n    CC --\u003e|\"hooks API\"| capture\n    capture --\u003e embed\n    embed --\u003e sqlite\n    embed --\u003e redis\n    embed --\u003e mem0\n    mem0 --\u003e qdrant\n\n    sqlite --\u003e inject\n    redis --\u003e inject\n    mem0 --\u003e inject\n\n    inject --\u003e|\"context block\"| CC\n    mcp \u003c--\u003e|\"tools\"| CC\n\n    style AIANA fill:#7C3AED,color:#fff\n    style CC fill:#D97706,color:#fff\n    style sqlite fill:#0EA5E9,color:#fff\n    style redis fill:#DC2626,color:#fff\n    style mem0 fill:#EC4899,color:#fff\n    style qdrant fill:#059669,color:#fff\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/aiana-architecture.svg\" alt=\"Aiana Architecture\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n---\n\n## Features\n\n### Storage \u0026 Search\n- **SQLite with FTS5** - Session transcripts, full-text search\n- **Redis caching** - Fast session state, context cache, preferences\n- **Qdrant vectors** - Semantic search via sentence-transformers\n- **Mem0 integration** - Enhanced AI memory with automatic extraction and deduplication\n\n### Intelligence\n- **Context injection** - Auto-inject relevant memories at session start\n- **User preferences** - Persistent (static) and recent (dynamic) prefs\n- **Semantic search** - Find memories by meaning, not just keywords\n- **Mem0 memory management** - Automatic memory consolidation and relevance scoring\n\n### Integration\n- **MCP server mode** - Expose memory tools directly to Claude\n- **Hook-based capture** - Official Claude Code hooks API\n- **File watcher** - Docker-compatible monitoring mode\n- **Auto-bootstrap** - One-and-done preference loading on first install\n\n### Privacy\n- **100% local** - All data stays on your machine\n- **No cloud sync** - Nothing leaves your system\n- **Read-only mounts** - Docker uses read-only access to Claude data\n\n---\n\n## Quick Start\n\n### Docker Compose (Recommended)\n\n```bash\n# Clone repository\ngit clone https://github.com/ry-ops/aiana\ncd aiana\n\n# Start full stack (Aiana + Redis + Qdrant)\ndocker compose up -d\n\n# Check status\ndocker compose exec aiana aiana status\n\n# Search memories\ndocker compose exec aiana aiana memory search \"authentication\"\n```\n\n### Local Installation\n\n```bash\n# Install with all features\npip install -e \".[all]\"\n\n# Or minimal install\npip install -e .\n\n# Install Claude Code hooks (auto-loads development preferences)\naiana install\n\n# Start monitoring\naiana start\n```\n\n\u003e **One-and-Done**: The `aiana install` command automatically bootstraps your development preferences into memory. No manual configuration needed - your standards are immediately active across all projects.\n\n---\n\n## CLI Commands\n\n### Session Management\n\n```bash\n# List recent sessions\naiana list --limit 10\n\n# View a session\naiana show \u003csession-id\u003e\n\n# Search full-text\naiana search \"database migration\"\n\n# Export session\naiana export \u003csession-id\u003e --format markdown\n```\n\n### Memory Operations\n\n```bash\n# Semantic search\naiana memory search \"how did I fix the auth bug\"\n\n# Add a memory manually\naiana memory add \"cortex uses uv for Python deps\" --type pattern\n\n# Recall context for a project\naiana memory recall git-steer\n```\n\n### Preferences\n\n```bash\n# Add permanent preference\naiana prefer \"Uses conventional commits\"\n\n# Add temporary/recent context\naiana prefer \"Working on Aiana docs\" --temporary\n```\n\n### Bootstrap\n\n```bash\n# Force reload development preferences\naiana bootstrap --force\n\n# Reset bootstrap marker (allows re-bootstrap on next install)\naiana bootstrap --reset\n```\n\n### MCP Server\n\n```bash\n# Start MCP server\naiana mcp\n\n# Check system status\naiana status\n```\n\n---\n\n## MCP Server Tools\n\nWhen running as an MCP server, Aiana exposes these tools to Claude:\n\n| Tool | Description |\n|------|-------------|\n| `memory_search` | Semantic search across memories |\n| `memory_add` | Save a memory or note |\n| `memory_recall` | Get context for a project |\n| `memory_feedback` | Rate recalled memories (helpful/not helpful/harmful) |\n| `feedback_summary` | Get summary of recall quality patterns |\n| `session_list` | List recorded sessions |\n| `session_show` | View session details |\n| `preference_add` | Add user preferences |\n| `aiana_status` | System health check |\n\n### Claude Desktop Integration\n\n```json\n{\n  \"mcpServers\": {\n    \"aiana\": {\n      \"command\": \"aiana\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n---\n\n## Docker Configuration\n\n### Full Stack (docker-compose.yml)\n\n```yaml\nservices:\n  aiana:\n    image: ry-ops/aiana:latest\n    depends_on:\n      - redis\n      - qdrant\n    volumes:\n      - ~/.claude:/home/aiana/.claude:ro\n      - aiana-data:/home/aiana/.aiana\n    ports:\n      - \"8765:8765\"  # MCP server\n    environment:\n      - REDIS_URL=redis://redis:6379\n      - QDRANT_URL=http://qdrant:6333\n\n  redis:\n    image: redis:7-alpine\n    command: redis-server --appendonly yes\n\n  qdrant:\n    image: qdrant/qdrant:latest\n    volumes:\n      - qdrant-data:/qdrant/storage\n\nvolumes:\n  aiana-data:\n  qdrant-data:\n```\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `TZ` | Timezone | `UTC` |\n| `REDIS_URL` | Redis connection URL | `redis://localhost:6379` |\n| `QDRANT_URL` | Qdrant server URL | `http://localhost:6333` |\n| `AIANA_MCP_PORT` | MCP server port | `8765` |\n| `AIANA_EMBEDDING_MODEL` | Embedding model | `all-MiniLM-L6-v2` |\n\n---\n\n## Mem0 Integration\n\nAIANA v1.1.0 integrates [Mem0](https://github.com/mem0ai/mem0) for enhanced AI memory management.\n\n### Why Mem0?\n\n- **Automatic memory extraction** - Extracts key information from conversations\n- **Deduplication** - Consolidates related memories automatically\n- **Relevance scoring** - Built-in scoring for better retrieval\n- **46k+ stars** - Active community, well-maintained\n\n### Integration Strategy\n\nWe use the **Wrapper Pattern** with pinned versions:\n\n```toml\n# Pinned to major version - allows patches, blocks breaking changes\n\"mem0ai\u003e=1.0.3,\u003c2.0\"\n```\n\n```\n┌─────────────────────────────────────────────────┐\n│              AIANA Storage Layer                │\n├─────────────────────────────────────────────────┤\n│                                                 │\n│   Mem0Storage  ──────►  QdrantStorage           │\n│   (primary)             (fallback)              │\n│       │                      │                  │\n│       ▼                      ▼                  │\n│   ┌───────┐              ┌───────┐              │\n│   │ Mem0  │──────────────│Qdrant │              │\n│   │  API  │   uses       │  API  │              │\n│   └───────┘              └───────┘              │\n│                                                 │\n└─────────────────────────────────────────────────┘\n```\n\n**Benefits:**\n- **Isolation** - Mem0 API changes stay in `Mem0Storage` wrapper\n- **Fallback** - If Mem0 fails, `QdrantStorage` takes over\n- **Testability** - Can mock wrapper for testing\n- **Swappability** - Replace Mem0 without touching other code\n\nSee [ADR-001](docs/decisions/001-dependency-integration-strategy.md) for full rationale.\n\n---\n\n## Configuration\n\nConfiguration file: `~/.aiana/config.yaml`\n\n```yaml\nstorage:\n  type: sqlite\n  path: ~/.aiana/conversations.db\n\nrecording:\n  include_tool_results: true\n  include_thinking: false\n  redact_secrets: true\n\nretention:\n  days: 90\n  max_sessions: 1000\n\nprivacy:\n  encrypt_at_rest: false\n```\n\n---\n\n## How Context Injection Works\n\nOn every `SessionStart`, Aiana:\n\n1. **Loads your profile** - Static preferences you've saved\n2. **Fetches project context** - Recent work in this project\n3. **Searches semantically** - Finds relevant memories\n4. **Injects context** - Adds `\u003caiana-context\u003e` block\n\n```xml\n\u003caiana-context\u003e\n## User Preferences (Persistent)\n- Prefers TypeScript over JavaScript\n- Uses ESLint flat config (v9+)\n- Commits with conventional format\n\n## Project: git-steer\n### Recent Activity\n- Fixed 9 security vulnerabilities\n- Updated to vitest 4.x\n- Created blog post series\n\n## Recent Context\n- Working on Aiana documentation\n\u003c/aiana-context\u003e\n```\n\nClaude sees this context and adapts to YOUR patterns.\n\n---\n\n## Documentation\n\n- [Architecture](docs/ARCHITECTURE.md) - Technical design and components\n- [Storage Backends](docs/STORAGE.md) - SQLite, Redis, Qdrant configuration\n- [MCP Server](docs/MCP_SERVER.md) - MCP integration and tools\n- [Context Injection](docs/CONTEXT_INJECTION.md) - How memory injection works\n- [Claude Code Internals](docs/CLAUDE_CODE_INTERNALS.md) - File formats, hooks, APIs\n- [TOS Compatibility](docs/TOS_COMPATIBILITY_ANALYSIS.md) - Legal compliance\n\n### Architecture Decisions\n- [ADR-001: Dependency Integration Strategy](docs/decisions/001-dependency-integration-strategy.md) - Wrapper pattern for third-party libs\n\n---\n\n## Privacy \u0026 Security\n\nAiana is designed with privacy as a core principle:\n\n- **Local Only** - All data stored on your machine\n- **No Cloud Sync** - Data never leaves your system\n- **User Control** - You decide what gets recorded\n- **Read-Only Access** - Docker mounts Claude directory as read-only\n- **Non-Root Container** - Runs as unprivileged user\n\n---\n\n## Roadmap\n\n- [x] **Phase 1: Core MVP**\n  - [x] Hook-based session capture\n  - [x] SQLite storage with FTS5\n  - [x] CLI interface\n  - [x] Docker support\n\n- [x] **Phase 2: Memory Layer**\n  - [x] Redis caching\n  - [x] Qdrant vector storage\n  - [x] Semantic search\n  - [x] Context injection\n  - [x] MCP server mode\n\n- [x] **Phase 2.5: Enhanced Memory (v1.1.0)**\n  - [x] Mem0 integration\n  - [x] Automatic memory extraction\n  - [x] Memory deduplication\n  - [x] Conversation-based memory\n\n- [x] **Phase 2.6: Auto-Bootstrap (v1.2.0)**\n  - [x] Bundled development preferences\n  - [x] Automatic preference loading on first install\n  - [x] Cross-project memory (user-level, not project-isolated)\n  - [x] One-and-done installation experience\n\n- [ ] **Phase 3: Intelligence**\n  - [ ] Automatic pattern extraction\n  - [ ] Session summaries\n  - [ ] Cross-session linking\n  - [ ] Workflow suggestions\n\n- [ ] **Phase 4: Polish**\n  - [ ] Secret redaction\n  - [ ] Encryption at rest\n  - [ ] Web UI (optional)\n\n---\n\n## Related Projects\n\n**ry-ops ecosystem:**\n- [git-steer](https://github.com/ry-ops/git-steer) - GitHub autonomy engine via MCP\n- [cortex](https://github.com/ry-ops/cortex) - Multi-agent AI system\n\n**Community tools:**\n- [ccusage](https://github.com/ryoppippi/ccusage) - Cost/token tracking\n- [claude-code-log](https://github.com/daaain/claude-code-log) - JSONL to HTML converter\n\n---\n\n## Contributing\n\nContributions welcome! Please read the documentation and open an issue before submitting PRs.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n---\n\n**Repository:** [github.com/ry-ops/aiana](https://github.com/ry-ops/aiana)\n\n**Blog Post:** [Personal AI Operations Memory](https://ry-ops.dev/posts/2026-02-01-personal-ai-operations-memory)\n\n**Status:** Phase 2.6 Complete - Auto-Bootstrap Ready\n\n**Version:** [v1.2.1](https://github.com/ry-ops/aiana/releases/tag/v1.2.1)\n\n**Updated:** 2026-02-14\n\n---\n\n## Changelog\n\n### v1.2.1 (2026-02-14)\n- Fixed CVE-2026-26007: Bump cryptography to \u003e=46.0.5 (subgroup attack in SECT curves)\n\n### v1.2.0 (2026-02-04)\n- **Auto-Bootstrap**: Automatically load development preferences on first `aiana install`\n- Added `aiana bootstrap` command for manual preference management\n- Bundled `bootstrap/user-preferences.md` with development standards\n- Cross-project memory by default (user-level, not project-isolated)\n- One-and-done installation experience\n\n### v1.1.0 (2026-02-04)\n- Added Mem0 integration for enhanced AI memory management\n- Automatic memory extraction from conversations\n- Memory consolidation and deduplication\n- Mem0 as primary memory backend with Qdrant fallback\n- Updated CLI commands to support Mem0\n- Updated MCP server tools for Mem0\n- Implemented wrapper pattern with pinned dependency (`\u003e=1.0.3,\u003c2.0`)\n- Added ADR-001: Dependency Integration Strategy\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fry-ops%2Faiana","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fry-ops%2Faiana","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fry-ops%2Faiana/lists"}