# Contextualise: a research tool built on topic maps

> Contextualise is a Flask application for information-heavy projects that stores topics, notes and occurrences in a topic maps graph rather than in folders, and adds graph, map, timeline and 3D views on top of it. It is MIT licensed, requires Python 3.10, and depends on the author's separate TopicDB engine.

**brettkromkamp/contextualise** — Contextualise is an effective tool particularly suited for organising information-heavy projects and activities consisting of unstructured and widely diverse data and information resources

- Repository: https://github.com/brettkromkamp/contextualise
- Website: https://contextualise.dev/
- Stars: 1,115 · Forks: 41
- Language: Python
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/brettkromkamp-contextualise

## Why a topic map instead of a folder tree

Contextualise is described as a tool for organising information-heavy projects made of unstructured and widely diverse data, with investigative journalism, personal and professional research projects, world building for books, movies or computer games, and many kinds of hobbies given as the situations it suits.

The interesting decision is the data model. Rather than nesting notes in folders, Contextualise describes concepts and the resources that illustrate them, and lets you say how they relate. The README names the intended fields of study: investigative journalists tracing a story, a researcher following a question across sources, a writer building a world where every place, person and artefact has a defined relationship to the others.

A folder tree cannot express the third of those. It can hold a page about a character and a page about a city, but it cannot state that the character was born in that city, that the city appears in a particular chapter, and that both are relevant to a research question. Contextualise treats those statements as first-class objects, which is why the tool ends up with a graph visualisation and an API rather than only a document tree.

The application is written in Python with Flask, MIT licensed, published on PyPI as contextualise, with a project site at contextualise.dev and a repository last pushed on 2026-10-17.

## TopicDB does the real work

Contextualise is not the engine. Its main dependency is TopicDB, an open source topic maps based graph store also written by the same author, and both projects are MIT licensed.

Topic maps provide a way to describe complex relationships between abstract concepts and real-world information resources. In practice the model has three parts. Base names are the abstract concepts, occurrences are the concrete instances of a concept in a given context, and associations are the typed links between them, with role-based members. That is where Contextualise's vocabulary of scopes, base names, topic occurrences and associations comes from.

The distinction is worth pausing on because it drives the interface. A topic is not a page. A topic is a concept, its occurrences are the places that concept shows up, and an association is a statement like this occurrence plays that role in this other concept. Filtering happens along those axes, which is why the README describes flexible filtering of base names, topic occurrences and associations by scope, that is, by context.

Because the graph engine lives in a separate project, Contextualise inherits a real boundary: the Flask application is the interface and the workflow layer on top of a store that can be used on its own.

## Four views over the same data

The README illustrates the application with several screens, and the set says more about the tool's ambitions than the feature list does.

There is a My maps view, which is where a user sees the topic maps they own or have access to, and a topic view, the working screen for a single concept with its notes, its occurrences and its associations. Then there is a navigable network graph visualisation of related topics, and an interactive 3D viewer for the glTF scenes attached to topics.

The graph view is the one that changes the character of the tool. A list of associations is a table, and a table is what you get from a database. A navigable graph makes the shape of the material visible, which is the point for research work where the interesting finding is often a cluster of connections nobody wrote down.

The 3D viewer is a different kind of ambition. Attaching a glTF scene to a topic, and viewing it in place, means a world-building project can hold a model of a place and its notes in the same record, and the AR support for 3D occurrences is listed as an existing feature.

## Notes, files and the details that carry weight

A research tool earns its keep on the small stuff, and the feature list is full of it.

Notes are first class, with extensive support including the ability to attach a note to an existing topic and to convert a note into a topic, which is the operation that turns a stray observation into something you can link to. Topic text and notes are edited in a Markdown based text editor, and syntax highlighting for numerous programming languages comes from Pygments, which matters for a tool that stores code snippets in research notes.

Files can be attached to topics, including images and PDFs. Auto-complete works on all form fields that expect a topic reference, and in-place topic creation lets you create a topic from inside a form instead of navigating away to do it, with quick association creation described as frictionless topic-linking.

Two features stand out as ideas rather than plumbing. Knowledge paths are user-defined, which sounds like a saved traversal through the graph that can be shared. Associative tagging lets a tag be expressed as an association rather than a flat label, so tags participate in the same typed structure as everything else.

Spatial and temporal navigation are also present: a map view that shows a topic in its geographical context and lets you navigate between topics geographically, and a timeline component for navigating between topics over time.

## Sharing a map with other people

Collaboration is described as Google Docs-like, and the mechanism is a permission level per shared topic map. There are three: can view, can comment, and can edit.

