{"id":51492144,"url":"https://github.com/evermind-ai/everalgo","last_synced_at":"2026-07-07T12:02:11.521Z","repository":{"id":363952124,"uuid":"1235123321","full_name":"EverMind-AI/EverAlgo","owner":"EverMind-AI","description":"EverAlgo is the algorithm library behind EverMind's memory system — stateless, storage-free, focused on extraction and ranking only. Orchestration, persistence, and routing live upstream in evermem.","archived":false,"fork":false,"pushed_at":"2026-06-24T03:50:33.000Z","size":2545,"stargazers_count":11,"open_issues_count":0,"forks_count":4,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-24T04:24:41.179Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EverMind-AI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-11T03:09:00.000Z","updated_at":"2026-06-24T03:50:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/EverMind-AI/EverAlgo","commit_stats":null,"previous_names":["evermind-ai/everalgo"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/EverMind-AI/EverAlgo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EverMind-AI%2FEverAlgo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EverMind-AI%2FEverAlgo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EverMind-AI%2FEverAlgo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EverMind-AI%2FEverAlgo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EverMind-AI","download_url":"https://codeload.github.com/EverMind-AI/EverAlgo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EverMind-AI%2FEverAlgo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35226918,"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-07T02:00:07.222Z","response_time":90,"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":"2026-07-07T12:02:08.998Z","updated_at":"2026-07-07T12:02:11.504Z","avatar_url":"https://github.com/EverMind-AI.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EverAlgo\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/)\n[![PyPI - everalgo-core](https://img.shields.io/pypi/v/everalgo-core)](https://pypi.org/project/everalgo-core/)\n\nEverAlgo is the **algorithm library** behind EverMind's memory system — stateless, storage-free, focused on extraction and ranking only. Orchestration, persistence, and routing live upstream in EverOS.\n\n## Why split EverAlgo from EverOS?\n\n- **Algorithm engineers iterate fast.** EverAlgo is the algorithm team's home base — every change to extraction strategies, prompts, fusion math, and ranker weights happens here without going through service-layer ceremony.\n- **Pure functions, easy to reason about.** No DB, no filesystem, no business state. All operators are plain in-memory transforms with explicit input / output types.\n- **One codebase serves both the open-source and the commercial cloud builds.** The same `everalgo.*` packages are consumed by both editions.\n\nThe full architecture lives in [`docs/concepts/architecture.md`](docs/concepts/architecture.md).\n\n## Repository layout\n\nThis repo is a **monorepo** of 8 distributions sharing the `everalgo.*` namespace via [PEP 420](https://peps.python.org/pep-0420/), managed with [uv workspace](https://docs.astral.sh/uv/concepts/projects/workspaces/) (all published to PyPI):\n\n| Distribution | What it provides |\n|---|---|\n| [`everalgo-core`](packages/everalgo-core/) | Types, LLM client + providers, prompt helpers, testing utilities |\n| [`everalgo-boundary`](packages/everalgo-boundary/) | `detect_boundaries` + `DetectionResult` + token helpers |\n| [`everalgo-clustering`](packages/everalgo-clustering/) | `Cluster` value object + `cluster_by_geometry` / `cluster_by_llm` operators |\n| [`everalgo-rank`](packages/everalgo-rank/) | 4 rankers (episodic / profile / case / skill) over fusion / weight / rerank toolkit |\n| [`everalgo-parser`](packages/everalgo-parser/) | Multimodal raw-file → `ParsedContent` (image, audio, PDF, HTML, email, office, URL; video deferred) |\n| [`everalgo-user-memory`](packages/everalgo-user-memory/) | `BoundaryDetector` + `Episode` / `Foresight` / `AtomicFact` / `Profile` extractors |\n| [`everalgo-agent-memory`](packages/everalgo-agent-memory/) | `AgentBoundaryDetector` + `AgentCase` / `AgentSkill` extractors |\n| [`everalgo-knowledge`](packages/everalgo-knowledge/) | `KnowledgeExtractor` pipeline + `aclassify_category` (file-based knowledge extraction) |\n\n## 60-second quickstart\n\nInstall all packages into a shared editable venv, then run the offline examples — no API key required:\n\n```bash\ngit clone git@github.com:EverMind-AI/EverAlgo.git\ncd everalgo\n\nuv sync --all-packages          # editable-install all 8 packages into a shared venv\nuv run pre-commit install       # register the git hook (ruff + standard sanitisers)\nls .git/hooks/pre-commit        # MUST exist — see AGENTS.md §3 \"Common pitfall\"\n\nuv run python examples/01_boundary_chat.py          # Chat → MemCell\nuv run python examples/03_user_memory_episode.py    # MemCell → Episode\nuv run python examples/04_agent_memory_case.py      # Agent trajectory → AgentCase\nuv run python examples/06_full_user_memory_pipeline.py   # Full pipeline\nuv run pytest                                        # workspace-wide test suite\n```\n\n\u003e [!NOTE]\n\u003e If `.git/hooks/pre-commit` does not exist after the `install` step, hooks won't fire at `git commit` time. Verify the file every clone. Details in [`AGENTS.md`](AGENTS.md) §3.\n\n## Code example — full user-memory pipeline\n\n```python\nimport asyncio\nimport json\nimport numpy as np\n\nfrom everalgo.clustering import Cluster, cluster_by_geometry\nfrom everalgo.llm.types import ChatResponse\nfrom everalgo.testing.fake_llm import FakeLLMClient\nfrom everalgo.types import ChatMessage\nfrom everalgo.user_memory import (\n    BoundaryDetector, EpisodeExtractor, ForesightExtractor,\n    AtomicFactExtractor, ProfileExtractor,\n)\n\n_BOUNDARY_JSON = json.dumps({\"reasoning\": \"single topic\", \"boundaries\": [], \"should_wait\": False})\n_EPISODE_JSON  = json.dumps({\"title\": \"Alice asks about async\", \"content\": \"Alice explored async patterns.\"})\n_FORE_JSON     = json.dumps([{\"content\": \"Alice will read the follow-up doc\", \"evidence\": \"assistant promised a doc\", \"start_time\": \"2023-11-14\", \"end_time\": \"2023-11-21\", \"duration_days\": 7}])\n_FACT_JSON     = json.dumps({\"atomic_facts\": {\"time\": \"Nov 14 2023\", \"atomic_fact\": [\"Alice is learning Python async.\"]}})\n_PROFILE_JSON  = json.dumps({\"explicit_info\": [], \"implicit_traits\": [{\"category\": \"Technical\", \"description\": \"Python developer.\"}]})\n\n\nasync def main() -\u003e None:\n    fake = FakeLLMClient(responses=[\n        ChatResponse(content=_BOUNDARY_JSON, model=\"fake\"),\n        ChatResponse(content=_EPISODE_JSON,  model=\"fake\"),\n        ChatResponse(content=_FORE_JSON,     model=\"fake\"),\n        ChatResponse(content=_FACT_JSON,     model=\"fake\"),\n        ChatResponse(content=_PROFILE_JSON,  model=\"fake\"),\n    ])\n\n    messages = [\n        ChatMessage(id=\"m1\", role=\"user\",      content=\"I want to learn Python async retry patterns.\", timestamp=1_700_000_000_000, sender_id=\"u_alice\", sender_name=\"Alice\"),\n        ChatMessage(id=\"m2\", role=\"assistant\",  content=\"Sure — I'll send a follow-up doc next week.\", timestamp=1_700_000_001_000, sender_id=\"assistant\"),\n    ]\n\n    # Step 1 — boundary detection\n    result = await BoundaryDetector(llm=fake).adetect(messages, is_final=True)\n    mc = result.cells[0]\n\n    # Steps 2–4 — extract user-memory products (sender_id is required, not inferred)\n    episode    = await EpisodeExtractor(llm=fake).aextract(mc, sender_id=\"u_alice\")\n    foresights = await ForesightExtractor(llm=fake).aextract(mc, sender_id=\"u_alice\")\n    facts      = await AtomicFactExtractor(llm=fake).aextract(mc, sender_id=\"u_alice\")\n\n    # Step 5 — cluster the cell (caller wraps as size-1 Cluster, no LLM), then extract profile\n    vector = np.random.rand(2560).astype(np.float32)\n    existing: list[Cluster] = []\n    new_cluster = Cluster(centroid=vector, last_ts=mc.timestamp)\n    merged = cluster_by_geometry(new_cluster, existing)\n    if merged is None:\n        existing.append(new_cluster.model_copy(update={\"id\": \"cid_001\"}))\n\n    profile = await ProfileExtractor(llm=fake).aextract([mc], sender_id=\"u_alice\")\n\n    print(f\"episode: {episode.subject!r}\")\n    print(f\"foresights: {len(foresights)}, facts: {len(facts)}\")\n    print(f\"profile summary: {profile.summary!r}\")\n\n\nasyncio.run(main())\n```\n\n## Install — consumers\n\nInstall only the distributions you need; transitive deps are pulled automatically:\n\n```bash\npip install everalgo-user-memory    # pulls core + boundary\npip install everalgo-agent-memory   # pulls core + boundary + clustering\npip install everalgo-rank           # pulls core\npip install everalgo-clustering     # pulls core\n```\n\n## Status \u0026 known limitations\n\nAll eight distributions are published on PyPI. Two operators are **unimplemented placeholders that raise `NotImplementedError`** — they are deliberately kept out of the public `__all__` (import the submodule directly if you want the reserved stub) and must not be relied on yet:\n\n| Placeholder | Reachable at | Status |\n|---|---|---|\n| `WorkspaceMemCellExtractor` | `everalgo.boundary.workspace` | Jira / Email / Confluence slicing — not implemented |\n| video parsing | `everalgo.parser.video` | deferred pending an ADR (Gemini Video vs Whisper + frame sampling) |\n\nEverything else is fully implemented and tested: boundary detection, both clustering operators, all four rankers, the user-memory extractors (Episode / Foresight / AtomicFact / Profile), the agent-memory extractors (Case / Skill), and the knowledge extractor (KnowledgeExtractor + document classification).\n\n## Releasing\n\nEvery distribution is released **independently**: each `packages/everalgo-*/pyproject.toml` carries its own `version = \"...\"` and follows its own SemVer cadence. There is no umbrella version — bumping `everalgo-rank` does not require bumping anything else.\n\nThe repo uses a **two-tier CHANGELOG**:\n- [`CHANGELOG.md`](CHANGELOG.md) at the root — current-version overview table.\n- `packages/everalgo-\u003cdist\u003e/CHANGELOG.md` per distribution — full history; ships inside the wheel.\n\nPer-distribution changelogs are generated by [git-cliff](https://git-cliff.org/) from Conventional Commit messages on `main` (see [`cliff.toml`](cliff.toml) for the parser config; see [`AGENTS.md`](AGENTS.md) §6 for the commit-message contract).\n\n### Cutting a release\n\n\u003e **The full, verified step-by-step procedure is in [`docs/releasing.md`](docs/releasing.md)** — including the canary-first / one-tag-at-a-time lessons learned in the 0.2.0 release. The steps below are a quick reference.\n\nSteps for releasing `everalgo-clustering v0.2.0`:\n\n1. **Bump the version.** Open an MR editing `packages/everalgo-clustering/pyproject.toml`; merge to `main` via squash.\n\n2. **Generate the changelog fragment.**\n   ```bash\n   git checkout main \u0026\u0026 git pull\n   uv run git-cliff \\\n     --tag everalgo-clustering/v0.2.0 \\\n     --include-path 'packages/everalgo-clustering/**' \\\n     --unreleased \\\n     --prepend packages/everalgo-clustering/CHANGELOG.md\n   ```\n\n3. **Review and polish.** git-cliff gives a draft, not a final — edit for clarity and add Breaking-Changes call-outs.\n\n4. **Update the root CHANGELOG** table row for this distribution.\n\n5. **Commit + tag + push.**\n   ```bash\n   git add packages/everalgo-clustering/CHANGELOG.md CHANGELOG.md\n   git commit -m \"📝 docs(clustering): release notes for v0.2.0\"\n   git push origin main\n   git tag everalgo-clustering/v0.2.0\n   git push origin everalgo-clustering/v0.2.0\n   ```\n\n6. **Publish to PyPI.** The `.gitlab-ci.yml` `publish` stage triggers automatically on `\u003cdist\u003e/v\u003csemver\u003e` tag push using [PyPI Trusted Publishers](https://docs.pypi.org/trusted-publishers/) (GitLab OIDC, no long-lived tokens). See the CI file for prerequisites and mechanism details.\n\nTag format: `\u003cdist-name\u003e/v\u003csemver\u003e` — e.g. `everalgo-core/v0.1.0`, `everalgo-rank/v0.2.0`.\n\n### Pre-flight checklist\n\n- [ ] `uv run pytest` is green on `main`.\n- [ ] `uv run ruff check . \u0026\u0026 uv run ruff format --check .` pass.\n- [ ] `uv run mypy . \u0026\u0026 uv run pyright` pass.\n- [ ] The bumped `version` honours SemVer relative to the previous tag.\n- [ ] The `packages/everalgo-\u003cdist\u003e/CHANGELOG.md` section has been reviewed and edited.\n- [ ] The root `CHANGELOG.md` table row has been updated.\n\n## For AI coding assistants\n\nRead [`AGENTS.md`](AGENTS.md) — the single source of truth for assistant context. `CLAUDE.md` and `.cursorrules` are symlinks to it.\n\n## Documentation\n\n- [`docs/index.md`](docs/index.md) — project landing page\n- [`docs/installation.md`](docs/installation.md) — install + prerequisites\n- [`docs/getting-started.md`](docs/getting-started.md) — 5-minute quickstart\n- [`docs/concepts/`](docs/concepts/) — architecture, stateless-design, async/sync bridge\n- [`docs/api/`](docs/api/) — per-package API reference\n- [`docs/version-policy.md`](docs/version-policy.md) — SemVer + supported Python versions\n- [`docs/contributing.md`](docs/contributing.md) — how to contribute\n- [`examples/`](examples/) — runnable quickstart scripts (01 through 07)\n- [`AGENTS.md`](AGENTS.md) — onboarding for AI assistants + contributors\n\n## License\n\n[Apache License 2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevermind-ai%2Feveralgo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevermind-ai%2Feveralgo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevermind-ai%2Feveralgo/lists"}