Luma

Luma is a portable agent seed: instructions, skills and small tools for useful work, source-backed understanding and continuity across sessions. It runs through an existing file-capable AI agent, with no bundled model runtime.

Use it directly on a question or project, add your own skills and tools, and retain what helps the next session. A Markdown wiki is optional and works with Obsidian or an ordinary editor. Animus is not required.

Initialize

Requires Python 3.9+ for the helpers and an agent with local file access. The download command also uses curl.

Run inside your target directory:

curl -fsSL https://raw.githubusercontent.com/lukeanthony007/luma/main/.agents/tools/luma.py | python3 - init

Then ask your agent:

Read .agents/AGENTS.md, then help me with [your task].

If you need help finding a starting point, ask the agent to use luma-setup. For a collection you want organized:

Use luma-sync to reconcile this directory into a connected wiki. Preserve the original sources.

The initializer installs guidance and tools, adds README routing and configures local-record Git exclusions. Existing files are preserved. Conflicting managed resources stop installation before writes; identical installations make no changes.

Workspace structure

Path	Purpose
wiki/	Optional connected understanding: subjects, relationships, decisions and open questions.
inbox/	Optional temporary messages and worksheets. Outcomes survive clearing handled items.
.agents/sources/<date-time>/	Preserved standalone source evidence and provenance. Inspect existing ownership first.
.agents/skills/	Reusable agent practices.
.agents/tools/	Workspace utilities.
.agents/AGENTS.md	Canonical working agreement.

Directories are created on demand. Keep current work and continuity in established project records; a wiki is not a prerequisite. Optional packages and repositories retain their own ownership. Existing runtime state is never relocated merely to match this layout.

Work and continuity

The working agreement keeps purpose, evidence, useful retention and honest completion available without imposing a fixed workflow. Detailed methods load when needed.

• Work directly: answer or act on the request using available tools and relevant skills, including your own.
• Carry understanding: during ongoing project work, maintain a discoverable source-backed account of what matters, including corrections, decisions and unfinished work. Create the first useful account when needed; a later session consults it and verifies relevant evidence. One-off answers need no record; respect explicit no-write requests.
• Learn selectively: distinguish new knowledge from method changes. Preserve the basis and conditions of a useful lesson, revise the owned resource within authorization, and check later use before claiming improvement.

For knowledge-building work, capture selected sources, comprehend and reconcile their meaning, and maintain connected explanations. A wiki is synthesis, not a relocated source collection. Original evidence stays separate and linked; human edits and meaningful history are preserved.

Skills

• Setup: establish goals and identify useful applications of AI or automation.
• Sync: integrate new or changed material.
• Memory: preserve evidence and verify claim support.
• Wiki: maintain connected explanations and navigation.
• Continuity: retain purpose, progress and open commitments.
• Dream: develop supported connections and clearly identified proposals.
• Inbox: manage structured interactions.
• Comprehension: investigate documents, data and code.
• Collaboration: delegate bounded work and integrate results.
• Configuration: maintain guidance, tools and integrations.

The working agreement routes the agent to the relevant skill.

Capture and check

Preserve explicit source files:

python3 .agents/tools/luma_knowledge.py capture --root . notes/source.md

Check wiki and inbox navigation together, plus captured evidence integrity:

python3 .agents/tools/luma_knowledge.py complete --root .

Add maintained pages outside those directories with --page path.md. JSON reports the exact checked scope. For a narrower edit-time check, use check --root . path.md; that result is not workspace completion.

Capture records UTC timestamps, paths and hashes. Unchanged verified sources are reused; changed sources receive separate versions. Originals remain in place.

Checks are mechanical. They do not establish factual accuracy, source relevance or completeness.

Installation options

Preview installation:

curl -fsSL https://raw.githubusercontent.com/lukeanthony007/luma/main/.agents/tools/luma.py | python3 - init "/path/to/project" --dry-run

Install offline from a local checkout:

