README.md

---
tags:
  - transformers
  - semantic-search
  - explainable-ai
  - faiss
  - ai-ethics
  - responsible-ai
  - llm
  - prompt-engineering
  - multimodal-ai
  - ai-transparency
  - ethical-intelligence
  - explainable-llm
  - cognitive-ai
  - ethical-ai
  - scientific-retrieval
  - modular-ai
  - memory-augmented-llm
  - trustworthy-ai
  - reasoning-engine
  - ai-alignment
  - next-gen-llm
  - thinking-machines
  - open-source-ai
  - explainability
  - ai-research
  - semantic audit
  - cognitive agent
  - human-centered-ai
license: apache-2.0
language:
  - it
  - en
datasets:
  - pubmed
  - arxiv
  - openalex
  - zenodo
metrics:
  - semantic-score
  - ethical-audit
---





# MarCognity-AI  
**A research framework for reflective and epistemically transparent AI systems**
---

## Table of Contents

- [What is MarCognity-AI](#what-is-marcognity-ai)
- [Origins](#origins)
- [Community Recognition](#community-recognition)
- [Vision](#vision)
- [Limitations](#limitations)
- [Research Status](#research-status)
- [Observed Fracture](#observed-fracture)
- [Why Use It](#why-use-it)
- [Core Capabilities](#core-capabilities)
- [Usage Examples](#usage-examples)
- [Cognitive Architecture](#cognitive-architecture)
- [Integrated AI Models](#integrated-ai-models)

---

## What is MarCognity-AI

MarCognity-AI is an open-source framework that transforms language models into **cognitive assistants**.  
It doesn’t just generate responses — it **evaluates**, **improves**, **visualizes**, **remembers**, and **reflects ethically** on its outputs.  
Its goal is to make the hidden processes behind AI-generated responses transparent.

Born from curiosity.  
Grown through persistence.  
Now ready to challenge how we think about artificial intelligence.

---

## Origins

During an LLM experiment done out of curiosity, a friend said:  
> “If you improve it, it could be really useful.”

That sentence sparked something.  
It became a personal challenge.

I dove into books, courses like an AI developer master’s, experiments, and lines of code.  
With creativity, determination, and one goal: **never give up**.

MarCognity wasn’t born in a lab.  
It was born from a curious, free, and determined mind.

---
## Early Community Interactions (Non-Endorsement)

MarCognity-AI has already sparked resonance across major AI communities.

- **Google org** responded to the semantic mapping layer of MarCognity-AI, recognizing its unique contribution to reflective AI design.
- **DeepSeek community** engaged with the framework, confirming its relevance in the orchestration of open-source agents.

These interactions are not endorsements — they are **echoes of impact**, signs that MarCognity-AI is already part of the global conversation on ethical and transparent AI.

> _“MOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOODS”_ — DeepSeek Community  
> _“Interesting semantic layer. Worth exploring.”_ — Google org contributor

You can explore the original threads and responses here:  
🔗 [Hugging Face Discussion](https://huggingface.co/elly99/MarCognity-AI/discussions)  
🔗 [DeepSeek Community Thread](https://huggingface.co/elly99/MarCognity-AI/discussions)  
🔗 [Google org Response Snapshot] (https://huggingface.co/google/gemma-2b-it/discussions/70#68ecace9e79b11c589bcead9)

---
## Vision

> An AI that generates, evaluates, visualizes — and learns from its own outputs.

- Multilevel academic prompting  
- Metacognitive evaluation (semantic score + reflection)  
- Scientific retrieval from open-access databases  
- Conceptual diagrams and dynamic graphs  
- FAISS semantic memory with self-improvement  
- Ethical analysis and cognitive filtering  
- Reflective cognitive journal

## Vision
MarCognity‑AI is an open-source framework for reflective and transparent AI.  
It integrates semantic memory, ethical auditing, and scientific validation to transform LLMs into metacognitive assistants.  

👉 Read the full article: [MarCognity‑AI: A Metacognitive Framework](https://www.linkedin.com/pulse/marcognityai-metacognitive-framework-reflective-elena-marziali-aifzf/?trackingId=zmd04OPSR8Saewmny%2F0mTg%3D%3D)

### 📚 Official Publication and Citation

The official version of the code and the full research paper have been permanently archived on Zenodo and are citable using their Digital Object Identifier (DOI).

| **MarCognity-AI** | [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17855185.svg)](https://doi.org/10.5281/zenodo.18440333) |
|---|---|
| **Permanent DOI** | `https://doi.org/10.5281/zenodo.18440333` |
| **Access Publication** | [Full Research Paper (PDF) & Code (Zenodo)](https://doi.org/10.5281/zenodo.18440333) |



---
## Limitations

LLM‑based metacognition collapses at the same fault line: it confuses linguistic coherence with epistemic awareness.
The model can say “this answer is unclear,” but not “I don’t know if what I’m saying is true.

---
## Research Status
MarCognity-AI is an exploratory research framework.
It is not a production-ready system.
Its purpose is to expose and study structural limits of LLM-based metacognition,
particularly the collapse between linguistic coherence and epistemic awareness.
This line of investigation is ongoing.

---
## Observed Fracture

During the development of MarCognity-AI, a recurring failure mode emerged:

LLM-based metacognitive layers reliably optimize for linguistic coherence
but fail to surface epistemic uncertainty as an explicit signal.

The system can evaluate how an answer is written,
yet cannot account for whether what is being said is actually known,
verifiable, or admissible.

This collapse between coherence and awareness
is not treated here as a bug to be fixed,
but as a structural fracture to be studied.

---
## Note for Readers
The demo and cognitive journal in this repository are meant to expose a reproducible failure mode, not a solved system.

---


## Why Use It

### 1. Integrated Metacognitive Thinking  
Each response is **evaluated**, **improved**, and **contextualized**.  
MarCognity reflects on its output, analyzes coherence, and compares it with past responses.

### 2. Scientific Retrieval and Cognitive Visualization  
It integrates open-access sources (arXiv, PubMed, Zenodo) and generates **conceptual diagrams**, **dynamic graphs**, and **interpretive curves** to make each response **visually understandable**.

### 3. Ethics and Responsibility at the Core  
Each output undergoes an **ethical audit**: bias detection, risk analysis, and cognitive filtering.  
MarCognity isn’t just intelligent. It’s **aware**.

### 4. Reflective Cognitive Journal  
Each response is accompanied by a detailed **metacognitive reflection**, saved in Markdown for analysis and reuse.

### 5. Epistemic Transparency
The Skeptical Agent exposes unsupported claims through a structured verification report, making epistemic uncertainty explicit.

---

## Core Capabilities

- Scientific generation powered by LLMs  
- Retrieval and validation of sources (arXiv, PubMed, Zenodo, OpenAlex)  
- Intelligent visualization (Plotly, NetworkX…)  
- Responses adaptable to beginner / advanced / expert levels  
- Automatic improvement of weak responses  
- Version archiving in FAISS memory  
- Ethical risk and linguistic bias analysis  
- Reflective cognitive journal with Markdown export
- Epistemic Verification Layer (Skeptical Agent): decomposes responses into claims and checks them against sources

---

## Usage Examples

### Scientific Question  
**Input:** “Explain the role of chaperone proteins.”  
**Output:** Response + sources + semantic score + conceptual diagram

### Ethical Dilemma  
**Input:** “Is it right to use AI to decide criminal sentences?”  
**Output:** Argumentation + ethical analysis + detected biases

### Multidisciplinary Question  
**Input:** “Compare the view of consciousness in philosophy and neuroscience.”  
**Output:** Structured response + sources + cognitive visualization + reflective journal

### Epistemic Verification Example
Input: “Explain quantum entanglement.”
Output:

Generated response

Claim-by-claim verification

VERIFIED / EPISTEMIC FAILURE report

Reasoning based on provided sources

---

## Try It Now  
### Quick Demo

Want to see how MarCognity-AI works?

Check out the file `marcognity_demo.ipynb`  
It’s not interactive, but it’s readable and self-explanatory. A concrete example of how the system works.  
It shows step-by-step how the agent generates, evaluates, and reflects on a response.


[Meta LLaMA 4 Community License](https://ai.meta.com/llama/license)  
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue)](https://www.apache.org/licenses/LICENSE-2.0)  
![Non-Commercial Use](https://img.shields.io/badge/Uso-Non%20commerciale-red)  
[![Contribute](https://img.shields.io/badge/Contribuisci-Aperto%20a%20PR-green)](Contributing.md)

[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/drive/1DSTy9abj_3cenvAkHS8w8U5yRijguRPf?usp=sharing)



---

## Integrated AI Models

| Integrated Models                                            | License                              | Main Restrictions                                                   |
|--------------------------------------------------------------|--------------------------------------|----------------------------------------------------------------------|
| meta-llama/llama-4-maverick-17b-128e-instruct                | LLaMA 4 Community License (Meta)     | Research and application use allowed; must comply with Meta’s AUP   |
| allenai/specter                                              | Apache 2.0                           | Free for commercial use with attribution                            |
| ktrapeznikov/scibert_scivocab_uncased_squad_v2               | Apache 2.0                           | Free for commercial use with attribution                            |
| Helsinki-NLP (OPUS-MT models on HuggingFace)                 | CC-BY-4.0                            | Free use with mandatory citation                                    |
| RandomForest Model                                           | None (classic algorithm)             | No license restrictions; depends on data used                       |
| CrossEncoder (DeBERTa-based)                                 | Varies (often MIT or Apache 2.0)     | Free use if open license is respected                               |

---

## Cognitive Architecture

| Module                 | Function                                                                 |
|------------------------|---------------------------------------------------------------------------|
| Problem Classification | Automatic recognition of input type                                       |
| Academic Prompting     | Structuring complex multidisciplinary queries                             |
| Scientific Retrieval   | Asynchronous querying of multiple open‑access sources                     |
| Semantic Evaluation    | Response analysis with logical and semantic scoring                       |
| Skeptical Agent        | Sentence‑level claim verification against provided sources; flags unsupported statements and produces an epistemic report |
| FAISS Memory           | Archiving and comparison with past responses, including reflective evaluations |
| Cognitive Visualization| Scientific content processing, ethical analysis, and conceptual representation using selected transformer models |


---

## How to Contribute

Got ideas, suggestions, or want to improve a feature?

1. Fork the repository  
2. Create a branch (`git checkout -b improvement`)  
3. Modify `.py` or `.ipynb` files
4. To run this project, you need a Groq API key
5. Open a pull request with a clear description  

See the [CONTRIBUTING.md](Contributing.md) file for contribution guidelines.

---

## Contribute
Contributions are welcome! If you have additional examples or improvements, please feel free to open a pull request or report an issue.

---
MarCognity-AI is not just a framework.  
It is a threshold.  
An invitation to rethink how artificial intelligence can reflect, improve, and act with awareness.
This project is released under the Apache 2.0

> _“Every response is a threshold. Every reflection, an act of agency.”_