Obsidian and AI: How to Build a Knowledge Base for AI Agents


Want your AI assistant to work with knowledge from previous projects, technical decisions and your own notes? One approach is to create a structured knowledge base using Obsidian.

Obsidian is a note-taking and knowledge management application that stores information in Markdown files. It lets you organise documents, connect related topics and maintain information outside individual AI conversations.

In this guide, you will learn how to set up Obsidian, create a practical knowledge structure and prepare your notes for use with AI tools such as Claude Code or OpenAI Codex.

We will also explain an important distinction: storing information is not the same as giving an AI agent persistent memory. The agent needs an appropriate way to access, retrieve and, where permitted, update that information.

For questions about a selected set of documents and source citations, see our Gemini Notebook (NotebookLM) guide.





What is Obsidian and how does it work?


Obsidian is a personal knowledge management (PKM) application built around local Markdown files.

Instead of storing notes only in a proprietary online workspace, Obsidian uses ordinary files that can also be opened with other text editors.

Your notes live in a folder called a Vault. A Vault can contain documents, images, attachments and links between related notes.

Three important concepts are:

  • Markdown: a lightweight format for writing structured text.
  • Internal links: connections between related notes using Obsidian’s linking syntax.
  • Graph View: a visual representation of links between notes.

Obsidian can be useful for project documentation, research notes, technical decisions, learning materials and personal knowledge.

However, Obsidian is not an AI agent by itself. Using its notes as context for AI requires an additional workflow or integration.





Why use Obsidian with AI agents?


AI models work with the information available in their current context and through any connected tools. They do not necessarily remember your previous projects, conversations or decisions.

A structured knowledge base helps preserve useful information outside an individual AI session.

Potential benefits include:

  • Project continuity: important information remains available across sessions.
  • Reusable knowledge: notes can support different tools and tasks.
  • Structured context: project goals, constraints and decisions are easier to organise.
  • File ownership: standard Markdown files can be managed independently of the application.
  • Flexible integrations: notes can be processed by scripts, search tools and AI systems.

These benefits depend on how the knowledge base is maintained and accessed. A folder containing hundreds of documents is not automatically an effective memory system.

The AI must be able to find the right information, understand its relevance and distinguish current decisions from outdated notes.





Step 1: Install Obsidian and create a Vault


Start by downloading Obsidian from its official website.

After installation, open the application and choose the option to create a new Vault.

For this guide, name it AI Knowledge Base and choose a suitable location on your computer.

A Vault is simply a folder containing your notes and supporting files. You can open it directly through your operating system’s file manager.

This is useful because other applications may be able to access the same Markdown files, subject to their permissions and configuration.

Practical tip: Start with a local Vault containing non-sensitive example information. Avoid connecting confidential company documents to external AI services before reviewing the applicable security rules.





Step 2: Organise your knowledge base


A simple folder structure is usually enough to begin.

You do not need a complicated knowledge management system before creating your first useful notes.

Consider this example:

AI-Knowledge-Base/
00-Inbox/
01-Projects/
02-Knowledge/
03-Decisions/
04-Templates/
05-AI-Context/

Each folder has a specific purpose:

  • 00-Inbox: new information that has not yet been organised.
  • 01-Projects: active projects and their documentation.
  • 02-Knowledge: reusable technical and business knowledge.
  • 03-Decisions: important decisions and their reasoning.
  • 04-Templates: standard document structures.
  • 05-AI-Context: selected information intended for use with AI tools.

This is a suggested structure rather than an Obsidian requirement.

For a small personal Vault, fewer folders may work better. For a larger team, you may need naming conventions, ownership rules and a review process.





Step 3: Create useful Markdown notes


Markdown makes it possible to write structured documents using plain text.

For example, create a note called AI Assistant Project inside your Projects folder.

Add the following information:

# AI Assistant Project

## Goal
Build an AI assistant that can retrieve information from approved company documentation.

## Technologies
– Large Language Model (LLM)
– Python
– API integration

## Decisions
– Use an approved AI model.
– Apply access controls to source documents.
– Validate answers against available evidence.

## Next steps
– Prepare a representative test dataset.
– Define evaluation criteria.
– Review security requirements.

This example contains a project goal, technologies, decisions and next steps.

