{"id":48950049,"url":"https://github.com/divagr18/memlayer","last_synced_at":"2026-04-17T19:32:09.928Z","repository":{"id":324526338,"uuid":"1097525599","full_name":"divagr18/memlayer","owner":"divagr18","description":"The plug and play memory layer for LLMs - add persistent, intelligent and human memory to any LLM in minutes.","archived":false,"fork":false,"pushed_at":"2025-11-16T11:21:18.000Z","size":181,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-16T13:04:55.602Z","etag":null,"topics":["agent","ai","ai-infrastructure","context-management","developer-tools","embedded","graph-database","knowledge-graph","llm","llm-memory","memory","openai","persistent-memory","python","rag","retrieval","retrieval-augmented-generation","semantic-search","transformer","vector-database"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/memlayer/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/divagr18.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-11-16T10:57:16.000Z","updated_at":"2025-11-16T11:34:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/divagr18/memlayer","commit_stats":null,"previous_names":["divagr18/memlayer"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/divagr18/memlayer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divagr18%2Fmemlayer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divagr18%2Fmemlayer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divagr18%2Fmemlayer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divagr18%2Fmemlayer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/divagr18","download_url":"https://codeload.github.com/divagr18/memlayer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divagr18%2Fmemlayer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31943310,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-17T17:29:20.459Z","status":"ssl_error","status_checked_at":"2026-04-17T17:28:47.801Z","response_time":62,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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":["agent","ai","ai-infrastructure","context-management","developer-tools","embedded","graph-database","knowledge-graph","llm","llm-memory","memory","openai","persistent-memory","python","rag","retrieval","retrieval-augmented-generation","semantic-search","transformer","vector-database"],"created_at":"2026-04-17T19:32:08.726Z","updated_at":"2026-04-17T19:32:09.921Z","avatar_url":"https://github.com/divagr18.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Memlayer\n\n**The plug-and-play memory layer for smart, contextual agents**\n\nMemlayer adds persistent, intelligent memory to any LLM in just 3 lines of code, enabling agents that recall context across conversations, extract structured knowledge, and surface relevant information when it matters.\n\n**\u003c100ms Fast Search • Noise-Aware Memory Gate • Multi-Tier Retrieval Modes • 100% Local • Zero Config**\n\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![PyPI version](https://img.shields.io/pypi/v/memlayer.svg)](https://pypi.org/project/memlayer/)\n\n[Quick Start](#quick-start) • [Documentation](https://divagr18.github.io/memlayer/) • [Examples](https://github.com/divagr18/memlayer/tree/main/examples) • [Twitter](https://x.com/getmemlayer)\n\n\n\n\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./memlayer.png\" alt=\"Memlayer Overview\" width=\"700\"\u003e\n\u003c/p\u003e\n\n\u003cbr/\u003e\n\n## Contents\n\n- [Features](#features)\n- [Quick Start](#quick-start)\n- [Key Concepts](#key-concepts)\n- [Memory Modes](#memory-modes)\n- [Search Tiers](#search-tiers)\n- [Providers](#providers)\n- [Advanced Features](#advanced-features)\n- [Examples](#examples)\n- [Performance](#performance)\n- [Documentation](#documentation)\n- [Contributing](#contributing)\n\n##  Features\n\n- **Universal LLM Support**: Works with OpenAI, Claude, Gemini, Ollama models\n- **Plug-and-play**: Install with `pip install memlayer` and get started in minutes — minimal setup required.\n- **Intelligent Memory Filtering**: Three operation modes (LOCAL/ONLINE/LIGHTWEIGHT) automatically filter important information\n- **Hybrid Search**: Combines vector similarity + knowledge graph traversal for accurate retrieval\n- **Three Search Tiers**: Fast (\u003c100ms), Balanced (\u003c500ms), Deep (\u003c2s) optimized for different use cases\n- **Knowledge Graph**: Automatically extracts entities, relationships, and facts from conversations\n- **Proactive Reminders**: Schedule tasks and get automatic reminders when they're due\n- **Built-in Observability**: Trace every search operation with detailed performance metrics\n- **Flexible Storage**: ChromaDB (vector) + NetworkX (graph) or graph-only mode\n- **Production Ready**: Serverless-friendly with fast cold starts using online mode\n\n##  Quick Start\n\n### Installation\n\n```bash\npip install memlayer\n```\n\n### Basic Usage\n\n```python\nfrom memlayer import OpenAI\n\n# Initialize with memory capabilities\nclient = OpenAI(\n    model=\"gpt-4.1-mini\",\n    storage_path=\"./memories\",\n    user_id=\"user_123\"\n)\n\n# Store information automatically\nclient.chat([\n    {\"role\": \"user\", \"content\": \"My name is Alice and I work at TechCorp\"}\n])\n\n# Retrieve information automatically (no manual prompting needed!)\nresponse = client.chat([\n    {\"role\": \"user\", \"content\": \"Where do I work?\"}\n])\n# Response: \"You work at TechCorp.\"\n```\n\nThat's it! Memlayer automatically:\n1. ✅ Filters salient information using ML-based classification\n2. ✅ Extracts structured facts, entities, and relationships\n3. ✅ Stores memories in hybrid vector + graph storage\n4. ✅ Retrieves relevant context for each query\n5. ✅ Injects memories seamlessly into LLM context\n\n##  Key Concepts\n\n### Salience Filtering\nNot all conversation content is worth storing. Memlayer uses **salience gates** to intelligently filter:\n- ✅ **Save**: Facts, preferences, user info, decisions, relationships\n- ❌ **Skip**: Greetings, acknowledgments, filler words, meta-conversation\n\n### Hybrid Storage\nMemories are stored in two complementary systems:\n- **Vector Store (ChromaDB)**: Semantic similarity search for facts\n- **Knowledge Graph (NetworkX)**: Entity relationships and structured knowledge\n\n### Automatic Consolidation\nAfter each conversation, background threads:\n1. Extract facts, entities, and relationships using LLM\n2. Store facts in vector database with embeddings\n3. Build knowledge graph with entities and relationships\n4. Index everything for fast retrieval\n\n##  Memory Modes\n\nMemlayer offers three modes that control both **memory filtering (salience)** and **storage**:\n\n### 1. LOCAL Mode (Default)\n```python\nclient = Ollama(operation_mode=\"local\")\n```\n- **Filtering**: Sentence-transformers ML model (high accuracy)\n- **Storage**: ChromaDB (vector) + NetworkX (graph)\n- **Startup**: ~10s (model loading)\n- **Best for**: High-volume production, offline apps\n- **Cost**: Free (no API calls)\n\n### 2. ONLINE Mode (Default)\n```python\nclient = OpenAI(operation_mode=\"online\")\n```\n- **Filtering**: OpenAI embeddings API (high accuracy)\n- **Storage**: ChromaDB (vector) + NetworkX (graph)\n- **Startup**: ~2s (no model loading!)\n- **Best for**: Serverless, cloud functions, fast cold starts\n- **Cost**: ~$0.0001 per operation\n\n### 3. LIGHTWEIGHT Mode\n```python\nclient = OpenAI(operation_mode=\"lightweight\")\n```\n- **Filtering**: Keyword-based (medium accuracy)\n- **Storage**: NetworkX only (no vector storage!)\n- **Startup**: \u003c1s (instant)\n- **Best for**: Prototyping, testing, low-resource environments\n- **Cost**: Free (no embeddings at all)\n\n**Performance Comparison:**\n```\nMode          Startup Time    Accuracy    API Cost    Storage\n──────────────────────────────────────────────────────────────\nLOCAL         ~10s            High        Free        Vector+Graph\nONLINE        ~2s             High        $0.0001/op  Vector+Graph  \nLIGHTWEIGHT   \u003c1s             Medium      Free        Graph-only\n```\n\n##  Search Tiers\n\nMemlayer provides three search tiers optimized for different latency requirements:\n\n### Fast Tier (\u003c100ms)\n```python\n# Automatic - LLM chooses based on query complexity\nresponse = client.chat([{\"role\": \"user\", \"content\": \"What's my name?\"}])\n```\n- 2 vector search results\n- No graph traversal\n- Perfect for: Real-time chat, simple factual recall\n\n### Balanced Tier (\u003c500ms)  DEFAULT\n```python\n# Automatic - handles most queries well\nresponse = client.chat([{\"role\": \"user\", \"content\": \"Tell me about my projects\"}])\n```\n- 5 vector search results\n- No graph traversal\n- Perfect for: General conversation, most use cases\n\n### Deep Tier (\u003c2s)\n```python\n# Explicit request or auto-detected for complex queries\nresponse = client.chat([{\n    \"role\": \"user\",\n    \"content\": \"Use deep search: Tell me everything about Alice and her relationships\"\n}])\n```\n- 10 vector search results\n- Graph traversal enabled (entity extraction + 1-hop relationships)\n- Perfect for: Research, \"tell me everything\", multi-hop reasoning\n\n## 🔌 Providers\n\nMemlayer works with all major LLM providers:\n\n### OpenAI\n```python\nfrom memlayer import OpenAI\n\nclient = OpenAI(\n    model=\"gpt-4.1-mini\",  # or gpt-4.1, gpt-5, etc.\n    storage_path=\"./memories\",\n    user_id=\"user_123\"\n)\n```\n\n### Claude (Anthropic)\n```python\nfrom memlayer import Claude\n\nclient = Claude(\n    model=\"claude-4-sonnet\",\n    storage_path=\"./memories\",\n    user_id=\"user_123\"\n)\n```\n\n### Google Gemini\n```python\nfrom memlayer import Gemini\n\nclient = Gemini(\n    model=\"gemini-2.5-flash\",\n    storage_path=\"./memories\",\n    user_id=\"user_123\"\n)\n```\n\n### Ollama (Local)\n```python\nfrom memlayer import Ollama\n\nclient = Ollama(\n    host=\"http://localhost:11434\",\n    model=\"qwen3:14b\",  # or llama3.2, mistral, etc.\n    storage_path=\"./memories\",\n    user_id=\"user_123\",\n    operation_mode=\"local\"  # Run 100% offline!\n)\n```\n### LMStudio (Local)\n```python\nfrom memlayer import LMStudio\n\nclient = LMStudio(\n    host=\"http://localhost:11434/v1\",\n    model=\"qwen/qwen3-14b\",\n    storage_path=\"./memories\",\n    user_id=\"user_123\",\n)\n```\n\n**All providers share the same API** - switch between them seamlessly!\n\n##  Advanced Features\n\n### Proactive Task Reminders\n\n```python\n# User schedules a task\nclient.chat([{\n    \"role\": \"user\",\n    \"content\": \"Remind me to submit the report next Friday at 9am\"\n}])\n\n# Later, when the task is due, Memlayer automatically injects it\nresponse = client.chat([{\"role\": \"user\", \"content\": \"What should I do today?\"}])\n# Response includes: \"Don't forget to submit the report - it's due today at 9am!\"\n```\n\n### Observability \u0026 Tracing\n\n```python\nresponse = client.chat(messages)\n\n# Inspect search performance\nif client.last_trace:\n    print(f\"Search tier: {client.last_trace.events[0].metadata.get('tier')}\")\n    print(f\"Total time: {client.last_trace.total_duration_ms}ms\")\n    \n    for event in client.last_trace.events:\n        print(f\"  {event.event_type}: {event.duration_ms}ms\")\n```\n\n### Custom Salience Threshold\n\n```python\n# Control memory filtering strictness\nclient = OpenAI(\n    salience_threshold=-0.1  # Permissive (saves more)\n    # salience_threshold=0.0   # Balanced (default)\n    # salience_threshold=0.1   # Strict (saves less)\n)\n```\n\n### Knowledge Graph Extraction\n\n```python\n# Manually extract structured knowledge\nkg = client.analyze_and_extract_knowledge(\n    \"Alice leads Project Phoenix in the London office. The project uses Python and React.\"\n)\n\nprint(kg[\"facts\"])         # [\"Alice leads Project Phoenix\", ...]\nprint(kg[\"entities\"])      # [{\"name\": \"Alice\", \"type\": \"Person\"}, ...]\nprint(kg[\"relationships\"]) # [{\"subject\": \"Alice\", \"predicate\": \"leads\", \"object\": \"Project Phoenix\"}]\n```\n\n##  Examples\n\nExplore the `examples/` directory for comprehensive examples:\n\n### Basics\n```bash\n# Getting started\npython examples/01_basics/getting_started.py\n```\n\n### Search Tiers\n```bash\n# Try all three search tiers\npython examples/02_search_tiers/fast_tier_example.py\npython examples/02_search_tiers/balanced_tier_example.py\npython examples/02_search_tiers/deep_tier_example.py\n\n# Compare them side-by-side\npython examples/02_search_tiers/tier_comparison.py\n```\n\n### Advanced Features\n```bash\n# Proactive task reminders\npython examples/03_features/task_reminders.py\n\n# Knowledge graph visualization\npython examples/03_features/test_knowledge_graph.py\n```\n\n### Benchmarks\n```bash\n# Compare salience modes\npython examples/04_benchmarks/compare_operation_modes.py\n```\n\n### Providers\n```bash\n# Try different LLM providers\npython examples/05_providers/openai_example.py\npython examples/05_providers/claude_example.py\npython examples/05_providers/gemini_example.py\npython examples/05_providers/ollama_example.py\n```\n\nSee [examples/README.md](examples/README.md) for full documentation.\n\n##  Performance\n\n### Salience Mode Comparison\nReal-world startup times from benchmarks:\n\n```\nMode          First Use    Memory Savings    Trade-off\n─────────────────────────────────────────────────────────\nLIGHTWEIGHT   ~5s          No embeddings     No semantic search\nONLINE        ~5s          5s faster         Small API cost\nLOCAL         ~10s         No API cost       11s model loading\n```\n\n### Search Tier Latency\nTypical query latencies:\n\n```\nTier        Latency    Vector Results    Graph    Use Case\n────────────────────────────────────────────────────────────\nFast        50-150ms   2                 No       Real-time chat\nBalanced    200-600ms  5                 No       General use\nDeep        800-2500ms 10                Yes      Research queries\n```\n\n### Memory Consolidation\nBackground processing (non-blocking):\n\n```\nStep                        Time      Async\n──────────────────────────────────────────────\nSalience filtering         ~10ms      Yes\nKnowledge extraction       ~1-2s      Yes (background thread)\nVector storage             ~50ms      Yes\nGraph storage              ~20ms      Yes\nTotal (non-blocking)       ~0ms       User doesn't wait!\n```\n\n##  Documentation\n\n### Getting Started\n- **[Basics Overview](docs/basics/overview.md)** - Architecture, components, and how Memlayer works\n- **[Quickstart Guide](docs/basics/quickstart.md)** - Get up and running in 5 minutes\n- **[Streaming Mode](docs/basics/streaming.md)** - Complete guide to streaming responses\n- **[API Reference](docs/API_REFERENCE.md)** - Complete API documentation with all methods and parameters\n\n### Provider Setup\n- **[Providers Overview](docs/providers/README.md)** - Compare all providers, choose the right one\n- **[Ollama Setup](docs/providers/ollama.md)** - Run completely offline with local models\n- **[OpenAI](docs/providers/openai.md)** - OpenAI configuration\n- **[Claude](docs/providers/claude.md)** - Anthropic Claude setup\n- **[Gemini](docs/providers/gemini.md)** - Google Gemini configuration\n\n### Examples\n- **[Examples Index](examples/README.md)** - Comprehensive examples by category\n- **[Provider Examples](examples/05_providers/README.md)** - Provider comparison and usage\n\n##  Tunable features (quick index)\n\nThe project exposes several runtime/configuration knobs you can tune to match latency, cost, and accuracy trade-offs. Detailed docs for each area live in the `docs/` folder:\n\n- **[docs/tuning/operation_mode.md](docs/tuning/operation_mode.md)** — **Architecture deep dive**: How to choose between `online`, `local`, and `lightweight` modes, performance implications, storage composition, and deployment strategies.\n- **[docs/tuning/intervals.md](docs/tuning/intervals.md)** — Scheduler and curation interval configuration (`scheduler_interval_seconds`, `curation_interval_seconds`) and practical guidance.\n- **[docs/tuning/salience_threshold.md](docs/tuning/salience_threshold.md)** — How to adjust `salience_threshold` and expected behavior.\n- **[docs/services/consolidation.md](docs/services/consolidation.md)** — Consolidation pipeline internals and how to call it programmatically (including `update_from_text`).\n- **[docs/services/curation.md](docs/services/curation.md)** — How memory curation works, archiving rules, and how to run/stop the curation service.\n- **[docs/storage/chroma.md](docs/storage/chroma.md)** — ChromaDB notes: metadata types, connection handling, and Windows file-lock guidance.\n- **[docs/storage/networkx.md](docs/storage/networkx.md)** — Knowledge graph persistence, expected node schemas, and backup/restore tips.\n\nUse the docs when tuning for production. The following `docs/` files were added to this repository and provide detailed, practical guidance.\n\n##  Development\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/divagr18/memlayer.git\ncd memlayer\n\n# Install dependencies\npip install -e .\n\n# Run tests\npython -m pytest tests/\n\n# Run examples\npython examples/01_basics/getting_started.py\n```\n\n### Project Structure\n\n```\nmemlayer/\n├── memlayer/           # Core library\n│   ├── wrappers/          # LLM provider wrappers\n│   ├── storage/           # Storage backends (ChromaDB, NetworkX)\n│   ├── services.py        # Search \u0026 consolidation services\n│   ├── ml_gate.py         # Salience filtering\n│   └── embedding_models.py # Embedding model implementations\n├── examples/              # Organized examples by category\n│   ├── 01_basics/\n│   ├── 02_search_tiers/\n│   ├── 03_features/\n│   ├── 04_benchmarks/\n│   └── 05_providers/\n├── tests/                 # Tests and benchmarks\n├── docs/                  # Documentation\n└── README.md              # This file\n```\n\n##  Contributing\n\nContributions are welcome! Here's how you can help:\n\n1. **Report bugs** - Open an issue with reproduction steps\n2. **Suggest features** - Share your use case and requirements\n3. **Submit PRs** - Fix bugs, add features, improve docs\n4. **Share examples** - Show us what you've built!\n\nPlease keep PRs focused and include tests for new features.\n\n##  Contact \u0026 Support\n\n- **Author/Maintainer**: Divyansh Agrawal\n- **Email**: keshav.r.1925@gmail.com\n- **GitHub**: [divagr18](https://github.com/divagr18)\n- **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/divagr18/memlayer/issues)\n\nFor security vulnerabilities, please email directly with `SECURITY` in the subject line instead of opening a public issue.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- Built with [ChromaDB](https://www.trychroma.com/) for vector storage\n- Uses [NetworkX](https://networkx.org/) for knowledge graph operations\n- Powered by [sentence-transformers](https://www.sbert.net/) for local embeddings\n- Supports [OpenAI](https://openai.com/), [Anthropic](https://www.anthropic.com/), [Google Gemini](https://ai.google.dev/), and [Ollama](https://ollama.ai/)\n\n---\n\n**Made with ❤️ for the AI community**\n\nGive your LLMs memory. Try Memlayer today! \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdivagr18%2Fmemlayer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdivagr18%2Fmemlayer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdivagr18%2Fmemlayer/lists"}