{
  "markdown": "<!-- mcp-name: io.github.potatohoney-p/weasley-deepmind -->\n\n![Weasley DeepMind](assets/weasley-deepmind-hero.png)\n\n# Weasley DeepMind\n\nWeasley DeepMind is a self-hosted memory server for AI agents. It stores small, typed memory fragments, links related evidence, and recalls the right context through MCP without forcing an entire conversation history back into every prompt.\n\nIt is part of the **Weasley Open Source** family and is released under Apache-2.0.\n\n## Why DeepMind\n\n- **Useful recall, not a transcript dump.** Keyword, PostgreSQL GIN, graph-neighbor, and optional pgvector search are merged and ranked within a token budget.\n- **Memory with structure.** Facts, decisions, procedures, preferences, episodes, and errors keep provenance, importance, links, and lifecycle state.\n- **MCP-native.** Use a local stdio process or the Streamable HTTP endpoint at `/mcp`.\n- **Fail-closed HTTP security.** The HTTP server rejects requests when no access key is configured. Authentication can only be disabled explicitly for local development.\n- **Self-hosted data.** PostgreSQL is the system of record. Redis and external embedding or LLM providers are optional.\n- **Operationally ready.** Migrations are serialized with a PostgreSQL advisory lock, secrets are redacted from logs, and updates refuse dirty Git checkouts.\n\n## Requirements\n\n- Node.js 20.19 or newer\n- PostgreSQL 15 or newer with the `pgvector` extension\n- Redis 7 (optional, for cache and low-latency keyword lookup)\n\n## Install from npm\n\n```bash\nnpm install --global weasley-deepmind\n```\n\nCreate a PostgreSQL database with pgvector, then configure the connection:\n\n```bash\nexport DATABASE_URL='postgresql://postgres:password@localhost:5432/weasley_deepmind'\nexport WEASLEY_DEEPMIND_ACCESS_KEY='replace-with-a-long-random-secret'\n\nweasley-deepmind migrate\nweasley-deepmind serve\n```\n\nThe HTTP server listens on `http://127.0.0.1:57332` by default. Its MCP endpoint is `http://127.0.0.1:57332/mcp`.\n\n## Add it to an MCP client\n\nThe npm package includes a newline-delimited stdio transport. A generic MCP client configuration looks like this:\n\n```json\n{\n  \"mcpServers\": {\n    \"weasley-deepmind\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"weasley-deepmind\", \"stdio\"],\n      \"env\": {\n        \"DATABASE_URL\": \"postgresql://postgres:password@localhost:5432/weasley_deepmind\",\n        \"WEASLEY_DEEPMIND_AUTO_MIGRATE\": \"true\"\n      }\n    }\n  }\n}\n```\n\nFor an already-running HTTP deployment, point the client at `/mcp` and send `Authorization: Bearer <WEASLEY_DEEPMIND_ACCESS_KEY>`.\n\n## Run the repository locally\n\n```bash\ngit clone https://github.com/potatohoney-p/weasley-deepmind.git\ncd weasley-deepmind\nnpm ci\ndocker compose -f docker-compose.dev.yml up -d\ncp .env.example.minimal .env\nnpm run migrate\nnpm start\n```\n\nThe development Compose file exposes PostgreSQL at `localhost:35432` and Redis at `localhost:36379`. Update `.env` to match those ports before starting the server.\n\n## Core flow\n\n```mermaid\nflowchart LR\n    Agent[\"AI agent\"] --> MCP[\"stdio or Streamable HTTP\"]\n    MCP --> Tools[\"remember · recall · reflect · context\"]\n    Tools --> Rank[\"keyword + graph + vector ranking\"]\n    Rank --> Postgres[\"PostgreSQL + pgvector\"]\n    Rank -. optional cache .-> Redis[\"Redis\"]\n```\n\nThe main tool set includes `remember`, `batch_remember`, `recall`, `forget`, `amend`, `link`, `reflect`, `context`, `memory_stats`, `memory_consolidate`, `graph_explore`, `fragment_history`, `reconstruct_history`, and `search_traces`. Tool availability can be limited by API-key permissions and operating mode.\n\n## Configuration\n\n| Variable | Purpose | Default |\n| --- | --- | --- |\n| `DATABASE_URL` | PostgreSQL connection URL | derived from `POSTGRES_*` |\n| `WEASLEY_DEEPMIND_ACCESS_KEY` | Required bearer secret for HTTP mode | none; HTTP fails closed |\n| `WEASLEY_DEEPMIND_AUTH_DISABLED` | Explicit loopback-only authentication opt-out; startup rejects non-loopback listeners | `false` |\n| `WEASLEY_DEEPMIND_AUTO_MIGRATE` | Run migrations before stdio startup | `false` (`server.json` suggests `true`) |\n| `WEASLEY_DEEPMIND_HOME` | CLI cache and local state directory | `~/.weasley/deepmind` |\n| `WEASLEY_DEEPMIND_HOST` | HTTP listen address | `127.0.0.1` |\n| `PORT` | HTTP port | `57332` |\n| `REDIS_ENABLED` | Enable Redis-backed features | `false` |\n| `EMBEDDING_PROVIDER` | `openai`, `gemini`, `ollama`, `localai`, `cloudflare`, `transformers` (optional install), or `custom` | `openai` |\n| `EMBEDDING_API_KEY` | Optional embedding provider secret | none |\n\nSee [.env.example](.env.example), [configuration](docs/configuration.en.md), and the [installation guide](docs/INSTALL.en.md) for the complete matrix.\n\nLocal transformer embeddings are intentionally excluded from the default install so the core MCP server does not inherit an optional native-image dependency. Follow the pinned setup in [docs/embedding-local.md](docs/embedding-local.md) before selecting `EMBEDDING_PROVIDER=transformers`.\n\n## CLI\n\n```text\nweasley-deepmind serve       Start the HTTP MCP server\nweasley-deepmind stdio       Start the local stdio MCP server\nweasley-deepmind migrate     Apply pending database migrations\nweasley-deepmind health      Check database, Redis, and embeddings\nweasley-deepmind recall      Search memory from the terminal\nweasley-deepmind remember    Store a memory fragment\nweasley-deepmind update      Preview or apply an update\n```\n\nRun `weasley-deepmind --help` or see the [CLI reference](docs/cli.en.md) for every command.\n\n## Security defaults\n\n- Keep the HTTP listener on loopback unless you have a trusted reverse proxy and an explicit origin allowlist.\n- Use a unique, high-entropy `WEASLEY_DEEPMIND_ACCESS_KEY` and never commit `.env`.\n- Stdio mode trusts the local MCP host process; protect the host account and database credentials accordingly.\n- Report vulnerabilities privately using the instructions in [SECURITY.md](SECURITY.md).\n\n## Development\n\n```bash\nnpm ci\nnpm test\nnpm run lint\nnpm run lint:migrations\nnpm pack --dry-run\n```\n\nArchitecture and operations details live in [docs/architecture.en.md](docs/architecture.en.md) and [docs/operations](docs/operations). Contributions are welcome through [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nCopyright 2026 Weasley Open Source.\n\nLicensed under the [Apache License 2.0](LICENSE). See [NOTICE](NOTICE) for attribution information.\n",
  "bytes": 6369,
  "sha": "53269491c209c8a045d518d17b437ce99e002dcf43a99d5b9c907d0880fa8e4c",
  "repo_slug": "potatohoney-p/weasley-deepmind",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_potatohoney_p_weasley_deepmind_35d7335d/readme"
}