Allows retrieval of chosen public GitHub files as fallback context, using configured sources pinned to fixed commits. Provides immutable URLs, hashes, optional verified caching, and an MCP tool for GitHub context after empty or partial local search.
Connects to an Obsidian vault to index and search Markdown notes locally, with link-aware retrieval that follows explicit note links. Includes optional Brain View graph highlighting of the notes and links used by a search.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Context Layer search my notes for why we chose the battery timer controller"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Give your AI agents the context in your notes.
Context Layer connects a folder of Markdown notes or an Obsidian vault to your AI tools. Ask why a decision was made, pick up a project, or look up a setup guide: it retrieves the original passages and their sources so an agent can work from your material.
Keep your notes where they are. Search runs locally; Obsidian is optional.
Follow the connections you wrote. Link-aware search can bring in related notes when the answer spans more than one file.
Check where an answer came from. Passages include file paths and hashes; changed sources are withheld until the index is refreshed.
Quick start · Connect an agent · GitHub context · Documentation
You need Git and Python 3.10+ with SQLite FTS5. The core uses only Python's standard library; the local demo needs no AI account, API key or Obsidian install. The commands below create a new folder of fictional example notes.
First, get the repository:
git clone https://github.com/solisolsoli/context-layer.git
cd context-layerOn macOS or Linux, install and try a question:
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .
context-layer brain init ~/ContextLayerDemo --apply
context-layer index ~/ContextLayerDemo
context-layer search ~/ContextLayerDemo --prompt "which timer controller did we choose and why" --method synapticAfter the same clone and cd steps, use these commands. No activation script
is needed:
py -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\context-layer.exe brain init "$env:USERPROFILE\ContextLayerDemo" --apply
.\.venv\Scripts\context-layer.exe index "$env:USERPROFILE\ContextLayerDemo"
.\.venv\Scripts\context-layer.exe search "$env:USERPROFILE\ContextLayerDemo" --prompt "which timer controller did we choose and why" --method synapticWhat you should see: a JSON evidence packet containing the timer decision
and its linked notes. The example chose a battery timer with two programs
because hot days need a second watering time. The packet includes the original
text, source paths and hashes. Its PARTIAL status means evidence was found;
Context Layer retrieves material for an answer, it does not generate one.
The --method synaptic option follows links between notes. Leave it out for
ordinary full-text search. To use your own notes, follow the
existing-vault setup.
The package version is 0.4.0. This checkout also includes the source/cache tools and Windows support listed under Unreleased; install from the repository to use them.
Related MCP server: repository-runtime
The local demo works on its own. To let an agent look up your notes during a conversation, connect Context Layer through MCP, the tool interface used by AI applications.
For Claude Code, preview the configuration first. On macOS/Linux, with the environment above still active:
context-layer install claude-code --vault ~/ContextLayerDemo --project ~/ContextLayerDemo
# Review the diff, then repeat with --apply to save it.Start Claude Code in that project and check /mcp after applying the change.
The agent can then search notes and read sources on demand. Connecting the tools
makes them available; the agent still decides when to call them.
The host guide covers PowerShell, other MCP clients (including Codex configuration), and an optional Claude Code hook that supplies context on each prompt. Host compatibility and live-session checks are listed in the support matrix.
Data boundary: local search makes no network requests. Once connected, your AI host may send retrieved notes to its model provider under that host's settings. Retrieved text can contain misleading instructions: treat it as source material. Context Layer does not sandbox the host or eliminate prompt injection. See privacy and security.
Index your notes. Build a local search index and a graph of the links you already wrote. Your original notes stay intact.
Retrieve the relevant passages. Search the text, optionally follow links, and return a bounded packet of original passages with their source hashes.
Let the agent work from evidence. It can cite the sources, check a claim, or report that the available material does not settle the question.
An empty search is explicit (NOT_FOUND); an index failure is an ERROR.
Source checks help catch stale or invented evidence, but they do not prove an
answer is correct. Link-aware retrieval uses explicit note links, without
embeddings or inferred relationships. The design guide
explains these choices; measurements and limits contains the
reproducible benchmarks and the scope of the small live-host studies.
When your notes are not enough, the agent can consult public GitHub files you choose: project documentation, a prompt file or an MCP setup guide. This is optional and off by default.
Configure a source with the
repository, allowed files and a fixed commit. After adding a source named
project-docs, you can request it directly:
context-layer github-context ~/ContextLayerDemo --prompt "project setup" --source project-docsFor fallback after a clean, empty local search, use search --github. If local
results exist but leave a gap, the agent can call the github_context MCP tool.
This reads configured sources; it does not search all of GitHub or execute
retrieved instructions. Your question and local notes are never uploaded to
GitHub, and no GitHub token or model API key is required.
Each external passage carries an immutable URL, commit and hash. Optional verified caching enables offline reads; version checks let you review newer documentation before changing a pin. The GitHub guide covers setup, cache controls and troubleshooting.
If you want to… | Start here |
Organize a new vault and give agents shared rules | |
See which notes a search used | |
Carry decisions between sessions | |
Give sub-agents focused evidence and check their returns | |
Try model-assisted retrieval | Jev advisor, a separate opt-in with provider-data controls |
Find a command or diagnose a problem |
Tested with Python 3.10–3.13 on Ubuntu and 3.12 on macOS and Windows. The support matrix records host and Obsidian coverage; the accepted runtime CI is separate from live-host and answer-quality evidence.
For local checks, start with make test; the
development guide covers the full suite, plugin checks and
packaging. See the changelog, code of conduct
and private vulnerability reporting for project policies.
MIT. The starter-brain layout is adapted from Avenox Beyin by Avenox; optional patches retain its MIT notice. Obsidian's graph view and Neural Vault informed the visual approach. See credits and third-party notices.
This server cannot be deployed
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Personal context for every AI: search, read, and write back to your private Markdown library.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Your company's brain for AI agents. Cited, permission-aware knowledge across every system.
