{"id":31838951,"url":"https://github.com/truemagic-coder/sapien","last_synced_at":"2026-07-06T15:31:23.165Z","repository":{"id":310748902,"uuid":"1041074789","full_name":"truemagic-coder/sapien","owner":"truemagic-coder","description":"Long Term Memory for AI","archived":false,"fork":false,"pushed_at":"2025-08-20T01:54:15.000Z","size":79,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-30T08:27:50.995Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/truemagic-coder.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}},"created_at":"2025-08-20T00:18:17.000Z","updated_at":"2025-08-20T01:54:18.000Z","dependencies_parsed_at":"2025-08-25T05:47:12.151Z","dependency_job_id":null,"html_url":"https://github.com/truemagic-coder/sapien","commit_stats":null,"previous_names":["truemagic-coder/sapien"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/truemagic-coder/sapien","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truemagic-coder%2Fsapien","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truemagic-coder%2Fsapien/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truemagic-coder%2Fsapien/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truemagic-coder%2Fsapien/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/truemagic-coder","download_url":"https://codeload.github.com/truemagic-coder/sapien/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/truemagic-coder%2Fsapien/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35197534,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-10-12T03:59:42.172Z","updated_at":"2026-07-06T15:31:23.103Z","avatar_url":"https://github.com/truemagic-coder.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Sapien – Long Term Memory for AI\n\nSapien is a lightweight temporal knowledge graph library that lets you:\n\n* Persist chat messages (or any event) in **MongoDB**.\n* Compute dense embeddings with **sentence‑transformers**.\n* Store those vectors in **Qdrant** for fast semantic search.\n* Retrieve the most relevant historical context for a given query.\n\nIt’s ideal for building LLM‑powered assistants that need to remember past conversations or knowledge graphs while keeping all data stored in open‑source databases.\n\n\u003e ⚠️  The library is still a work‑in‑progress.  It has minimal tests and expects MongoDB + Qdrant to be running locally (or reachable from your environment).\n\n---\n\n## Features\n\n| Feature | Status |\n|---------|--------|\n| **MongoDB persistence** | ✅ |\n| **Qdrant vector search** | ✅ |\n| **Sentence‑transformers embeddings** | ✅ |\n| **Convenient async API** | ✅ |\n| **Zero‑configuration defaults (except for services)** | ✅ |\n| **Type‑hinted, testable code** | ✅ |\n\n---\n\n## Quick start\n\n```bash\n# 1️⃣ Install the package + dev deps\npoetry install\n\n# 2️⃣ Start MongoDB and Qdrant locally\n#    (use Docker Compose – see docker-compose.yml)\ndocker compose up -d\n\n# 3️⃣ Run a short demo script\npython demo.py\n```\n\n**demo.py**\n\n```python\nimport asyncio\nfrom datetime import datetime\n\nfrom sapien import SapienClient, SapienConfig, CollectionNames\n\n\nasync def main():\n    cfg = SapienConfig(\n        mongo_uri=\"mongodb://localhost:27017\",\n        db_name=\"sapien\",\n        qdrant_url=\"http://localhost:6333\",\n        collections=CollectionNames(),\n    )\n    async with SapienClient(cfg) as db:\n        await db.init_indexes()\n\n        # Add a new message\n        msg_id = await db.add_message(\n            session_id=\"chat_42\",\n            role=\"user\",\n            content=\"I need a laptop for gaming.\",\n            timestamp=datetime.utcnow()\n        )\n\n        # Ask the context for a keyword\n        ctx = await db.get_context(\"chat_42\", \"laptop\")\n        print(f\"Context ({len(ctx)} docs):\")\n        for doc in ctx:\n            print(\"-\", doc[\"content\"])\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n---\n\n## Installation\n\n\u003e **Prerequisites** –  \n\u003e *Python 3.12+*  \n\u003e *MongoDB server* (\u003e=4.0)  \n\u003e *Qdrant server* (\u003e=1.0)\n\n```bash\n# Install via Poetry\npoetry add sapien\n```\n\nIf you want the full stack (including the optional `sentence-transformers` and Qdrant client), just install the package normally – all dependencies are pulled in automatically.\n\n---\n\n## Configuration\n\nAll configuration is done through a single dataclass:\n\n```python\nfrom sapien import SapienConfig, CollectionNames\n\ncfg = SapienConfig(\n    mongo_uri=\"mongodb://localhost:27017\",\n    db_name=\"sapien\",          # database name\n    qdrant_url=\"http://localhost:6333\",\n    collections=CollectionNames(),   # optional custom names\n)\n```\n\n\u003e **Tip** – The default collection names are prefixed with `sapien_` (`sessions`, `messages`, etc.) to keep them isolated in the `sapien` database.\n\n---\n\n## API Reference\n\n| Method | Description |\n|--------|-------------|\n| `SapienClient.__aenter__ / __aexit__` | Async context manager that ensures collection creation. |\n| `add_message(session_id, role, content, timestamp=None)` | Persist a message and fire‑and‑forget its embedding \u0026 Qdrant upsert. Returns the Mongo `_id`. |\n| `get_context(session_id, query, k=10)` | Vector search in Qdrant → return full Mongo docs for the top *k* matches. |\n| `init_indexes()` | Create idempotent indexes (`sessions.session_id`, `messages.timestamp`, etc.). |\n\n---\n\n## Testing\n\nThe project ships with a small async test‑suite that expects MongoDB and Qdrant to be running locally.\n\n```bash\n# Run tests\npoetry run pytest -vv\n```\n\nIf the services are not reachable, the integration tests will be skipped automatically.\n\n---\n\n## Development\n\n1. **Clone \u0026 install**\n\n   ```bash\n   git clone https://github.com/yourname/sapien.git\n   cd sapien\n   poetry install\n   ```\n\n2. **Run linters / formatters**\n\n   ```bash\n   poetry run ruff check .\n   poetry run black src tests\n   ```\n\n3. **Run the demo**\n\n   ```bash\n   python demo.py\n   ```\n\n4. **Add a new feature** – remember to update `pyproject.toml`, write tests, and add documentation.\n\n---\n\n## Contributing\n\nPull requests are welcome!  \nPlease:\n\n1. Fork the repo.\n2. Create a feature branch (`feature/your-feature`).\n3. Write or update tests.\n4. Run `poetry run pytest`.\n5. Submit a PR.\n\nFor major changes, open an issue first to discuss the scope.\n\n---\n\n## License\n\nMIT © 2025 – feel free to use it however you like.\n\n---\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftruemagic-coder%2Fsapien","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftruemagic-coder%2Fsapien","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftruemagic-coder%2Fsapien/lists"}