Aethel: AI Context & Knowledge Management System
Aethel is a lightweight, provider-agnostic context and prompt management boilerplate for AI agents in solo-developer projects. It separates human-authored rules (Markdown) from an AI-maintained Markdown knowledge layer — a curated index plus a tree of atomic topic files — with no server or external runtime dependency.
1. File Structure
AETHEL.md: Canonical human-written orchestrator — decision routing, RNA-Blueprint plan templates, and critical coding taboos.AGENTS.md: Universal cross-agent entry point. Read natively by most coding agents; it redirects toAETHEL.md.GEMINI.md/CLAUDE.md: Thin redirect stubs (for tools that look for those names) pointing atAGENTS.md/AETHEL.md.CONTEXT.md: Anllms.txt-style index — an H1, a one-line summary, then H2 sections of annotated inline links into the knowledge tree. Curated, not exhaustive; kept under 150 lines.knowledge/: Atomic topic files (one layer / subsystem / bounded context each,name+descriptionfrontmatter). Detail lives here, not in the index. Design decisions are append-only ADRs underknowledge/decisions/NNNN-*.md.aethel.toml(optional): Linter policy — required-header keywords, language rules, spec-sync, and[knowledge]index/orphan settings. Omit to use built-in defaults.
2. The Markdown Knowledge Architecture
Structured knowledge is plain Markdown — there is nothing to install or wire up:
- The index (
CONTEXT.md) maps the project. Each entry is one inline link to a topic file with a one-line note. - Each topic file under
knowledge/is a single unit-of-change and unit-of-retrieval. - Decisions are recorded as numbered ADRs under
knowledge/decisions/.
The linter (aethel lint → check_knowledge_index) keeps the index honest: a relative inline
link that does not resolve on disk is an error; a knowledge/*.md file not reachable from
the index is an orphan warning. External (http(s)/mailto) links and #anchors are
ignored. Use inline links only — reference-style links and autolinks are intentionally not
parsed. Severities are configurable in aethel.toml under [knowledge].
Earlier versions stored structured knowledge in a Memory MCP server /
memory.jsongraph. That layer has been retired in favour of this provider-agnostic Markdown architecture; see knowledge/decisions/0001-retire-memory-graph.md.
3. CLI
aethel init [path] # scaffold a workspace (AGENTS.md, AETHEL.md, CONTEXT.md, knowledge/, ...)
aethel init --recipe python # also deploy a stack-specific linter recipe
aethel update [path] # refresh the managed core block non-destructively
aethel eject [path] # mark the managed core block as sanctioned divergence
aethel eject [path] --undo # remove the eject stamp, restoring managed updates
aethel lint [path] # validate plan/checklist + knowledge-index integrity + hygiene
aethel init also installs a Git pre-commit hook that runs the linter, including the spec-sync
drift guard (code staged without a spec update is flagged — Route C). Escape hatch for an
intentionally spec-irrelevant commit: AETHEL_SKIP_SYNC=1 git commit ....
Metadata
Release files for aethel-cli 1.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| aethel_cli-1.7.0.tar.gz | 92.3 kB | With provenance | Details for aethel_cli-1.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| aethel_cli-1.7.0-py3-none-any.whl | Python 3 | none | any | Details for aethel_cli-1.7.0-py3-none-any.whl |
Total release size: 163.3 kB
Release files / aethel_cli-1.7.0.tar.gz
| Download URL | aethel_cli-1.7.0.tar.gz |
|---|---|
| Size | 92.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3b8964b0aa5a7303d1eaefc81731b5f6877ea062cff4c74fd9d96d2ac36d37fe
|
|
BLAKE2b-256 checksum How to use checksums |
8a78322a86ea68f2b5ca255b062445d65c51bc541a23eafe330c2ad1b2d98517
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logRelease files / aethel_cli-1.7.0-py3-none-any.whl
| Download URL | aethel_cli-1.7.0-py3-none-any.whl |
|---|---|
| Size | 71.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2bdbdcb19254cea0efc9b18010c0958a2cfbd5108937bd11969516caf00520ea
|
|
BLAKE2b-256 checksum How to use checksums |
09819fa1c2e15e2d65e5873fc3ad191c39c86910284666bfe3a206745eccdd0b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logSecurity for aethel-cli 1.7.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for aethel_cli-1.7.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 26, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.