The same information can be read by a person or processed by another application with suitable file access.

For important documents, consider adding metadata such as the document owner, status and last review date.

This makes it easier to identify which information is still valid.





Step 4: Connect notes using internal links


One of Obsidian’s useful features is the ability to connect related notes.

For example, a project note might reference another document called AI Governance.

You can create a link using this syntax:

[[AI Governance]]

Obsidian can display backlinks and visualise the connections through Graph View.

This makes it easier to navigate between projects, technologies, policies and decisions.

A project might connect to several other notes, such as:

  • AI Architecture
  • Security Requirements
  • Approved AI Models
  • Project Decisions

Important: Graph View represents links between notes. It does not automatically create a semantic knowledge graph or guarantee that an AI model understands every relationship.

For AI use cases, consistent document structure and relevant retrieval methods remain important.





Step 5: Prepare Obsidian for AI agents


Once your notes are organised, you can consider how an AI agent should access them.

There are three common approaches.

Option 1: Provide notes manually

The simplest option is to copy relevant notes into an AI conversation or provide supported files as attachments.

This requires no additional integration.

It works well for small tasks but becomes less practical as the knowledge base grows.

Option 2: Give an AI tool access to selected Markdown files

Some development-oriented AI tools can work with local files when the environment and permissions allow it.

For example, Claude Code or Codex may be able to read selected Markdown documents from an accessible project directory.

Depending on their configuration, these tools may also propose or perform file changes.

File access must be explicitly configured and controlled. Simply installing Obsidian does not automatically give an AI agent access to your Vault.

Option 3: Build a retrieval system

For larger collections of documents, you may need a dedicated search and retrieval layer.

One approach is Retrieval-Augmented Generation (RAG).

A RAG system retrieves relevant information from external sources and provides it to an AI model as context for generating a response.

RAG is not a built-in capability automatically created by an Obsidian Vault. It requires additional components, configuration and evaluation.





Worked example: Obsidian with Claude Code or Codex


Imagine that you are working on a software project.

You want an AI coding agent to understand the project’s architecture, technical constraints and previous decisions before proposing a new feature.

First, prepare four notes in your Obsidian Vault:

  • Project Overview: goals, scope and requirements.
  • Architecture: technologies, components and integrations.
  • Decisions: approved technical choices and their rationale.
  • Known Issues: limitations and unresolved problems.

Next, make the relevant documents accessible to the AI tool through its supported file-access configuration.

You can then use an instruction such as:

Read the project documentation in the approved knowledge base directory.

Identify the current architectural decisions, technical constraints and known issues.

Based on this information, propose an implementation plan for the new feature.

For each important recommendation, reference the source document.

If the documentation does not contain the required information, clearly identify what is missing.

Do not modify any files at this stage.

The objective is to help the agent base its recommendations on existing project information rather than relying only on the current conversation.

Technical note: Some coding agents use dedicated instruction files. For example, Codex supports AGENTS.md, while Claude Code supports CLAUDE.md.

These files provide project-level instructions. They are not replacements for the full knowledge base.

This is an illustrative workflow. It does not represent a completed benchmark or guarantee identical behaviour across different environments.





Obsidian vs. AI agent memory vs. RAG


These three concepts are related, but they describe different parts of an AI system.

Obsidian is an application for creating, organising and connecting notes. It can act as a source of stored knowledge.

AI agent memory refers to mechanisms that allow an AI system to retain and reuse information across tasks or sessions. A memory system may include retrieval, updates, relevance filtering and retention rules.

Retrieval-Augmented Generation (RAG) is an architecture that provides information retrieved from external sources to a model when generating an answer.

An Obsidian Vault can serve as a knowledge source for a memory or retrieval system.

However, creating a Vault does not automatically provide persistent AI memory, semantic search or reliable information retrieval.

These capabilities depend on the wider system design.





How to keep your AI knowledge base accurate


A useful knowledge base needs more than a good folder structure.

If documents are outdated or inconsistent, an AI agent may use incorrect information even when retrieval works as intended.

Follow these practical rules:

  • Assign ownership: important documents should have a responsible person.
  • Record decisions: explain what was decided and why.
  • Mark outdated information: distinguish historical documents from current guidance.
  • Separate facts from proposals: an unapproved suggestion should not appear as an official decision.
  • Review regularly: establish a process for checking important notes.
  • Control automated updates: important changes should be reviewed before becoming authoritative.

