{"id":48541889,"url":"https://github.com/datastudy-nl/kraken-agent","last_synced_at":"2026-04-08T05:01:24.424Z","repository":{"id":347847151,"uuid":"1193792951","full_name":"datastudy-nl/kraken-agent","owner":"datastudy-nl","description":"A persistent AI agent that remembers you through a knowledge graph, learns workflows as reusable skills, and grows a deepening model of who you are across sessions","archived":false,"fork":false,"pushed_at":"2026-03-29T18:13:52.000Z","size":954,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-29T20:07:55.579Z","etag":null,"topics":["agent","agi","datastudy","graphrag","kraken","llm","memory","neo4j"],"latest_commit_sha":null,"homepage":"https://datastudy-nl.github.io/kraken-agent/","language":"TypeScript","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/datastudy-nl.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":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-03-27T15:30:51.000Z","updated_at":"2026-03-29T18:13:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/datastudy-nl/kraken-agent","commit_stats":null,"previous_names":["datastudy-nl/kraken-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/datastudy-nl/kraken-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastudy-nl%2Fkraken-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastudy-nl%2Fkraken-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastudy-nl%2Fkraken-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastudy-nl%2Fkraken-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datastudy-nl","download_url":"https://codeload.github.com/datastudy-nl/kraken-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datastudy-nl%2Fkraken-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31540826,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"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":["agent","agi","datastudy","graphrag","kraken","llm","memory","neo4j"],"created_at":"2026-04-08T05:01:09.527Z","updated_at":"2026-04-08T05:01:24.395Z","avatar_url":"https://github.com/datastudy-nl.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eKraken Agent 🐙\u003c/h1\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eDeploy once. Your AI assistant for everything.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-green?style=for-the-badge\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/kraken-agent/\"\u003e\u003cimg src=\"https://img.shields.io/badge/SDK-Python-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white\" alt=\"Python SDK\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Server-Node.js_22-339933?style=for-the-badge\u0026logo=node.js\u0026logoColor=white\" alt=\"Node.js\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n**Kraken** is an open-source AI personal assistant you deploy once and use for everything. It runs on your own hardware, remembers you through a knowledge graph, and gets smarter the more you use it. One instance handles coding, research, scheduling, browsing, automation — anything you throw at it — across every platform you connect.\n\nDeploy with a single `docker-compose up`. Wire it into Discord, Telegram, WhatsApp, a CLI, or any HTTP client. Every conversation from every channel feeds the same memory, skills, and user model. Over time, Kraken becomes the single AI that actually knows you — your projects, preferences, workflows, and goals.\n\n📚 **Full documentation:** [kraken-agent.com](https://kraken-agent.com)\n\n\u003ctable\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cb\u003eGraphRAG Memory\u003c/b\u003e\u003c/td\u003e\u003ctd\u003eNeo4j knowledge graph with entities, relationships, and hierarchical communities. Five query modes — \u003ccode\u003eauto\u003c/code\u003e, \u003ccode\u003elocal\u003c/code\u003e, \u003ccode\u003eglobal\u003c/code\u003e, \u003ccode\u003edrift\u003c/code\u003e, \u003ccode\u003ebasic\u003c/code\u003e — plus episodic message search with pgvector embeddings.\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cb\u003eIdentity System\u003c/b\u003e\u003c/td\u003e\u003ctd\u003eUser-editable \u003ccode\u003eSOUL.md\u003c/code\u003e personality file injected into every prompt. Auto-maintained user model that tracks preferences, expertise, and goals. Cross-platform identity linking maps the same person across Discord, Telegram, and more.\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cb\u003eSelf-Improving\u003c/b\u003e\u003c/td\u003e\u003ctd\u003eSkills auto-created after complex tasks (5+ tool calls or error recovery). Reflection loop evaluates conversations and persists learned procedures. Skills self-improve during use and load via relevance search.\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cb\u003eOne Brain, Every Channel\u003c/b\u003e\u003c/td\u003e\u003ctd\u003eConnect Discord, Telegram, WhatsApp, a CLI, or any HTTP client to the same instance. Session routing with stable keys keeps each conversation thread separate, but identity links let the agent recognize you everywhere. One deployment, one unified memory.\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cb\u003eSandboxed Execution\u003c/b\u003e\u003c/td\u003e\u003ctd\u003eDocker-isolated code execution with networking, port forwarding, and background server support. Playwright-based browser automation via headless Chromium with SSRF protection. Your assistant can write code, run it, and serve it.\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cb\u003eScheduled Automations\u003c/b\u003e\u003c/td\u003e\u003ctd\u003eTell your assistant \"check this RSS feed every morning\" and it does. Cron-based scheduling with natural-language definitions. Tasks run as full sessions with memory and tool access, and deliver results to any connected platform.\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cb\u003eOpenAI-Compatible\u003c/b\u003e\u003c/td\u003e\u003ctd\u003eDrop-in \u003ccode\u003e/v1/chat/completions\u003c/code\u003e endpoint works with any OpenAI client library. Kraken extensions (\u003ccode\u003esession_key\u003c/code\u003e, memory queries) ride alongside the standard API.\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e\u003cb\u003ePython SDK\u003c/b\u003e\u003c/td\u003e\u003ctd\u003eType-safe client for chat, memory, skills, sessions, and identity. Streaming support, session routing, and graph visualization out of the box.\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## Quick Start\n\n```bash\n# 1. Clone\ngit clone https://github.com/kraken-agent/kraken-agent.git\ncd kraken-agent\n\n# 2. Configure\ncp .env.example .env\n# Edit .env — set at minimum:\n#   OPENAI_API_KEY=sk-...\n#   KRAKEN_API_KEY=sk-kraken-...    (any secret you choose)\n#   POSTGRES_PASSWORD=...\n#   NEO4J_PASSWORD=...\n\n# 3. Start the stack\ndocker-compose up -d\n\n# 4. Initialize the database\ndocker-compose exec kraken-api npm run db:push\n\n# 5. Ready\ncurl http://localhost:8080/health\n```\n\nThe API is now live at `http://localhost:8080`.\n\n---\n\n## Python SDK\n\n```bash\npip install kraken-agent\n```\n\n```python\nfrom kraken import KrakenClient\n\nclient = KrakenClient(\n    api_url=\"http://localhost:8080\",\n    api_key=\"sk-kraken-...\",\n    model=\"gpt-5.4\",\n)\n\n# Simple chat\nresponse = client.chat(\"Hello, what can you do?\")\nprint(response.content)\n\n# Stable session routing — the agent remembers across calls\nclient.chat(\"My name is Alice\", session_key=\"discord-12345\", session_name=\"Discord DM\")\nr = client.chat(\"What's my name?\", session_key=\"discord-12345\")\nprint(r.content)  # \"Alice\"\n\n# Streaming\nfor chunk in client.chat(\"Explain GraphRAG\", stream=True):\n    print(chunk, end=\"\")\n```\n\n### Memory (GraphRAG)\n\n```python\n# Query the knowledge graph\nresults = client.memory.query(\"What do you know about my projects?\")\nfor entity in results.entities:\n    print(f\"{entity.type}: {entity.name}\")\n\n# Multi-mode search\nresults = client.memory.query(\n    \"What patterns do you see in my work?\",\n    mode=\"global\",  # \"auto\" | \"local\" | \"global\" | \"drift\" | \"basic\"\n)\n\n# Add entities manually\nclient.memory.add_entity(\"Kraken\", \"project\", properties={\"status\": \"active\"})\nclient.memory.add_relationship(\"user\", \"kraken-id\", \"works_on\")\n\n# Visualize the graph\ngraph = client.memory.graph(center=\"kraken-id\", depth=3)\nprint(f\"{len(graph.nodes)} nodes, {len(graph.edges)} edges\")\n```\n\n### Identity\n\n```python\n# Read the agent's personality\nsoul = client.identity.get_soul()\nprint(soul.content)\n\n# Customize personality\nclient.identity.set_soul(\"You are Kraken, a concise and technical assistant...\")\n\n# Read auto-maintained user model\nuser = client.identity.get_user_model()\nprint(user.content)\n```\n\n### Skills \u0026 Sessions\n\n```python\n# Create a skill\nclient.skills.create(\n    \"git-workflow\",\n    content=\"When committing: use conventional commits...\",\n    tags=[\"git\", \"workflow\"],\n)\n\n# List sessions\nfor s in client.sessions.list():\n    print(f\"{s.session_key or s.id} — {s.message_count} messages\")\n```\n\n---\n\n## How It Works\n\n```\nYour App (Python SDK / any HTTP client)\n               │\n               ▼\n┌─────────────────────────────────────┐\n│        Kraken API  (Hono)           │\n│    REST + WebSocket + streaming     │\n│    OpenAI-compatible /v1/chat/*     │\n└──────────────┬──────────────────────┘\n               │\n    ┌──────────┼──────────────────────────────┐\n    │          │                               │\n    ▼          ▼                               ▼\n┌────────┐ ┌─────────────────────┐  ┌──────────────────┐\n│ Worker │ │   PostgreSQL 17     │  │    Neo4j 5       │\n│(BullMQ)│ │   + pgvector        │  │ (knowledge graph)│\n│        │ │                     │  │                  │\n│ • Memory extraction            │  │ • Entities       │\n│ • Community detection          │  │ • Relationships  │\n│ • User model updates           │  │ • Communities    │\n│ • Skill reflection             │  │                  │\n│ • Dream cycle                  │  │                  │\n│ • Schedule execution           │  │                  │\n└────────┘ └─────────────────────┘  └──────────────────┘\n               │\n    ┌──────────┼──────────┐\n    ▼          ▼          ▼\n┌────────┐ ┌────────┐ ┌──────────┐\n│ Redis 7│ │Chromium│ │ Sandbox  │\n│(queues)│ │(browser│ │ (Docker) │\n│        │ │ CDP)   │ │          │\n└────────┘ └────────┘ └──────────┘\n```\n\n### Key Services\n\n| Service | Role |\n|---------|------|\n| **kraken-api** | Hono HTTP server — chat, memory, identity, sessions, skills, tools, schedules |\n| **worker** | BullMQ background jobs — entity extraction, community detection, user model compression, skill reflection, dream cycle, schedule execution |\n| **PostgreSQL + pgvector** | Sessions, messages (with vector embeddings), skills, tools, identity, schedules |\n| **Neo4j** | Knowledge graph — entities, directional relationships, hierarchical communities with summaries |\n| **Redis** | Job queues, session cache, pub/sub for streaming |\n| **Chromium** | Headless browser automation via Playwright CDP |\n| **Sandbox** | Docker containers for isolated code execution with resource limits |\n\n---\n\n## Memory System\n\nKraken's memory is organized in tiers, inspired by human cognition:\n\n| Tier | Storage | Purpose |\n|------|---------|---------|\n| **Working Memory** | In-context | Current conversation + retrieved context (max 80% of token window) |\n| **Entity Memory** | Neo4j | Knowledge graph — people, projects, tools, concepts, and their relationships |\n| **Community Memory** | Neo4j | Hierarchical clusters with LLM-generated summaries for holistic reasoning |\n| **Episodic Memory** | PostgreSQL | Message archive with full-text search + vector similarity |\n| **User Model** | PostgreSQL | Structured understanding of user preferences, expertise, goals, and patterns |\n| **Skill Memory** | PostgreSQL | Learned procedures — top 3 loaded per query via relevance search |\n\n### Query Modes\n\n| Mode | Best For | How It Works |\n|------|----------|--------------|\n| `auto` | General questions | Analyzes intent, routes to best strategy |\n| `local` | Specific entity questions | Fan out from entity to neighbors, gather context |\n| `global` | Overview / holistic questions | Map query over all community summaries, reduce |\n| `drift` | Entity + broader context | Local search enriched with community context |\n| `basic` | Simple factual recall | Vector similarity search over messages |\n\n---\n\n## API Reference\n\nAll endpoints require `Authorization: Bearer \u003cKRAKEN_API_KEY\u003e` (when set).\n\n### Chat\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/v1/chat` | Send a message (Kraken native format) |\n| `POST` | `/v1/chat/completions` | OpenAI-compatible chat completions |\n\n### Memory\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/v1/memory/query` | Query the knowledge graph (all modes) |\n| `GET` | `/v1/memory/entities` | List entities (filter by type, search) |\n| `POST` | `/v1/memory/entities` | Create an entity |\n| `DELETE` | `/v1/memory/entities/:id` | Delete an entity |\n| `POST` | `/v1/memory/relationships` | Create a relationship |\n| `GET` | `/v1/memory/communities` | List communities by level |\n| `GET` | `/v1/memory/graph` | Get graph neighborhood (center + depth) |\n\n### Identity\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/v1/identity/soul` | Read SOUL.md personality |\n| `PUT` | `/v1/identity/soul` | Update SOUL.md (max 6000 chars) |\n| `GET` | `/v1/identity/user-model` | Read auto-maintained user model |\n| `GET` | `/v1/identity/agents-md` | Read AGENTS.md project context |\n| `PUT` | `/v1/identity/agents-md` | Update AGENTS.md (max 4000 chars) |\n| `POST` | `/v1/identity/links` | Link a user across platforms |\n| `GET` | `/v1/identity/links` | List identity links |\n\n### Sessions, Skills, Tools, Schedules\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/v1/sessions` | List sessions |\n| `GET` | `/v1/sessions/:id` | Get session with message history |\n| `POST` | `/v1/skills` | Create a skill |\n| `GET` | `/v1/skills` | List skills (filter by tag) |\n| `PUT` | `/v1/skills/:id` | Update a skill |\n| `GET` | `/v1/tools` | List registered tools |\n| `POST` | `/v1/schedules` | Create a cron schedule |\n| `GET` | `/v1/schedules` | List schedules |\n| `GET` | `/health` | Health check (no auth) |\n\n---\n\n## Configuration\n\n### Required\n\n| Variable | Description |\n|----------|-------------|\n| `KRAKEN_API_KEY` | Bearer token for API authentication |\n| `DATABASE_URL` | PostgreSQL connection string |\n| `REDIS_URL` | Redis connection string |\n| `NEO4J_URL` | Neo4j Bolt URL |\n| `NEO4J_USER` / `NEO4J_PASSWORD` | Neo4j credentials |\n| `OPENAI_API_KEY` | OpenAI API key (or `ANTHROPIC_API_KEY`) |\n\n### Optional\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `KRAKEN_DEFAULT_MODEL` | `gpt-5.4` | Default LLM for chat |\n| `KRAKEN_EXTRACTION_MODEL` | `gpt-5.4` | Model for entity extraction (can be cheaper) |\n| `KRAKEN_MAX_CONTEXT_TOKENS` | `128000` | Model context window limit |\n| `KRAKEN_MAX_SOUL_CHARS` | `6000` | Max SOUL.md length |\n| `KRAKEN_MAX_USER_MODEL_CHARS` | `2000` | Max user model length |\n| `KRAKEN_MAX_SKILLS_PER_QUERY` | `3` | Skills loaded per query |\n| `KRAKEN_MAX_HISTORY_MESSAGES` | `50` | Recent messages included in context |\n| `KRAKEN_SESSION_MAX_AGE_HOURS` | `24` | Auto-archive sessions after this age |\n| `KRAKEN_SESSION_IDLE_MINUTES` | `120` | Auto-archive after idle time |\n| `KRAKEN_COMPACTION_THRESHOLD_TOKENS` | `80000` | Trigger context compaction |\n| `KRAKEN_COMPACTION_KEEP_RECENT` | `10` | Messages to keep after compaction |\n| `KRAKEN_PRE_FLUSH_ENABLED` | `true` | Silent memory persistence before compaction |\n| `KRAKEN_SKILL_AUTO_CREATE` | `true` | Auto-create skills after complex tasks |\n| `KRAKEN_SKILL_MIN_TOOL_CALLS` | `5` | Tool call threshold for skill creation |\n| `KRAKEN_BROWSER_CDP_URL` | — | Chromium CDP WebSocket URL |\n| `KRAKEN_BROWSER_TIMEOUT_MS` | `30000` | Browser action timeout |\n| `KRAKEN_SANDBOX_IMAGE` | `kraken-sandbox:latest` | Docker image for sandboxed execution |\n| `KRAKEN_SANDBOX_TIMEOUT_MS` | `30000` | Sandbox execution timeout |\n| `KRAKEN_DREAM_CRON` | `*/15 * * * *` | Dream cycle frequency |\n\n---\n\n## Project Structure\n\n```\nkraken-agent/\n├── server/                     # Core API server (TypeScript)\n│   ├── src/\n│   │   ├── index.ts            # Hono HTTP server entrypoint\n│   │   ├── worker.ts           # BullMQ background worker\n│   │   ├── config.ts           # Environment configuration\n│   │   ├── api/                # Route handlers\n│   │   │   ├── chat.ts         # /v1/chat, /v1/chat/completions\n│   │   │   ├── memory.ts       # /v1/memory/*\n│   │   │   ├── identity.ts     # /v1/identity/*\n│   │   │   ├── sessions.ts     # /v1/sessions/*\n│   │   │   ├── skills.ts       # /v1/skills/*\n│   │   │   ├── tools.ts        # /v1/tools/*\n│   │   │   ├── schedules.ts    # /v1/schedules/*\n│   │   │   └── health.ts       # /health\n│   │   ├── db/                 # Drizzle ORM schema + migrations\n│   │   └── services/           # Business logic\n│   │       ├── llm.ts          # LLM abstraction (Vercel AI SDK)\n│   │       ├── memory.ts       # Session \u0026 message management\n│   │       ├── graph.ts        # Neo4j operations\n│   │       ├── context.ts      # System prompt assembly\n│   │       ├── compaction.ts   # Context compaction + pre-flush\n│   │       ├── identity.ts     # SOUL.md, user model, identity links\n│   │       ├── skills.ts       # Skill CRUD + relevance search\n│   │       ├── tools.ts        # Tool registry\n│   │       ├── reflection.ts   # Self-improvement loop\n│   │       ├── browser.ts      # Playwright CDP automation\n│   │       ├── sandbox.ts      # Docker container management\n│   │       ├── vector.ts       # Embeddings + hybrid search\n│   │       ├── queue.ts        # BullMQ job dispatch\n│   │       └── security.ts     # SSRF protection, input validation\n│   ├── Dockerfile\n│   └── package.json\n├── sdk/\n│   └── python/                 # Python SDK\n│       ├── kraken/\n│       │   ├── client.py       # KrakenClient\n│       │   ├── models.py       # Pydantic models\n│       │   ├── memory.py       # Memory API\n│       │   ├── sessions.py     # Sessions API\n│       │   ├── skills.py       # Skills API\n│       │   ├── identity.py     # Identity API\n│       │   └── tools.py        # Tools API\n│       └── pyproject.toml\n├── docs/\n│   ├── research/               # Architecture research docs\n│   └── implementations/\n│       └── discord/            # Example Discord bot\n│           └── bot.py\n└── docker-compose.yml          # Full stack: API, worker, Postgres, Redis, Neo4j, Chromium\n```\n\n---\n\n## Contributing\n\n```bash\n# Clone and install\ngit clone https://github.com/kraken-agent/kraken-agent.git\ncd kraken-agent/server\nnpm install\n\n# Development (auto-reload)\nnpm run dev\n\n# Build\nnpm run build\n\n# Lint\nnpm run lint\n\n# Test\nnpm test\n\n# Database migrations\nnpm run db:generate\nnpm run db:push\n```\n\n### Python SDK\n\n```bash\ncd sdk/python\npip install -e .\n```\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatastudy-nl%2Fkraken-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatastudy-nl%2Fkraken-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatastudy-nl%2Fkraken-agent/lists"}