Tech Recon

Skillful Alhazen

A TypeDB-powered agentic knowledge notebook — run interactively with Claude Code or deployed persistently via OpenClaw

Prototype software — APIs, schemas, and skill interfaces are subject to change without notice.

"The duty of the man who investigates the writings of scientists, if learning the truth is his goal, is to make himself an enemy of all that he reads, and, applying his mind to the core and margins of its content, attack it from every side."

— Ibn al-Haytham (Alhazen), 965–1039 AD

---

What is it?

Skillful Alhazen is an agentic curation system with knowledge graph memory. The agent reads scientific papers, disease databases, job postings, news articles, and more — building structured understanding in a TypeDB knowledge graph that persists across sessions and grows over time.

Three layers work together:

• Agent — Claude Code (interactive) or OpenClaw (persistent service). You talk; the agent curates.
• TypeDB — ontological memory. The schema defines the concepts the agent reasons about; the data is what it has learned so far.
• Skills — domain modules combining a TypeDB schema namespace, Python CLI scripts, and agent instructions. Each skill extends what the agent can do and remember in a specific domain.

Skills are not just prompts. Each skill contributes a typed schema namespace to the knowledge graph, a set of CLI commands the agent calls to read and write structured data, and (optionally) a Next.js dashboard for browsing what has been learned.

📖 Full documentation: github.com/GullyBurns/skillful-alhazen/wiki

---

Quick Start

Prerequisites: Claude Code, Docker, uv

git clone https://github.com/GullyBurns/skillful-alhazen
cd skillful-alhazen
make build   # install deps + resolve skills + start TypeDB
claude       # open Claude Code and start talking

Then just talk to Claude:

You: Search PubMed for papers about CRISPR delivery mechanisms and build a corpus
You: What are the pathophysiological mechanisms underlying Marfan syndrome?
You: Ingest this job posting: https://example.com/senior-ml-engineer
You: Remember that lipid nanoparticles are most effective for hepatic delivery
You: What skill gaps do I have across my top three job prospects?

---

Skills

Core Skills

Built into this repository (skills/ directory). Always available.

Skill	What it does
typedb-notebook	Core knowledge operations — remember facts, recall notes, create collections, tag entities, track schema gaps
web-search	Web search via SearXNG (self-hosted metasearch, no API key needed)
curation-skill-builder	Design and build new TypeDB-backed curation skills; 6-phase system design framework with TypeDB tracking
tech-recon	Systematic investigation of software systems against user-defined success criteria

External Skills

Resolved from sciknow-io/alhazen-skill-examples and custom repositories. Cloned into local_skills/ on make build-skills.

Skill	Domain	What it does	Dashboard
scientific-literature	Biomedical research	Multi-source literature search (Europe PMC, PubMed, OpenAlex, bioRxiv/medRxiv) + semantic search via Voyage AI + Qdrant	—
alg-precision-therapeutics	Rare disease	Investigate disease mechanism of harm and therapeutic landscape from a MONDO diagnosis	✓
literature-trends	Research analysis	Trace how explanatory hypotheses evolve over time in a tagged literature corpus	—
they-said-whaaa	Journalism	Track consistency of public figures — ingest transcripts and articles, extract claims, detect contradictions	✓
jobhunt	Career	Track job applications — ingest postings, fit analysis, skill gap identification	✓
dismech	Disease mechanisms	Browse the DisMech knowledge graph (750+ curated disease mechanism entries)	—

---

Three Ways to Run

Mode	Setup	Best for
(A) Claude Code	make build && claude	Exploration, skill development, one-off research
(B) OpenClaw on Mac Mini	./deploy/deploy.sh --target-type macmini	Persistent local service with Telegram triage
(C) OpenClaw on VPS	./deploy/deploy.sh --target-type vps	Always-on, hardened production deployment

See the Deployment guide for the A → B → C progression.

---

Architecture

identifiable-entity (abstract root)
├── domain-thing              # Real-world objects: papers, diseases, genes, companies, jobs
├── collection                # Typed sets: corpora, search campaigns, investigations
└── information-content-entity (abstract)
    ├── artifact              # Raw captured content (PDFs, HTML, API responses)
    ├── fragment              # Extracted pieces (phenotype associations, requirements)
    └── note                  # Agent analysis (fit scores, mechanism notes, syntheses)

Each skill extends this hierarchy with domain-specific types. A gene or disease is a domain-thing. A paper ingested from PubMed is an artifact. The agent's synthesis of a paper's key claims is a note. Collections group domain objects into research corpora.

Schema gaps — when the agent tries to represent something that has no place in the current schema — are the primary signal for knowledge graph evolution. The skilllog system detects gaps automatically (via a PostToolUse hook), files them as GitHub issues, and provides a local fix workflow. See Gap Architecture.

---

Adding Skills

Skills are self-contained directories. The skills registry (skills-registry.yaml) is the single source of truth.

cp -r skills/_template skills/my-skill
# implement SKILL.md, USAGE.md, schema.tql, my-skill.py
# add a path: entry to skills-registry.yaml
make build-skills && make build-db

See the Skill Architecture guide.

---

History

Forked from CZI's alhazen, reimagined around Claude Code, TypeDB 3.x, and a skill-based architecture. Named after Ibn al-Haytham (965–1039 AD), who pioneered the scientific method five centuries before the Renaissance. See History.

Caveats

• Data licensing: Users are responsible for complying with data licensing requirements and third-party terms of service for all external sources queried by skills.
• LLM accuracy: All LLM-generated content should be reviewed. Claude's extractions are interpretations, not ground truth.

License

Fork of CZI's Alhazen, originally released under the MIT License.