Software changes. Knowledge doesn't.
And that gap is where things start breaking.
At the WeMakeDevs × AWS Bharat Builds Tour — First Commit, we spent the Build Day at Polaris School of Technology working on a problem that developers eventually face as their codebases grow:
How do we keep the knowledge surrounding a software system in sync with the software itself?
Documentation is easy to write once.
Keeping it correct as the code, APIs, SDKs, examples, tests and behaviour evolve is the difficult part.
A seemingly small change can leave behind:
→ outdated documentation
→ broken examples
→ inconsistent API contracts
→ stale SDK guidance
→ incorrect context for AI agents
→ knowledge that no longer reflects reality
We built Cognis to approach this as a knowledge integrity problem, rather than simply a documentation problem.
What is Cognis?
Cognis is an autonomous behavioral verification engine for codebase contract drift.
Instead of treating a repository as just a collection of source files, Cognis looks at the different pieces of evidence surrounding the software and tries to understand how they relate to one another.
It can inspect things such as:
Source code and ASTs
Documentation
API/schema definitions
Dependencies
Tests
CI configuration
Repository structure
Other evidence discovered during investigation
The system then builds an evidence graph and uses that information to reason about whether the knowledge surrounding the software still matches its actual behaviour.
The flow can be thought of as:
Code change → Behaviour change → Broken promise → Downstream consequences → Knowledge repair
The Cognis Investigation Engine
The heart of Cognis is its investigation engine.
When an investigation begins, Cognis first observes the repository and collects evidence.
That evidence is normalized and connected into the system's understanding of the codebase.
The investigation engine can then:
Reconstruct behaviour from the available evidence.
Identify contracts and expected behaviour.
Detect contradictions or drift.
Trace the consequences of the contradiction.
Use AI reasoning to investigate the evidence. Determine whether a repair is justified.
Verify the proposed change before allowing it to proceed.
This makes Cognis more than an AI chatbot that reads a repository and generates an answer.
The goal is to make the AI reason from evidence about the software, rather than simply relying on what the model thinks should be true.
Ask Cognis
We also built Ask Cognis, an AI assistant that lets developers interact with their codebase conversationally.
It is integrated with Amazon Bedrock, allowing Cognis to use a foundation model as part of its reasoning system.
Instead of asking an AI:
"What do you think this code does?"
the idea is to give it the relevant repository evidence and context and ask it to reason from that information.
This makes the assistant useful not only for answering questions, but also as an interface into Cognis's understanding of the repository.
Self-Healing — With Restraint
One of the ideas we cared about most was restraint.
A system capable of modifying software shouldn't blindly "fix" something just because an AI model believes it knows the answer.
Cognis therefore treats healing as a controlled process.
When a contradiction is detected, Cognis can create a healing transaction, plan a potential change, apply it in a controlled environment, and use verification/regression checks before considering the repair safe.
There is also an important failure condition:
When the evidence contradicts itself, Cognis can refuse to repair automatically.
Because sometimes the smartest action isn't to generate an answer.
It's to stop.
We believe this is particularly important for AI-powered developer tools. Giving an AI the ability to modify software also means giving it the ability to recognize when it doesn't have enough evidence to safely do so.
Repository Architecture
We structured Cognis as a monorepo so that the frontend, reasoning engine and cloud infrastructure could evolve together.
cognis/
│
├── apps/
│ └── web/
│ ├── app/
│ │ ├── dashboard/
│ │ ├── healing/
│ │ └── api/
│ ├── components/
│ │ ├── copilot/
│ │ ├── dashboard/
│ │ ├── healing/
│ │ ├── hero/
│ │ └── scenes/
│ └── lib/
│
├── backend/
│ ├── evidence/
│ │ ├── extractors/
│ │ ├── parsers/
│ │ ├── discovery/
│ │ ├── graph.py
│ │ └── pipeline.py
│ │
│ ├── contracts/
│ │ ├── extractor.py
│ │ └── resolver.py
│ │
│ ├── agent/
│ │ ├── bedrock_client.py
│ │ ├── loop.py
│ │ └── tools.py
│ │
│ ├── verification/
│ ├── healing/
│ │ ├── planner.py
│ │ ├── patcher.py
│ │ ├── transaction.py
│ │ └── immune_memory.py
│ │
│ ├── db/
│ └── orchestrator.py
│
├── infra/
│ └── aws/
│ ├── functions/
│ │ ├── ingress/
│ │ ├── observe/
│ │ ├── engine/
│ │ ├── persist/
│ │ └── status/
│ │
│ ├── statemachine/
│ │ └── pipeline.asl.json
│ └── template.yaml
│
├── docs/
│ ├── ARCHITECTURE.md
│ └── API.md
│
└── .github/
└── workflows/
The major layers are:
Frontend
The Next.js application provides the interactive Cognis experience, dashboard, investigation views, healing interface and Ask Cognis assistant.
Evidence Layer
Discovers and extracts information from source code, ASTs, documentation, schemas, dependencies, tests and CI.
Contract Layer
Extracts and resolves behavioural contracts from the evidence.
Cognitive/Agent Layer
Runs the investigation loop and integrates Amazon Bedrock for AI reasoning.
Verification Layer
Checks proposed changes against relevant verification surfaces.
Healing Layer
Handles planning, patching and transaction tracking instead of allowing uncontrolled file modification.
AWS Runtime Layer
Runs the investigation asynchronously through Lambda and Step Functions while using S3 and DynamoDB for persistent state and artifacts.
AWS Integration
AWS wasn't just added as a deployment target — it forms an important part of Cognis's execution architecture.
Our cloud pipeline is:
Result
Amazon API Gateway
Provides the HTTP interface for starting investigations and retrieving investigation status.
AWS Lambda
The Cognis runtime is divided into separate functions for:
Ingress
Repository observation
Investigation engine
Persistence
Status retrieval
This keeps individual responsibilities isolated instead of putting the entire system into one server.
AWS Step Functions
Step Functions orchestrates the investigation lifecycle:
Observe → Engine → Persist
It also provides retry and failure handling for the individual stages.
Amazon S3
Used for repository and investigation artifacts, allowing the system to work with larger artifacts without putting everything directly into the database.
Amazon DynamoDB
Stores persistent investigation state and Cognis data, including investigation information, evidence-related records, traces and configuration.
Amazon Bedrock
Bedrock provides the foundation-model capability used by Cognis's reasoning layer and Ask Cognis assistant.
AWS SAM
We used AWS Serverless Application Model (SAM) to define the AWS infrastructure as code and deploy the serverless architecture consistently.
Challenges We Faced
Building Cognis meant dealing with several different engineering problems at the same time.
A codebase isn't just source code.
Understanding a behavioural change can require looking at source files, documentation, schemas, tests, dependencies and CI configuration together.
Designing a common evidence model that could represent these different sources was one of the core challenges.
Getting an LLM to produce an answer is relatively straightforward.
Getting it to reason about a repository using structured evidence, contradictions and verification constraints is much harder.
We had to think about how evidence is collected, passed into the reasoning loop and used to determine whether an action is actually justified.
Self-healing sounds simple until the system is actually allowed to modify files.
A bad AI-generated repair can be worse than the original problem.
This is why we designed the healing layer around transactions, confidence thresholds and verification rather than directly overwriting files.
Connecting API Gateway, Lambda, Step Functions, S3, DynamoDB and Bedrock into one workflow introduced another layer of complexity.
IAM permissions, service-to-service communication, model configuration, deployment configuration and asynchronous execution all had to work together.
Repository investigation isn't always an instant operation.
Instead of making the user wait for one long HTTP request, we designed the AWS pipeline around Step Functions and persistent investigation state, allowing the investigation to run independently and the frontend to retrieve its progress/results.
Where Cognis Stands Out
There are already excellent developer tools for individual problems such as documentation generation, dependency analysis, code search, security scanning and AI coding assistance.
Cognis approaches the problem from a different angle.
Rather than asking only:
"Can AI understand my code?"
we ask:
"Can a system continuously determine whether the knowledge surrounding my software is still true?"
The distinction is important.
Most developer tools focus on a particular surface.
Cognis is designed around the relationship between surfaces.
For example: Source Code
│
▼
Behaviour
│
▼
API / Contract
│
├── Documentation
├── Examples
├── Tests
├── SDK guidance
└── AI context
If the implementation changes but the surrounding knowledge doesn't, Cognis treats that as a potential knowledge integrity problem. The second difference is the investigation loop.
Cognis isn't designed to immediately generate a patch whenever an LLM sees something suspicious.
It follows a process closer to:
Observe → Gather Evidence → Detect Drift → Investigate → Assess Confidence → Verify → Repair
And importantly:
Contradictory evidence → Stop
That idea of AI with restraint is central to what we wanted Cognis to become.
The Bigger Vision
The long-term vision is bigger than documentation.
We want Cognis to become a living knowledge layer for software.
A layer connecting software behaviour with everything that depends on understanding that behaviour:
Code ↔ APIs ↔ Documentation ↔ SDKs ↔ Examples ↔ Developer Portals ↔ Tests ↔ AI Agents
As software changes, Cognis could continuously ask:
"What else became untrue because of this change?"
And instead of simply telling the developer that something is wrong, it could provide the evidence, trace the consequences, explain the reasoning and, when sufficiently confident, help restore the affected knowledge safely.
Build Day
This project started as an idea during the WeMakeDevs × AWS Bharat Builds Tour — First Commit at Polaris School of Technology.
We got the opportunity to meet Kunal Kushwaha and Hitesh Choudhary, and learn from the AWS workshop with Jatin Mehrotra, Veeramani and Arkodyuti Saha.
Building alongside developers, learning from people actively contributing to the ecosystem, and turning an idea into a working prototype within the same environment was an experience we'll remember.
Huge thanks to WeMakeDevs, AWS and Polaris School of Technology for creating a space where we could experiment, learn and simply build.
Cognis is our attempt at answering one question:
What if software could tell you when the knowledge around it stopped being true — and safely help restore it?
We're only getting started.