Akinator AI: The Living Knowledge Layer for Code Repositories — A Comprehensive Guide

10 min read

Key Points

• Akinator AI is an always-on knowledge layer within the repository that makes AI coding agents read the project's intent before modifying it [1].
• It tracks eleven knowledge domains: Product, Business, Requirements, Drift, Architecture, Libraries, Decisions, History, Rules, Skills, and Memory [2].
• Installation takes 30 seconds and requires no change in your workflow — just give your commands naturally [1].
• It solves the core problem in generative programming: loss of context between sessions and repeating errors due to the agent's ignorance of business logic [3].

What is Akinator AI?

Akinator AI is an open-source project developed by Ihab Khaled, aiming to transform the code repository into its own "living wiki." The project's core slogan summarizes the idea: "Code says how. Akinator keeps what, why, who, when, before, now, next" [1].

Unlike traditional coding assistants that only understand code, Akinator focuses on maintaining the full context behind the code: product decisions, business rules, historical context, failures, and the evolving architecture [3].

Note:

Note: The name is borrowed from the famous guessing game Akinator, but the function is completely different — instead of guessing characters, this system ensures that the AI agent knows your project before touching a single file [1].

The Core Problem it Solves

When you rely on "vibe coding" — i.e., development based on text prompts — the AI agent faces recurring problems:

• It doesn't know the business logic of your project
• It doesn't understand the reason for previous decisions
• It is unaware of product requirements and their evolution
• It doesn't know what changed and why
• It loses context between consecutive sessions
• It repeats errors or contradicts previous decisions

Akinator addresses these problems by maintaining a "living wiki" within the repository itself, which the agent reads automatically [1].

The Eleven Knowledge Domains

Akinator tracks specific knowledge domains within the repository, according to the official documentation [2]:

How it Works Technically

Installation in 30 Seconds

On macOS and Linux (for all installed platforms — Claude Code, Codex, and Cursor):

curl -fsSL https://raw.githubusercontent.com/ihabkhaled/akinator-ai/main/install.sh | sh

On Windows (PowerShell 5.1 or later):

irm https://raw.githubusercontent.com/ihabkhaled/akinator-ai/main/install.ps1 | iex

After installation, restart your agent. No manual call is needed — just give your commands naturally [1].

Integration with Platforms

The primary mechanism is the hooks that operate automatically:

• SessionStart hook — injects knowledge and context at the start of the session
• Per-command hook — re-injects relevant context before every user command

This means the agent does not need to be asked to read the documentation — it happens automatically every time [1].

Updating and Uninstalling

• To update: rerun the same installation command
• To uninstall: add --uninstall (or -Uninstall on Windows) — the repository is restored byte-for-byte
• Options: --claude, --codex, and --cursor to choose platforms, and --repo PATH for a custom repository location [1]

How AI is Guided Toward a Better Programming Future

Without Akinator

User: "Add rate limiting to data export"
AI: [modifies files without knowing why the export exists,
     the business rules governing it, or project patterns]

With Akinator

User: "Add rate limiting to data export"
AI: [reads product context, business rules, architecture decisions,
     drift history, library choices,
     then modifies files with full awareness]

The agent understands the intent before the action [1].

Addressing Product Drift

Product drift is the gap between what was originally intended and what the product has become over time. Akinator tracks drift as a first-class knowledge domain [2].

This means that:

• Previous state is recorded (what the product used to be)
• Current state is recorded (what it is now)
• Transition justification is recorded (why it changed)
• Future direction is captured (what comes next)

When the agent makes changes, it can refer back to the drift history to:

1. Avoid reversing decisions that were intentionally changed
2. Understand the context of why the current state differs from original plans
3. Maintain consistency with the product roadmap
4. Identify potential conflicts between a new change and the intended direction

AI Context Support

Traditional programming context is temporary — it exists only in the current conversation. When the session ends, the context is lost.

Akinator creates a permanent context across three levels [1]:

Session Level

• SessionStart hook loads relevant knowledge at the start of the session
• Per-command hook re-injects before every command

Repository Level

• Knowledge lives inside the repository as files
• Version-managed alongside the code
• Grows with every change in the code

Across Sessions

• Memory scope persists across sessions
• History scope maintains the timeline
• Decisions scope preserves justifications

This means a new session begins with full awareness of the project, not with a blank page [1].

Capturing Product Expectations

Product expectations — i.e., what stakeholders expect from the product — are maintained through multiple layers [2]:

When the AI programs a feature, it can verify:

• Does this align with current requirements?
• Does it violate any business rules?
• Does it match the product scope?
• Was this expectation intentionally changed (drift)?
• Was there a previous decision regarding this?

Handling Product and Business Logic Changes

When business logic changes:

1. The change itself is recorded in the history scope
2. The justification is captured in the decisions
3. Drift from the previous logic is tracked
4. The new logic is encoded in the business and rules scopes
5. The agent reads all of this automatically via hooks before the next action

This creates an intent audit trail — not just code changes, but why those changes happened from a business perspective [1].

Generative Programming as an Integrated Company

"Generative Programming" means prompt-based development where you describe what you want and the AI builds it. Akinator elevates this from file-level programming to company-aware programming by giving the agent the same context possessed by a Senior Engineer + Product Manager + Architect [1].