Three tiers is a sensible model for research work. Viewing suits a source you want to read, commenting suits a reviewer who has something to add without changing the record, and editing suits a collaborator working in the same map. The README links to a separate write-up on Contextualise collaboration for the detail.

Public topic maps exist as a concept, but with a caveat that is worth knowing before planning a deployment. The README states that public maps are not available to non-admin users until support for dealing with inappropriate content is in place, and it links the open issue. So the shared-space story is currently limited to maps you explicitly share with other Contextualise users, and the public-facing side of the product is gated behind moderation work that has not landed.

The topic map is described as self-contained, and multiple such maps are supported, so the natural unit of collaboration is the map rather than the installation.

## Installing it and pointing it at a settings file

Contextualise is a normal Python package on PyPI, and the README gives the install command and the Python floor:

```bash
pip install --upgrade contextualise
```

Python 3.10 or higher is required. The application is then configured through a settings file rather than environment variables directly, which keeps the secret material out of shell history and process listings.

The file holds three values, shown as placeholders that you must replace with your own tokens:

```python
DATABASE_FILE = "contextualise.db"
SECRET_KEY = "your-secret-key"
SECURITY_PASSWORD_SALT = "your-security-password-salt"
```

The README suggests saving it in your home directory as settings.cfg and pointing the application at it with an environment variable, and it recommends Python's secrets module for generating the two token values:

```bash
export CONTEXTUALISE_SETTINGS=$HOME/settings.cfg
```

The repository also ships a settings-sample.cfg, so the template is available without copying from the README, and the project metadata shows a setuptools build with a ruff configuration setting a line length of 120, plus a uv.lock for reproducible environments.

## What is finished, what is planned and what the tool is not

The README separates existing features from post version 1.0 plans, and the planned list is short and specific: network graph visualisation filtering by association types, full-text search, and WikiMedia API integration to automatically enhance existing topics with information from Wikipedia.

The absence of full-text search in the current feature set is the most consequential gap for a research tool. Everything else on the list is about structure and navigation, and the tool's own authors planned search for after 1.0. Until then, finding material means following the graph rather than typing a phrase, which is a different research habit.

The stack is also worth stating plainly. This is a Flask application on top of a Python graph store with a SQLite database, built with htmx for the interface, and the repository tree has src/, data/, resources/, a settings sample, a MANIFEST.in and a pyproject.toml. There are no GitHub releases, so the PyPI version is the version to track, and the project ships no separate frontend to deploy.

For a single researcher or a small team, the trade is straightforward. You get a structured place to hold material and the relationships between it, with the cost of an opinionated model and a dependency on two projects by the same author.

## Conclusion

Contextualise suits a journalist, researcher or world builder who needs relationships between sources and concepts recorded explicitly rather than implied by folder structure, and who is comfortable with a topic map as the unit of organisation. It is the wrong choice if you need full-text search today, because the README places that among the planned features after version 1.0, and the wrong choice if you need public shared maps, since those stay unavailable to non-admin users until the moderation issue is closed. Verify first that TopicDB and Contextualise versions you pair are compatible, that your notes and files fit the topic and occurrence model rather than fighting it, and that the settings file permissions keep your secret key readable only by the account running the application.

## FAQ

### What is TopicDB and why does Contextualise depend on it?

TopicDB is the author's separate open source topic maps based graph store, and it is Contextualise's main dependency. Topic maps describe relationships between abstract concepts and real-world resources, giving the base names, occurrences and associations that Contextualise presents as topics, scopes and links.

### How do I install Contextualise and configure it?

Run pip install --upgrade contextualise, which needs Python 3.10 or later. Create a settings.cfg holding DATABASE_FILE, SECRET_KEY and SECURITY_PASSWORD_SALT, then point the application at it with export CONTEXTUALISE_SETTINGS pointing at that file.

### What collaboration options does Contextualise offer?

Topic maps can be shared with other Contextualise users in one of three ways: can view, can comment, or can edit. Public topic maps are not yet available to non-admin users, because support for inappropriate content is still an open issue in the repository.

### Does Contextualise have full-text search?

Not yet. The README lists full-text search among the planned post version 1.0 features, alongside filtering the network graph by association types and WikiMedia API integration. Navigation today is through the graph, map and timeline views.

## Sources

- [brettkromkamp/contextualise on GitHub](https://github.com/brettkromkamp/contextualise)
- [Issues](https://github.com/brettkromkamp/contextualise/issues)
- [License: MIT](https://github.com/brettkromkamp/contextualise/blob/master/LICENSE)
- [Project website](https://contextualise.dev/)
- [README](https://github.com/brettkromkamp/contextualise/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/brettkromkamp-contextualise