Skip to main content
Glama

Paracortex

tests

Give your AI agents the context in your notes.

Paracortex is a local search tool that gives AI agents the original passages from your Markdown notes or Obsidian vault, each with its file path and hash.

Ask why a decision was made, pick up a project, or look up a setup guide: it retrieves the passages and their sources so an agent can work from your material, through a command line, an MCP server or a prompt hook. The name means "beside the cortex": a second memory that stays in your own files. Until 0.6 the project was called Context Layer (what changed).

  • 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

Quick start

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/paracortex.git
cd paracortex

On macOS or Linux, install and try a question:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e .

paracortex brain init ~/ParacortexDemo --apply
paracortex index ~/ParacortexDemo
paracortex search ~/ParacortexDemo --prompt "which timer controller did we choose and why" --method synaptic

After 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\paracortex.exe brain init "$env:USERPROFILE\ParacortexDemo" --apply
.\.venv\Scripts\paracortex.exe index "$env:USERPROFILE\ParacortexDemo"
.\.venv\Scripts\paracortex.exe search "$env:USERPROFILE\ParacortexDemo" --prompt "which timer controller did we choose and why" --method synaptic

What 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; Paracortex 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.6.0 (alpha). This version renames the project; the 0.5 command context-layer, import context_layer and host entries written by 0.5 keep working for this release (see the rename guide). Upgrading from 0.4.0? Read the 0.5 migration guide first. Local search still needs no API key.

Related MCP server: repository-runtime

Connect an agent

The local demo works on its own. To let an agent look up your notes during a conversation, connect Paracortex 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:

paracortex install claude-code --vault ~/ParacortexDemo --project ~/ParacortexDemo
# 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. Paracortex does not sandbox the host or eliminate prompt injection. See privacy and security.

How it works

  1. Index your notes. Build a local search index and a graph of the links you already wrote. Your original notes stay intact.

  2. Retrieve the relevant passages. Search the text, optionally follow links, and return a bounded packet of original passages with their source hashes.

  3. 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.

Fill a gap from GitHub

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:

paracortex github-context ~/ParacortexDemo --prompt "project setup" --source project-docs

For 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.

Make it your own

If you want to…

Start here

Organize a new vault and give agents shared rules

Starter brain and daily workflow

See which notes a search used

Obsidian Brain View

Carry decisions between sessions

Source-linked memory

Keep long, multi-agent work resumable: handovers, verbatim decisions, claim status

Working records

Give sub-agents focused evidence and check their returns

Sub-agent workflow

Assess public or synthetic text manually

Decisions API, an opt-in advisory command

Draft a public or synthetic task with an explicit model

Responses API, preview first and send only on request

Preview which route fits a bounded need

Offline API routing, with no API call

Find a command or diagnose a problem

Quickstart, CLI reference, all guides

Support and development

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.

License and credits

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to search, read, and traverse Markdown note vaults (Obsidian-compatible) with full-text search, backlinks, knowledge graphs, and a persistent memory system for cross-session context.
      16
      4 npm
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to search, read, and traverse a local knowledge base of Markdown files using full-text search and relationship graph, reducing token usage.
      MIT
    • F
      license
      A
      quality
      B
      maintenance
      Enables agents to run hybrid dense and BM25 search over a local folder of Markdown files, read and write notes, and trigger reindexing as the folder changes. It also injects the most relevant sections into each prompt automatically and runs entirely locally with a bundled embedding model.
      12
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to semantically search and retrieve content from a local Markdown vault. Provides tools for fetching specific notes and finding related ones via embeddings and wikilinks.
      MIT