# Ars Umbris — Build your agentic knowledge system

by Volvelle Labs

Ars Umbris is a local-first workspace and framework for building domain-specific systems in which people and AI agents work with shared knowledge, methods and apps.

## Inside Ars Umbris

Open a note. Inspect its type. Follow its connections.

Interactive host showcase · AI-generated sample notes · edits reset on reload

## Give your knowledge a structure agents can work with.

Define your own types, connect notes with typed references, and catch missing fields or broken links. The graph stays up to date as your files change.

A type defines the structure. A note puts it to use. Both are files.

### tdg-example-note.type.yaml

```
fields:
  status: [brainstorm, draft, solid]
  conviction?: Number{>=0 & <=1}
```

### example-note.md

```
---
type: tdg-example-note
status: draft
conviction: 0.8
---
```

## One graph. Three layers to build on.

### au-engine: A live, typed graph

Indexes files across repositories, resolves types and references, and reports structural errors. Gives tools and views access to the graph.

Types · References · Diagnostics

### au-host: A malleable IDE

An IDE built from replaceable views over the graph. Its projections, layouts, and themes are yours to configure and extend.

Projections · Compositions · SDK

### au-mcp: A meta-harness for agents

Connect agent harnesses to typed tools, skills, and hooks. Configure sessions through profiles. Includes a Claude Code adapter.

Tools · Profiles · Adapters

## Build the workspace your work needs.

Arrange readers, editors, graphs, and terminals around your work. Configure each view through typed files, or build your own with the SDK we use.

First-party projections in the current host. Availability depends on the workspace composition.

### Read and write

Reader · Editor

Work with documents and their typed properties.

### Follow the structure

Graph · Backlinks · Types

Explore connections, inspect types, and move between related files.

### Work with agents

Terminal · Agent tools

Bring agent sessions and their tools into your workspace.

## Agents grew up on code. Knowledge is next.

# Install Ars Umbris

Please help me install Ars Umbris.

1) Create two folders if they do not already exist:
   - ~/arsumbris/ will hold multiple repositories.
   - ~/.arsumbris/ will hold configurations.

2) Clone the entry-point repository:
   git clone https://github.com/arsumbris/arsumbris.git ~/arsumbris/arsumbris
   If that destination already exists, inspect it before proceeding; do not overwrite it.

3) Read ~/arsumbris/arsumbris/INSTALL.md and follow its current setup process.
   Check prerequisites and explain any changes needed on my machine before making them.


## Links

- [GitHub](https://github.com/arsumbris/arsumbris/)
- [Discord](https://discord.gg/MecBjKZY9d)
- [X / @arsumbrisai](https://x.com/arsumbrisai)
- [YouTube](https://www.youtube.com/@arsumbris)
- [Reddit](https://www.reddit.com/r/arsumbris/)
- [Philosophy](https://arsumbris.ai/philosophy)
- [Contact](mailto:contact-arsumbris@proton.me)

---

# Knowledge you can build on.

Your knowledge should grow with your work. So should the software you use to understand it.

## Give knowledge a structure you can check.

A codebase gives an agent more than text: types, relationships, conventions, and feedback when something breaks. A knowledge base should offer the same.

Typed files make expectations explicit. A claim can require a source. A reference can point to a particular kind of object. Structural checks catch mistakes before another session builds on them. Whether the source supports the claim still takes judgment.

## Build the tools as you build the knowledge.

Your questions change as your understanding grows. You should be able to change the environment with them.

That is what malleable means to us: reshaping the knowledge model, the agent’s methods, and the interface together. When a view or capability is missing, you and your agent can build it. Our app uses the same primitives and SDKs available to you.

## Give each session something lasting to build on.

Conversations end. The work should carry forward.

Repos bring knowledge together with the types, skills, and tools used to work on it. They can depend on one another, letting you reuse a method or vocabulary across projects. Different agent sessions can inspect and revise those durable files, continuing from what came before.

## The art of shadows.

A graph can grow beyond what you can hold in your mind at once. Each projection reveals a part: a document, a map, a set of relationships. Moving between them helps you understand the whole.

Ars Umbris takes its name in homage to ars memoriae, ars combinatoria, and the tradition of building structures to think with. The art of shadows is how we think about shaping the views through which humans and agents understand their work together.

## Your thinking should outlast the tool.

Your repos remain files on your machine. Keep them in Git, open them elsewhere, and keep reading them if you stop using Ars Umbris.

## Start with something you want to understand.

Build the knowledge together, then build the tools you need around it.