python3 .agents/tools/luma.py init --source . "/path/to/project"

For reproducible installation, pin both the downloaded script URL and --ref to the same commit.

Upgrade a recorded installation to a newer Luma source:

python3 .agents/tools/luma.py upgrade --source /path/to/luma "/path/to/project"

upgrade takes the same --source (a checkout or a downloaded .tar.gz archive), --ref and --dry-run options as init, and needs the install record; without one it says to use init. On an installed tree, init either changes nothing (same release) or is refused as a conflicting install (newer release); use upgrade to move an installation to a new release, and status to see what it holds. Luma files and README/ignore blocks that still match the record are replaced; missing ones are reinstalled; files the new source no longer ships are removed when unedited, otherwise left in place and listed as orphaned. Any locally edited Luma file or block stops the whole upgrade with nothing written and the record unchanged: restore the recorded bytes or move the edit into a differently named file, then rerun. Files outside the record are never read or touched.

Inspect an installation without changing it:

python3 .agents/tools/luma.py status "/path/to/project"

The initializer records resource hashes, the hashes of its README and ignore blocks, and the declared source in .agents/luma-install.json. Status reports drift against that baseline, not whether a host loaded the guidance. The record is not a copy of the old source or signed provenance. Existing installations without a record remain usable; differing resources and local adaptations must be reconciled, not overwritten. See installed-resource maintenance.

Harness integration

Agents: read .agents/AGENTS.md first.

Instruction loading and skill discovery depend on the harness. Start by explicitly reading the working agreement; a README link does not automatically load it. Native host checks demonstrated a bounded fresh-process continuation in Codex and OMP. Automatic core loading passed on the tested OMP configuration, but not Codex; broad cross-harness compatibility is not established.

Connector definitions are maintained through luma-config only for an actual integration. .agents/mcp.json is a workspace convention, not a universal host discovery path; native schema, loading and authentication must be checked.

Luma does not configure models, initialize Git or activate background jobs. Search, scheduling and external integrations come from the host environment.

Design direction

The portable agent seed design contains the research basis, proposed architecture, evaluation plan and open decisions. The standalone increment implements the portable entry point, on-demand practice routing, retention guidance and installed-resource inspection. Seed checks and native host checks distinguish tested behavior from remaining limits. Persistent host adapters and Animus integration remain separate future work.

Status

Under active development. Automated checks cover supporting tools; behavioral evaluation remains limited. The first matched host/seed comparison found equal outcomes on small synthetic tasks, with higher token and tool-call effort for Luma. Outperformance and reliable completion across everyday workloads and different harnesses are not established.

The longitudinal comprehension evaluation exposed missing retention and stale accounts, then tested a frozen experimental configuration with a startup-loaded workflow and medium reasoning. It maintained and consulted project understanding across an existing-project replay and a fresh synthetic planning case, while respecting no-write and one-off boundaries. Equal-effort baselines reached the same central decisions; no answer-quality advantage was observed. That exact configuration was not promoted. The later revisions below are distinct experiments, not equivalent or proven replacements.

A later continuation regression found skipped knowledge updates and agent proposals carried forward as if they were user-selected scope. Both a consolidated candidate and the earlier experimental configuration showed this failure. Source-backed decision ownership subsequently recovered the requested scope in a known-case replay, but did not reliably activate retention.

The current source revision combines source-backed ownership with an explicit comprehension-to-retention workflow. Its 32-task known-case regression passed 84 frozen functional checks, and later sessions consulted retained understanding. It still skipped two initial investigations and left two intermediate accounts behind newly delivered evidence before repairing them later. This is experimental guidance, not a demonstrated reliability fix or advantage over a fresh agent. The behavior checks used medium reasoning; Luma does not change the host's effort setting. See the full results and limits. Existing installations and global settings are not automatically changed.

Previous version

The previous Obsidian plugin is retained on archive/obsidian-plugin.

License

See LICENSE.