{"id":49812587,"url":"https://github.com/ddong8/memento","last_synced_at":"2026-06-02T17:00:42.978Z","repository":{"id":357064521,"uuid":"1217190965","full_name":"ddong8/memento","owner":"ddong8","description":"A shared brain for your AI coding tools — collects conversations, plans and memory from Claude Code / Cursor / Codex / Obsidian / Antigravity, self-hosted, cross-device, MCP-ready","archived":false,"fork":false,"pushed_at":"2026-05-20T03:01:37.000Z","size":880,"stargazers_count":16,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-20T07:17:53.451Z","etag":null,"topics":["ai-memory","claude-code","developer-tools","fastapi","knowledge-graph","mcp","memento","nextjs","pgvector","self-hosted"],"latest_commit_sha":null,"homepage":"https://mem.ihasy.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ddong8.png","metadata":{"files":{"readme":"README.en.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2026-04-21T16:28:18.000Z","updated_at":"2026-05-20T03:01:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ddong8/memento","commit_stats":null,"previous_names":["ddong8/memento"],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/ddong8/memento","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddong8%2Fmemento","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddong8%2Fmemento/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddong8%2Fmemento/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddong8%2Fmemento/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ddong8","download_url":"https://codeload.github.com/ddong8/memento/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ddong8%2Fmemento/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33831629,"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-06-02T02:00:07.132Z","response_time":109,"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":["ai-memory","claude-code","developer-tools","fastapi","knowledge-graph","mcp","memento","nextjs","pgvector","self-hosted"],"created_at":"2026-05-13T02:14:04.774Z","updated_at":"2026-06-02T17:00:42.939Z","avatar_url":"https://github.com/ddong8.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Memento\n\n**A shared brain for your AI coding tools**\n\nAuto-collect AI coding conversations and memory across devices and tools, aggregate on your own backend, and view / search / recall through a unified Web UI + MCP.\n\n[![License: AGPL v3](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)\n[![Python ≥3.10](https://img.shields.io/badge/python-≥3.10-blue.svg)](#-tech-stack)\n[![Next.js 16](https://img.shields.io/badge/next.js-16-black.svg)](#-tech-stack)\n[![PyPI - memento-brain](https://img.shields.io/pypi/v/memento-brain?label=memento-brain)](https://pypi.org/project/memento-brain/)\n[![PyPI - memento-brain-collector](https://img.shields.io/pypi/v/memento-brain-collector?label=collector)](https://pypi.org/project/memento-brain-collector/)\n[![PyPI - memento-brain-memory](https://img.shields.io/pypi/v/memento-brain-memory?label=mcp-memory)](https://pypi.org/project/memento-brain-memory/)\n\n[Quick Start](#-quick-start) · [Architecture](#️-architecture) · [Supported Tools](#-supported-ai-tools) · [Self-host](#-quick-start) · [MCP](#-mcp-memory-service)\n\n🌐 **Languages**: [中文](README.md) · [English](README.en.md)\n\n\u003c/div\u003e\n\n---\n\n## ✨ What it does\n\n- 🧠 **Cross-device conversation sync** — Claude Code / Codex / Cursor / Antigravity etc. on Mac / Linux / Windows, all aggregated in one place\n- 🔍 **Hybrid retrieval** — BGE-M3 vectors + jieba-tokenized full-text index; works for both English and Chinese\n- 🕸️ **Knowledge graph** — LLM extracts entities (projects / tools / technologies / people / concepts), relations and observations from conversations; observations older than 7 days are auto-compacted into summaries\n- 🔗 **MCP integration** — 8 tools (find: `memory_search` / `memory_recall` / `memory_context`; drill: `memory_open` / `memory_conversation` / `memory_graph`; write: `memory_store`; overview: `daily_summary`) plus 4 resources; any AI IDE can query, read, and update your memory directly\n- 📅 **AI daily digest** — Celery runs a two-stage job at 23:30 every day: per-document summaries first, then aggregated into a cross-tool digest\n- 🔒 **Sanitize-before-enqueue** — The collector strips 14 classes of secrets locally (OpenAI / Anthropic / GitHub / Slack / Telegram / AWS / Bearer tokens / private keys / URL-embedded credentials …) so even the on-disk SQLite queue is safe\n- 🌐 **Public sharing** — One-click share links for project timelines / daily digests, with GeoIP visitor stats, expiry, revoke any time\n- 🛡️ **Fully self-hosted** — One-shot Docker Compose; Postgres + Redis + MinIO all on your own machine — data never leaves\n- 🔐 **Multi-tenant isolation** — Per-user namespaces with owner / admin / viewer roles + fine-grained per-resource grants + audit log\n- ⚡ **Daemon-grade** — Runs as launchd / systemd / Task Scheduler; offline queue and self-healing retry when network drops\n\n## 🏗️ Architecture\n\n```mermaid\ngraph TB\n    subgraph DEV[\"📱 User devices Mac/Linux/Windows\"]\n        direction LR\n        CC[\"Claude Code\u003cbr/\u003e~/.claude\"]\n        CDX[\"Codex\u003cbr/\u003e~/.codex\"]\n        CUR[\"Cursor\u003cbr/\u003e~/.cursor\"]\n        AG[\"Antigravity\u003cbr/\u003e~/.gemini/antigravity\"]\n        OC[\"OpenClaw\u003cbr/\u003e~/.openclaw\"]\n        HM[\"Hermes\u003cbr/\u003e~/.hermes\"]\n        OBS[\"Obsidian Vault\"]\n        COL[\"memento-brain-collector\u003cbr/\u003ewatchdog listener\u003cbr/\u003eSQLite offline queue\u003cbr/\u003esanitizer on enqueue\"]\n        CC --- COL\n        CDX --- COL\n        CUR --- COL\n        AG --- COL\n        OC --- COL\n        HM --- COL\n        OBS --- COL\n    end\n\n    subgraph SRV[\"☁️ Self-hosted Memento server\"]\n        direction TB\n        NGX[\"nginx\u003cbr/\u003eHTTPS + gzip\"]\n\n        subgraph DK[\"Docker Compose\"]\n            direction LR\n            API[\"FastAPI :8000\"]\n            WEB[\"Next.js Web :3000\"]\n            CW[\"Celery Worker\"]\n            CB[\"Celery Beat\"]\n            PG[(\"PostgreSQL 16\u003cbr/\u003e+ pgvector\")]\n            RD[(\"Redis 7\")]\n            S3[(\"MinIO\u003cbr/\u003eS3 compatible\")]\n        end\n\n        EMB[\"BGE-M3 Embedding\u003cbr/\u003e:8002 host process\"]\n\n        NGX --\u003e API\n        NGX --\u003e WEB\n        API \u003c--\u003e PG\n        API \u003c--\u003e RD\n        API \u003c--\u003e S3\n        API -.calls.-\u003e EMB\n        CW \u003c--\u003e PG\n        CW \u003c--\u003e RD\n        CB --\u003e CW\n    end\n\n    subgraph CLT[\"🤖 AI tools MCP clients\"]\n        direction LR\n        MCC[\"Claude Code\"]\n        MCDX[\"Codex\"]\n        MCUR[\"Cursor\"]\n        MAG[\"Antigravity\"]\n    end\n\n    MCP[\"memento-brain-memory\u003cbr/\u003eMCP Server\"]\n    MCC --\u003e MCP\n    MCDX --\u003e MCP\n    MCUR --\u003e MCP\n    MAG --\u003e MCP\n\n    COL ==\u003e|\"HTTPS + collector token\"| NGX\n    MCP ==\u003e|\"HTTPS + JWT\"| NGX\n\n    subgraph PUB[\"🌍 Public access\"]\n        SHARE[\"Share link /s/\u0026lt;token\u0026gt;\"]\n        GEO[\"GeoIP DB\u003cbr/\u003evisitor stats\"]\n    end\n    NGX --\u003e SHARE\n    SHARE --\u003e GEO\n\n    classDef device fill:#fef3c7,stroke:#d97706,color:#92400e\n    classDef server fill:#dbeafe,stroke:#2563eb,color:#1e40af\n    classDef client fill:#fce7f3,stroke:#db2777,color:#831843\n    classDef public fill:#dcfce7,stroke:#16a34a,color:#14532d\n    class CC,CDX,CUR,AG,OC,HM,OBS,COL device\n    class API,WEB,CW,CB,PG,RD,S3,EMB,NGX server\n    class MCC,MCDX,MCUR,MAG,MCP client\n    class SHARE,GEO public\n```\n\n### Data flow (a single conversation, from creation to searchable)\n\n```mermaid\nsequenceDiagram\n    participant T as AI tool\n    participant W as Local file\n    participant C as Collector\n    participant Q as SQLite queue\n    participant A as API\n    participant P as Postgres\n    participant E as Embedding\n    participant M as MCP\n\n    T-\u003e\u003eW: write .jsonl conversation\n    W-\u003e\u003eC: watchdog file event\n    C-\u003e\u003eC: parse + sanitize\n    C-\u003e\u003eQ: enqueue (offline-safe)\n    Q-\u003e\u003eA: HTTPS POST (retry on failure)\n    A-\u003e\u003eP: write documents / conversation_messages / content_tsv\n    A--\u003e\u003eE: async embedding\n    E-\u003e\u003eP: write document_embeddings (pgvector)\n    A--\u003e\u003eP: LLM extracts entities / relations\n    Note over M: User calls memory_search inside Claude Code\n    M-\u003e\u003eA: GET /api/memory/semantic\n    A-\u003e\u003eE: embed query\n    E-\u003e\u003eP: cosine_distance ranking\n    P--\u003e\u003eM: return relevant chunks\n```\n\n\u003e When embedding fails, `embedding_status` is set to `failed`; Celery beat scans `pending/failed` rows **every 15 minutes** and retries — no vectors are lost to transient hiccups.\n\n## 🧰 Supported AI tools\n\n| Tool | What's collected | Format |\n|------|------------------|--------|\n| **Claude Code** | conversations, memory, plans, history | JSONL / Markdown |\n| **OpenClaw** | conversation sessions, identity, memory, learnings, skills | JSONL / Markdown |\n| **Codex** | conversations, history, skills, state | JSONL / TOML / SQLite |\n| **Antigravity** | full conversations (built-in `.pb` decryption), plans, code snapshots | Protobuf / Markdown |\n| **Obsidian** | all notes | Markdown |\n| **Cursor** | conversations, skills, MCP config | JSONL / Markdown |\n| **Hermes** | full conversations (incl. tool calls), persona, skills, CLI history | JSON / Markdown / SQLite |\n\n## 🚀 Quick start\n\n### One-shot install (recommended)\n\n```bash\n# macOS / Linux\ncurl -fsSL https://mem.ihasy.com/install.sh | sh\n\n# Windows (PowerShell)\niwr https://mem.ihasy.com/install.ps1 -useb | iex\n```\n\nOr open \u003chttps://mem.ihasy.com/install\u003e in a browser to copy a ready-made command. The script clones the repo into `~/memento/` (override with `MEMENTO_INSTALL_DIR`) and runs the bundled `./install.sh`.\n\n### From a cloned repo\n\n```bash\ngit clone https://github.com/ddong8/memento.git \u0026\u0026 cd memento\n./install.sh            # macOS / Linux\n.\\install.ps1           # Windows\n```\n\n`install.sh` does it all:\n\n1. Generate `.env` with random secrets (JWT / collector token / MinIO / Postgres passwords)\n2. `docker compose up -d --build` — boots 7 containers\n3. Liveness probe on API `/health`\n4. Interactive prompt to create the first user (auto-promoted to owner with a `collector_token`)\n5. `pip install memento-brain-collector` + setup + register the system service\n\nOptional commands:\n\n| Command | Description |\n|---|---|\n| `./install.sh embedding` | Install BGE-M3 embedding server (Docker mode, ~1.3 GB; required for semantic search / MCP recall) |\n| `./install.sh embedding --native` | Switch to host-venv install (use this if you have NVIDIA CUDA or Apple MPS GPU) |\n| `./install.sh doctor` | Check status of all services |\n| `./install.sh update` | git pull + rebuild + upgrade |\n| `./install.sh uninstall` | Stop services; keep data and config |\n| `./install.sh uninstall --purge` | Above + drop Docker volumes + `.env` |\n| `./install.sh uninstall --all` | Nuclear: pip packages / `~/.memento` / model cache / Docker images / MCP entries — wiped |\n\n### Service ports\n\n| Port | Service |\n|---|---|\n| **8001** | API (Swagger: `/docs`) |\n| **3001** | Web UI |\n| 8002 | Embedding (host port only in `--native` mode; Docker mode keeps it on the docker network at `embedding:8002` without host publish) |\n| 5433 | PostgreSQL |\n| 6380 | Redis |\n| 9000 / 9001 | MinIO / console |\n\n\u003e Ports are deliberately offset from common defaults to avoid conflicts.\n\n## 💻 Adding more devices\n\nConnect every Mac / Windows / Linux box where you use AI tools. Two ways:\n\n### Option 1: Desktop app (recommended)\n\nNo command line, no Python on the machine — just grab the app. It **bundles the collector + MCP sidecar** (frozen, no Python needed), auto-updates, and lives in the system tray.\n\n**[⬇️ Download the latest release from GitHub](https://github.com/ddong8/memento/releases/latest)**\n\n| Platform | Installer |\n|---|---|\n| **macOS** (Apple Silicon) | `.dmg` — drag into Applications |\n| **Windows** | `.exe` — NSIS installer |\n| **Linux** | `.AppImage` (run directly) or `.deb` (`sudo dpkg -i`) |\n\nFirst launch is intentionally minimal — the **Server** tab has only three things:\n\n1. **Server URL** (paste `https://mem.ihasy.com` or your self-hosted URL)\n2. **Auto-start collector when the app launches** (on by default)\n3. **Launch Memento at system startup** (on by default)\n\nClick **Save** → you land on the **Dashboard**, log in or register inside the embedded web. On success:\n- The web posts the collector token back to the desktop via `postMessage`\n- The desktop saves the token + wires MCP + starts the collector (sweeps any stray instances first, so it's always single-instance)\n- The dashboard auto-SSOs you in — your data shows up immediately\n\nThe user **never sees a token** — no browser tab, no manual paste. The client checks for new releases (minisign-signed) and prompts to install them automatically.\n\n\u003e If macOS says it \"can't verify the developer\", right-click the icon → Open, or run `xattr -dr com.apple.quarantine /Applications/Memento.app`.\n\n### Option 2: Command line (pip)\n\nFor servers / headless / CLI-first setups:\n\n```bash\npip install memento-brain-collector   # collector only\n# or pip install memento-brain         # bundles collector + MCP memory together\nmemento-collector setup                # interactive: server URL + token\n```\n\n\u003e PyPI packages are `memento-brain-collector` / `memento-brain-memory` (the short names were taken). CLIs keep the short aliases `memento-collector` / `memento-memory`.\n\n**How to get a token?** (only the pip / CLI path needs it — the desktop client is fully automatic)\n\n- **Ran `./install.sh`** → printed at the end and stored in `.env.local`\n- **Web self-register** → `/auth/register` (open mode) hands back a token immediately\n- **Other devices of the same account** → call `POST /api/auth/me/rotate-collector-token` while logged into the web\n\n### Daemon control\n\n```bash\nmemento-collector status    # show status\nmemento-collector start     # start service\nmemento-collector stop      # stop service\nmemento-collector run       # run in foreground (debug)\n```\n\nAuto-detects platform: **macOS** launchd / **Linux** systemd user / **Windows** Task Scheduler.\n\n## 🕸️ Knowledge graph\n\nThe system extracts the following from every synced conversation / document via LLM:\n\n- **Entities** (`knowledge_entities`) — projects / tools / technologies / people / concepts; deduplicated across conversations\n- **Relations** (`knowledge_relations`) — `uses` / `creates` / `depends_on` / `discussed` between entities\n- **Observations** (`observations`) — concrete factual statements about an entity, with timestamp and source document\n\n**Auto-compaction**: observations on the same entity older than 7 days get merged by an LLM into a shorter summary — preserves semantics, saves space. The window is tunable via `MEMENTO_COMPACTION_AGE_DAYS`.\n\nRead / write through MCP tools: write with `memory_store`; read with `memory_graph(entity_name)` for an entity's neighbors and observations, `memory_context(project)` for project-level context, or `memory_recall(category, days)` for a time-series view. Visualize at the Web `/memory` page.\n\n## 🧠 MCP memory service\n\nAfter installing `memento-brain`, `memento-collector setup` automatically wires MCP into every AI IDE it finds:\n\n| AI tool | MCP config file | How it's written |\n|---|---|---|\n| Claude Code | `~/.claude.json` | `claude mcp add` CLI |\n| Cursor | `~/.cursor/mcp.json` | JSON `mcpServers.memento-memory` |\n| Windsurf | `~/.codeium/windsurf/mcp_config.json` | same |\n| Antigravity | `~/.gemini/antigravity/mcp_config.json` | same |\n| **Codex** | `~/.codex/config.toml` | TOML `[mcp_servers.memento-memory]` |\n| OpenClaw | `~/.openclaw/openclaw.json` | `openclaw mcp set` CLI |\n\nAfter installation, AI IDEs can call 8 tools, grouped in 4 buckets:\n\n| Tool | Purpose |\n|---|---|\n| **Find** | |\n| `memory_search(q, limit, tool_filter, days)` | Hybrid BGE-M3 semantic + jieba full-text search; `days` bounds the time window, `tool_filter` restricts to one tool |\n| `memory_recall(category, days, project, date)` | List recent files of a category (optionally for a specific date or project) |\n| `memory_context(project_name)` | Pull project context (document list + project metadata) when switching projects |\n| **Drill in** | |\n| `memory_open(doc_id)` | Fetch the full content of a document (use after `memory_search` returns a snippet) |\n| `memory_conversation(doc_id, limit, offset)` | Unfold a conversation document into role/content/timestamp messages, with pagination |\n| `memory_graph(entity_name)` | Knowledge-graph drill-in: entity summary + incoming/outgoing relations + recent observations |\n| **Write** | |\n| `memory_store(content, entity_name, entity_type)` | Save an observation into the knowledge graph |\n| **Overview** | |\n| `daily_summary(date)` | Cross-tool activity digest + AI summary for a given day |\n\nPlus 4 MCP **resources** exposed as URIs (subscribable from any IDE):\n\n| URI | Content |\n|---|---|\n| `memory://projects` | list of all projects |\n| `memory://projects/{name}` | single project detail (conversations / entities / observations) |\n| `memory://identity/{tool}` | \"identity card\" for a tool (user preferences / long-term memory) |\n| `memory://daily/{date}` | activity digest for a given day |\n\n## 👥 Users and permissions\n\n| Role | Description |\n|---|---|\n| `owner` | First registered user. Can change any user's role/status; sees all data |\n| `admin` | Manages devices, reads audit log; approves pending users in `invite_only` mode |\n| `viewer` | Read-only (default). Sees only projects/tools granted to them |\n| `pending` | Edge case — only appears in `invite_only` mode for users who self-register without a valid code |\n\n**Registration mode** (`MEMENTO_REGISTRATION_MODE`, defaults to `open`):\n\n| Mode | Behavior |\n|---|---|\n| `open` | Anyone can self-register and is activated immediately with a collector token — no admin in the loop |\n| `invite_only` | Must present an `invite_code` to register; otherwise rejected. Codes are created by owner/admin at `/admin/invites` |\n| `closed` | The register endpoint refuses everyone (deployments meant for the owner alone) |\n\nKey flows:\n\n- **Register** — `/auth/register`. First user becomes owner + active automatically; later registrations follow `MEMENTO_REGISTRATION_MODE`.\n- **Desktop client** — fill the Server URL on the Server tab → Save → log in or register inside the embedded dashboard iframe. The web posts the collector token back via `postMessage` and the desktop wires up everything; **users never see the token**.\n- **Fine-grained grants** — `/admin/permissions` issues per-project / per-tool read/write grants to viewers.\n- **Audit log** — every sensitive action is recorded in `access_logs` (user_id / action / IP / metadata) for after-the-fact review.\n- **Token rotation** — CLI users can `POST /api/auth/me/rotate-collector-token` (JWT required); the desktop app pulls a fresh token automatically on every login, so manual rotation isn't needed there.\n\n## 🌐 Public sharing\n\nProject timelines and daily digests can be shared publicly with one click:\n\n- Open `/projects/\u003cid\u003e/timeline` or `/daily/\u003cdate\u003e` and click **Share** (top right)\n- Pick an expiry (or never), and a `/s/\u003ctoken\u003e` URL is generated\n- Visitors view without logging in\n- Backend records visitor IP + country / region / city (local GeoIP DB; no outbound calls)\n- Revocable any time\n\n## 🛠️ Tech stack\n\n| Layer | Technology |\n|------|------------|\n| Collector | Python ≥3.10, watchdog, httpx, pydantic-settings |\n| MCP memory | Python ≥3.10, mcp ≥1.26, asyncpg, pgvector |\n| Server | Python ≥3.12, FastAPI ≥0.115, SQLAlchemy 2.0 async, asyncpg, Celery |\n| Database | PostgreSQL 16 (+ pgvector + pg_trgm), Redis 7, MinIO (S3-compatible) |\n| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS 4 |\n| AI summary / graph | Anthropic Claude API + OpenAI-compatible endpoints (Kimi / DashScope...) |\n| Embedding | BGE-M3 host process (macOS MPS / Linux CUDA / CPU fallback) |\n| GeoIP | MaxMind GeoLite2 / db-ip city-lite (offline mmdb) |\n| Deployment | Docker Compose (7 services) |\n\n## ⚙️ Background tasks\n\nScheduled by Celery beat:\n\n| Task | Trigger | Purpose |\n|---|---|---|\n| `daily_digest` | every day at 23:30 | Cross-tool daily activity digest (per-doc summaries → aggregation) |\n| `embedding_retry` | every 15 minutes | Scan `embedding_status=pending/failed` and re-embed |\n| `tsvector_backfill` | on startup | Backfill jieba-tokenized full-text index for legacy data |\n| `memory_compaction` | manual / periodic | Merge accumulated observations older than 7 days into summaries |\n\n## 📁 Directory layout\n\n```\nmemento/\n├── collector/                # Local collector — PyPI: memento-brain-collector\n│   └── collector/\n│       ├── main.py           # daemon entry\n│       ├── cli.py            # setup / install / start / stop / uninstall\n│       ├── watcher.py        # cross-platform watchdog + debounce\n│       ├── queue.py          # SQLite WAL offline queue\n│       ├── sync_client.py    # HTTPS sync (chunked upload / offline retry)\n│       ├── sanitizer.py      # sanitize on enqueue (API keys / private keys / OAuth)\n│       ├── parsers/          # 8 parsers\n│       └── tools/            # 6 tool definitions\n├── mcp_server/               # MCP memory — PyPI: memento-brain-memory\n├── memento_brain/            # Meta — PyPI: memento-brain (one-shot install)\n├── server/                   # Backend FastAPI\n│   └── server/\n│       ├── main.py           # entry + schema migrations + validate_production\n│       ├── config.py         # MEMENTO_-prefixed settings + fail-fast\n│       ├── middleware/       # JWT + collector token (constant-time)\n│       ├── api/              # REST + SSE + MCP mount\n│       ├── db/               # 16 tables\n│       ├── services/         # ingest / embedding / graph / cache / geoip\n│       └── tasks/            # Celery worker + beat\n├── web/                      # Next.js 16 frontend\n│   ├── src/app/              # 18+ pages\n│   └── src/components/       # Aurora design system\n├── embedding/                # BGE-M3 host service\n├── scripts/                  # install.py backend + utility scripts\n├── deploy/bootstrap/         # curl one-shot installer (install.sh / .ps1 / index.html)\n├── docs/                     # project-architecture.md / collector-architecture.md\n└── docker-compose.yml\n```\n\n## ⚙️ Environment variables\n\nAll variables share the `MEMENTO_` prefix.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCollector\u003c/b\u003e\u003c/summary\u003e\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MEMENTO_SERVER_URL` | http://localhost:8001 | Server API URL |\n| `MEMENTO_SERVER_TOKEN` | — | collector token |\n| `MEMENTO_OBSIDIAN_VAULT_PATH` | auto-detected | Obsidian vault path |\n| `MEMENTO_NONINTERACTIVE` | — | set `1` to skip prompts during setup |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eServer (api / celery)\u003c/b\u003e\u003c/summary\u003e\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MEMENTO_DATABASE_URL` | postgresql+asyncpg://postgres:postgres@localhost:5433/memento | Postgres connection |\n| `MEMENTO_REDIS_URL` | redis://localhost:6380/0 | Redis broker + backend |\n| `MEMENTO_COLLECTOR_TOKEN` | collector-dev-token | Fallback collector token (dev only) |\n| `MEMENTO_SECRET_KEY` | change-me-in-production | JWT signing key (must override in prod) |\n| `MEMENTO_S3_ENDPOINT` | http://localhost:9000 | MinIO/S3 endpoint |\n| `MEMENTO_S3_ACCESS_KEY` / `MEMENTO_S3_SECRET_KEY` | minioadmin | MinIO credentials |\n| `MEMENTO_S3_BUCKET` | memento | bucket for large files |\n| `MEMENTO_ANTHROPIC_API_KEY` | — | Claude API (AI summaries) |\n| `MEMENTO_AI_API_KEY` / `_BASE_URL` / `_MODEL` | — / dashscope / kimi-k2.5 | OpenAI-compatible fallback |\n| `MEMENTO_EMBEDDING_SERVER_URL` | http://host.docker.internal:8002 | Host BGE-M3 service |\n| `MEMENTO_GEOIP_DB` | /data/geoip/GeoLite2-City.mmdb | GeoIP database path |\n| `MEMENTO_DEBUG` | `0` | set `1` to allow startup with dev defaults |\n| `MEMENTO_PORT` | 8000 | API listen port |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eEmbedding service\u003c/b\u003e\u003c/summary\u003e\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `MEMENTO_EMBEDDING_PORT` | 8002 | HTTP port |\n| `MEMENTO_EMBEDDING_MODEL_NAME` | BAAI/bge-m3 | sentence-transformers model |\n\n\u003c/details\u003e\n\n## 🌐 Remote access / custom domain\n\n- The frontend's API base URL automatically follows `window.location.hostname` (see `getApiBase()`; never hardcoded)\n- Docker port mappings work over both IPv4 and IPv6\n- To allow another origin, edit `allow_origin_regex` in [server/server/main.py](server/server/main.py); default:\n\n  ```python\n  allow_origin_regex=r\"(https?://localhost:\\d+|https?://mem\\.ihasy\\.com)\"\n  ```\n\n## 🗑️ Uninstall\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eServer (installed via install.sh)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n./install.sh uninstall          # stop containers; keep data / .env / pip packages\n./install.sh uninstall --purge  # above + drop Docker volumes + .env\n./install.sh uninstall --all    # nuclear (add -y to skip confirmation)\n```\n\n`--all` removes:\n- pip packages (memento-brain-* + legacy daily-report-*)\n- `~/.memento` + `~/.daily-report` (legacy path)\n- Collector logs (macOS / Linux / Windows paths)\n- Embedding venv + HuggingFace model cache (~1.3 GB)\n- Docker images + volumes\n- `.env` / `.env.local`\n- The `memento-memory` MCP entry from every AI tool\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCollector-only device\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nmemento-collector uninstall                                  # drop launchd/systemd/Task entry\npip uninstall -y memento-brain-collector memento-brain-memory memento-brain\nrm -rf ~/.memento\n\n# Logs (pick one)\nrm -rf ~/Library/Logs/memento                                # macOS\nrm -rf ~/.local/share/memento/logs                           # Linux\n# Windows: Remove-Item -Recurse $env:LOCALAPPDATA\\memento\n\n# Manually remove the memento-memory block from each AI tool's MCP config\n```\n\n\u003c/details\u003e\n\n## 📄 License\n\nThis project is licensed under [AGPL-3.0](LICENSE).\n\nIn short: personal use, self-hosting, internal corporate use, and research are all free. But if you take this code (or any modifications) and offer it as a network service (SaaS / public hosting), AGPL §13 requires you to release your full modified source code under AGPL as well.\n\nFor commercial licensing (waiver of AGPL terms, closed-source use, SaaS deployment, etc.), please contact the author.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddong8%2Fmemento","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fddong8%2Fmemento","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fddong8%2Fmemento/lists"}