Content
# Obsidian Wiki Agent Plugin
An AI agent plugin (compatible with Google Antigravity / Gemini) that enables LLMs to use a local Obsidian vault as a long-term **External Semantic Memory (MSE)**.
By combining a source ingestion MCP server and a semantic linking protocol, this plugin allows AI agents to persist, retrieve, and traverse knowledge across chats, bypassing context window limitations.
---
## 🚀 Key Features
* **Source Ingestion (MCP Scraper)**: Automatically scrapes YouTube video transcripts, descriptions, channels, and thumbnails, saving them directly as raw notes in your Obsidian vault.
* **Semantic memory Protocol (`SKILL.md`)**: Instructs LLM agents to automatically compile raw sources into atomic, interconnected concept cards.
* **Typed Synaptic Links**: Formats connections between concept cards with precise relationship types (`Généralisation`, `Spécialisation`, `Prérequis`, `Tension`, etc.) for seamless agent navigation.
* **Self-Organizing Network**: Guides the agent on when to split (mitosis) large concepts or merge (pruning) duplicate ideas.
* **Activation Map & Activity Log**: Dynamically maintains `index.md` (domain classification) and `log.md` (compilation history) for agentic discovery.
---
## 📂 Folder Structure
The plugin operates on a decentralized, flat Obsidian vault structure:
```
your-vault/
├── raw/ # Temporary sensor memory (input docs)
│ ├── youtube/ # Ingested YouTube video transcripts named after titles
│ └── assets/ # Local thumbnails and images (.jpg, .png)
└── brain/ # Long-term semantic memory (flat folder)
├── index.md # Activation Map (Entrypoint for agents)
├── log.md # Activity Log (Chronological learning history)
├── RAG.md # Atomic Concept Note
└── Notion.md # Atomic Tool Note
```
---
## 🛠️ Installation
### 1. Place the Plugin in your Environment
Clone this repository to your agents customization directory or workspace:
```bash
git clone https://github.com/your-username/obsidian-wiki-plugin.git
```
### 2. Register the Plugin
Ensure the plugin is registered in your `config/plugins` path. The directory should contain:
* `plugin.json` - Plugin metadata.
* `mcp_config.json` - Server registration pointing to `tools/mcp_server.py`.
* `skills/obsidian-wiki/SKILL.md` - Cognitive guidelines loaded by the agent.
### 3. Dependencies
The MCP server automatically tries to install its dependencies on startup. However, you can install them manually:
```bash
pip install yt-dlp youtube-transcript-api requests urllib3
```
---
## ⚙️ Configuration
The MCP server connects via standard stdin/stdout JSON-RPC. It is registered in `mcp_config.json`:
```json
{
"mcpServers": {
"obsidian-wiki-scraper": {
"command": "python",
"args": ["/path/to/obsidian-wiki-plugin/tools/mcp_server.py"]
}
}
}
```
---
## 📖 How to Use
Once installed, the agent will load the instructions and have access to the `obsidian-wiki-scraper` tools.
### 1. Ingesting YouTube Videos
You can tell the agent to scrape a video:
> *"Ingère la vidéo https://www.youtube.com/watch?v=mHxLXzYjQRE"*
The agent will run the `ingest_youtube_video` tool, creating a file under `raw/youtube/` named after the video title containing its metadata, description, and transcript.
### 2. Compiling the Brain
Ask the agent to index the new sources:
> *"Compile les nouvelles sources dans le Cerveau Numérique"*
The agent will:
1. Scan the `raw/` directory.
2. Read the `brain/log.md` to find unprocessed inputs.
3. Generate or enrich atomic notes in `brain/` following the synaptic guidelines.
4. Update `brain/index.md` and log the operations.