Engineer Knowledge

• Architectural patterns
• Library choices and their reasons
• Coding standards
• Technical decisions and their justifications

Product Manager Knowledge

• Product scope and identity
• Current requirements
• Business rules
• Product drift history

Architect Knowledge

• Structural decisions
• History of constraints
• Why certain patterns were chosen or rejected

Team Memory

• Who decided what and when
• Change history
• Reusable skills and patterns

When you write:

Fix payment retry failure

The AI knows [1]:

• What the payment system does (Product)
• What business rules govern the retry (Business)
• What architecture the payment service uses (Architecture)
• Which libraries are involved (Libraries)
• What decisions were made regarding the retry (Decisions)
• How the retry logic has changed (Drift/History)
• What rules apply to the payment code (Rules)

It programs as if it has been on your team since day one.

Akinator's Twelve-Station Loop

According to the documentation available via the ChatGPT Plugins Guide, Akinator runs every touch of the repository through a twelve-station loop [4]:

1. Ask — Determining what needs clarification
2. Resolve — Addressing ambiguity
3. Audit — Reviewing the current state
4. Plan — Developing a plan for change
5. Execute — Implementing modifications
6. Document — Updating documentation
7. Convert to Skill — Turning repetitive processes into skills
8. Rule — Enforcing lessons as rules
9. Context — Linking the change to the broader context
10. Save — Storing in memory
11. Index and Sync — Keeping routing files synchronized
12. Verify — Final verification in one step

Warning:

Warning: This loop is documented as a concept/demo in the Plugins Guide, and it is not clear from the summary whether a full code version is publicly available within the linked repository [4].

Practical Use Case Scenarios

Scenario 1: Onboarding a New Developer

Command: "Explain how our export system works"

The AI reads the architecture, product, business, and history domains → it provides an answer based on the actual project context, not general knowledge [1].

Scenario 2: Adding a Feature

Command: "Add rate limiting to exports"

The AI reads the current export logic, business rules, architectural constraints, and library choices → it implements rate limiting in a way that fits the existing system [1].

Scenario 3: Fixing a Bug

Command: "Fix payment retry failure"

The AI reads the payment history, previous decisions, drift, and business rules → it fixes the bug without breaking the intended behavior [1].

Scenario 4: Architectural Question

Command: "Why does this service use Redis?"

The AI reads the decisions, architecture, and history domains → it explains the actual justification, not a guess [1].

Scenario 5: Multi-session Continuity

Session 1: "We are migrating from REST to GraphQL"
Session 2 (New): "Complete the API migration"

The AI reads the memory and history → it knows that the migration is underway, what has been accomplished, and what comes next [1].

Benefits Summary

What the Public Documentation Does Not Cover

Based on available evidence from the repository home page and the README file [1, 2], the following details are not publicly documented:

• Internal structure of cognitive scope files
• The exact format of stored knowledge (JSON? Markdown? YAML?)
• How knowledge is updated (manually or via automatic detection?)
• Whether it uses embeddings or keyword matching for context retrieval
• Impact of hooks on command latency
• How conflicts between knowledge inputs are resolved
• Whether it supports monorepos
• Team collaboration features (if any)
• Pricing or licensing details
• How "skills" are defined and reused
• Integration with CI/CD pipelines
• Support for languages other than English

Note:

Note: The docs directory and the skills/akinator directory exist in the repository, but direct access to them was blocked by robots.txt files during this search [8, 9].

Relationship with Ihab Khaled's Other Works

Ihab Khaled maintains several integrated projects:

• ClawAI — A local-first AI orchestration platform that manages open models on the user's device and connects to leading LLM providers [6]. According to the changelog, ClawAI moved in version 0.2.0 from a monolithic architecture to nine independent NestJS microservices with RabbitMQ for asynchronous messaging and Nginx as an API gateway [7].
• AI-Psychiatry — A framework for detecting behavioral drift in AI agents, mentioned in the context of ChatGPT plugins [5].

While ClawAI orchestrates any model used, Akinator ensures that the model understands your project before it acts [1][6].

The Bigger Picture

Akinator AI represents a shift from:

"AI as a code generator" → "AI as a team member with memory"

By embedding project knowledge within the repository and making it automatically available to AI agents, it addresses the fundamental constraint of LLM-based programming: context loss. The agent stops being a tool that needs constant reminding and becomes something that knows your project [1].

This is particularly important for sensitive platforms such as healthcare, where business logic, regulatory requirements, and product drift are critical — making the AI understand why something works a certain way before changing it can prevent compliance issues, data safety problems, and regression errors [3].

Sources

• 1
• 2
• https://www.linkedin.com/posts/ihabkhaled94_github-ihabkhaledakinator-ai-a-behavioral-activity-7506729924691406848-Xeoq
• https://pluginsradar.com/chatgpt/plugins/akinator-788ea07d
• https://pluginsradar.com/chatgpt/developers/ihab-khaled
• https://github.com/ihabkhaled/ClawAI
• https://github.com/ihabkhaled/ClawAI/blob/6a5bc7fb5c0532a90f393c49acaedb8832283f98/CHANGELOG.md
• 8
• 9