For larger projects, use standard templates that include document status, ownership and review dates.

You should also decide which information an AI agent may update automatically and which documents require human approval.





Security and privacy considerations


Obsidian normally works with local files, giving users control over where their notes are stored.

However, local storage alone does not guarantee security.

When connecting Obsidian to AI tools, consider the following:

  • Access permissions: provide access only to the files required for the task.
  • Sensitive information: check whether documents may be processed by the selected AI service.
  • Cloud synchronisation: distinguish local storage from data transferred to cloud services.
  • Automatic changes: use approval steps, backups and version control where appropriate.
  • Untrusted content: documents may contain malicious or misleading instructions that an AI agent should not follow.
  • Organisational policies: follow internal data classification, security and privacy requirements.

For business use, assess applicable GDPR obligations and the security requirements of each connected service.

If you use Obsidian Sync, review its encryption options. Encryption of synchronised data does not mean that local Markdown files are automatically encrypted.

Do not provide an agent unrestricted access to confidential documents simply because they are stored inside one Vault.





Common mistakes when using Obsidian with AI


  • Creating too many folders: an unnecessarily complex structure makes information difficult to maintain.
  • Keeping outdated documentation: AI may use information that is no longer valid.
  • Missing source references: important claims become difficult to verify.
  • Providing excessive permissions: an agent may access or modify more information than necessary.
  • Confusing notes with memory: stored documents do not guarantee that AI can find and reuse the right information.
  • Skipping evaluation: the retrieval workflow is not tested against representative questions.

Start with a small knowledge base and one clearly defined AI use case.

Expand the system only after confirming that it can retrieve appropriate documents and produce reliable, verifiable results.





Checklist before connecting Obsidian to an AI agent


Before giving an AI tool access to your knowledge base, check the following:

  • Is the intended use case clearly defined?
  • Are the relevant documents accurate and up to date?
  • Does the Vault contain confidential or personal information?
  • Does the agent have access only to the required files?
  • Are reading permissions separated from editing permissions?
  • Can the agent identify the source documents behind its answers?
  • Is there a review process for automated changes?
  • Are important files backed up?

These checks are especially important in business environments and when AI agents interact with documentation related to production systems.





Frequently asked questions

Is Obsidian free to use?


Obsidian can be used for free. Additional services, including official synchronisation and publishing, may require a paid subscription. Check the official website for current terms.

Can Obsidian work offline?


Yes. You can create and manage local notes without an internet connection. Cloud synchronisation and external AI services may require connectivity.

Does Obsidian automatically give AI agents long-term memory?


No. An AI agent needs a configured mechanism to read, retrieve and potentially update relevant information. Obsidian provides a possible knowledge source, not a complete memory system.

Can I use Obsidian with Claude Code or Codex?


Yes, for example by allowing the selected AI tool to access approved Markdown files. The exact workflow depends on the tool, its execution environment and file permissions.

Is Obsidian suitable for business knowledge management?


It can be useful for technical documentation, project notes and structured knowledge. For organisational use, assess collaboration needs, access controls, synchronisation, backups and internal security policies.




Continue learning


Explore more practical resources in our AI Guides or learn about related concepts in the AI Glossary.

For development-oriented AI tools, read our introduction to Claude Code.

If you want to improve the instructions you give to AI agents, start with How to Write a Good AI Prompt.





Explore AI models in the Prompts AI Lab


A well-organised knowledge base can provide useful context, but the quality of AI results also depends on the model and tools used.

In the Prompts AI Lab, we compare AI models using the same assignments. Each model gets one attempt, and we publish the resulting output without further editing.

Explore practical experiments involving applications, games and interactive visualisations.






Want to build an AI assistant using your business knowledge?


Obsidian is one way to organise knowledge. For business applications, it is equally important to design secure document access, retrieval workflows, permissions and information updates.

At Prompts, we help organisations select AI technologies, introduce AI assistants and agents, automate workflows and develop practical AI solutions.

Tell us about your existing documentation, the tools you use and the problem you want to solve. We can discuss a suitable starting point.